# Workflow: Starting a New Mod

> The numbered click-path from opening Edit Mode to a named mod of a chosen kind, in its own public GitHub repository, ready to author.

- Source: https://diceytable.com/docs/editor/workflows/new-mod
- Last verified: 2026-10-15

Creating a mod is two decisions: **what you are creating**, and **which GitHub repository its
files live in**. The dialog asks them in that order.

> **You need a GitHub account.** Every DiceyTable mod lives in its own GitHub repository — that
> is where your files are kept safe, with full version history, and where other players load
> them from. If you don't have an account yet, [create one for free](https://github.com/signup)
> before you start; it takes about a minute. Stuck? Ask in the
> [DiceyTable Discord](https://discord.gg/dSs3uv8Nup) — the dialog links it too.

## Steps

1. Open **Edit Mode** — at `/editor`, or the Edit Mode toggle on the `/table` toolbar.
2. If you have no mods yet, the **What are you creating?** dialog opens automatically; otherwise
   choose **File ▸ New Mod…** in the menu bar.
3. Type a **Name**.
4. Choose **what you are creating**. The four kinds are one choice — click a card, or tab into
   the row once and move through it with the arrow keys. The chosen card is filled, outlined and
   ticked, and stays chosen while you read about it.

   | Kind | What it is | Manifest `type` |
   |---|---|---|
   | **Game** | A playable game others can sit at — pieces, decks, seats, rules, scripts. A game *composes* a room and a table rather than containing them. | `game-pack` |
   | **Room** | The space the table sits in: walls, floor, ceiling, lighting, posters, decoration. | `room-pack` |
   | **Table** | The play surface itself: model, colliders, trigger volumes and the seat ring derived from its metrics. | `table-pack` |
   | **Asset pack** | Prefabs, decks, dice and pieces — Definitions a game can place, reusable anywhere. | `component-pack` |

   A new **Game** starts in the platform defaults - the **Modern Room** pack and the **Square
   Table** pack - with its seat ring laid out to match the table. Both are ordinary assignments you
   can change or remove in the Game Editor; see [Assigning a Room or Table](https://diceytable.com/docs/editor/workflows/assign-a-room-or-table#the-platform-defaults-modern-room-and-square-table).

   The panel under the cards describes whichever kind is selected. Where a kind has limits, that
   panel carries a **What a Room can and cannot hold** disclosure (named for whichever kind is selected) — click it to read them:

   - A **Room** currently *reskins a fixed shell* — 18 ft square, 12 ft high, four walls, a floor,
     a ceiling, up to 24 lights and posters. You cannot yet model arbitrary geometry.
   - A **Room** and a **Table** may not contain scripts or table pieces. They are created with no
     script file at all, and publishing one that has acquired a script is refused.

   > **This choice cannot be changed after your first publish.** The kind is part of what other
   > mods depend on, so once a version is published the server refuses to re-publish the same mod
   > under a different kind. Picking again means creating a new mod. The dialog says this once,
   > above the button that commits it.

   You do **not** have to publish any of these. A room, a table or a set of pieces built inside a
   game and kept private needs no packaging at all — and if you change your mind later, the Game
   Editor's **Extract to a pack** lifts it out into its own pack.

   Click **Continue** once you have a name and a kind. Choosing a kind does **not** move you on by
   itself — the Name field stays in front of you until you press **Continue**, and if the button
   is not ready it says which of the two is missing.

5. Decide **which repository it lives in**. If you are not connected yet, the dialog explains
   why a repository is needed and offers **Connect GitHub** (a GitHub OAuth consent popup — see
   [Connect GitHub](https://diceytable.com/docs/mods/publishing/github-setup)) and a **Create a free GitHub account**
   link. **Create** stays unavailable, with the note *"Connect GitHub to create your mod's
   repository."*, until you have connected. Then:
   - **Create a new repository** — the default. Give the repository a name.
     DiceyTable creates it **public**: multiplayer peers load your models and textures straight
     from GitHub without signing in, so a private repository cannot be used in multiplayer. The
     dialog says this before you commit.
   - **Use an existing repository** — pick from a searchable, paginated list of **your own**
     repositories. A repository you have already published a *different* kind of mod from is
     marked with a warning, because a mod's kind cannot change after its first publish.

   There is no "keep it local" option. A mod stored only in your browser is lost for good if the
   browser's data is cleared, and nothing can bring it back.
6. Click **Create Game** / **Create Room** / **Create Table** / **Create Asset pack**. **Back** returns to the kind step with your choice still selected.

## Definition of done

Edit Mode opens on your new, empty mod. For a game, the Hierarchy shows **Room**, **Table**,
**Player Zones (N)** and **Entities (0)** and nothing else (the runtime no longer seeds default
pieces). The Publish dialog shows your repository pre-filled, and your work is checkpointed to its
`wip` branch as you edit.

## Mods created before repositories were required

A mod made with the old **Not yet — keep this local** option has no repository. When you open
one, a **Move to GitHub** dialog explains that local-only mods are no longer supported and why:
its files exist only in that browser, so clearing browser data or switching devices would delete
it with no way to recover it.

1. Connect GitHub if you have not (or create a free account first).
2. Check the **New repository name** — it starts as a slug of the mod's name.
3. Click **Move to GitHub**. DiceyTable creates the public repository, links it to the mod and
   uploads your files, showing each step as it completes.

**Not now** closes the dialog for this tab only; it opens again the next time you open the mod.
**Extract to a pack** never makes a local-only project: it creates the new pack's repository
first, like this dialog does — see [Extract to a pack](https://diceytable.com/docs/editor/workflows/assign-a-room-or-table#extract-to-a-pack).

## If it fails

- **Connect GitHub fails with "not configured".** GitHub publishing has not been set up on this
  server deployment, and no mod can be created until it is. See
  [Troubleshooting](https://diceytable.com/docs/mods/publishing/troubleshooting).
- **Move to GitHub says the name already exists.** You already have a repository with that name;
  type a different one and click **Move to GitHub** again.
- **"Linked to … but the first upload failed."** The mod is on GitHub and linked; only the first
  upload did not finish. It retries automatically as you work, and the status bar shows the last
  checkpoint.
- **The repository list is empty or says you are not connected.** The list is read with *your*
  GitHub authorization, not the server's, so it only works once you have connected GitHub. A
  "not connected" message is exactly that — not an empty account.
- **Continue looks greyed out.** It tells you why: a short note appears beside the button —
  *"Give your mod a name."* or *"Choose what you're creating."* Those are the only two required
  things on the first step. The same note appears beside **Create** on the last step if GitHub is
  not connected yet, or the repository option you picked still needs a name or a selection.
- **A repository in the list is marked with a warning.** You have already published a different
  kind of mod from it. Reusing it would be refused at publish time; pick another repository or
  create a new one.

## See also

- [Assign a room or a table](https://diceytable.com/docs/editor/workflows/assign-a-room-or-table)
- [Connect GitHub](https://diceytable.com/docs/mods/publishing/github-setup)
- [wip and main](https://diceytable.com/docs/mods/publishing/wip-and-main)
- [Anatomy of a mod](https://diceytable.com/docs/mods/getting-started/anatomy-of-a-mod)
