Walkthrough: Building a Character

This walkthrough takes you from New Character to a saved sheet, then explains what the save quietly creates — a linked player card on your campaign board and item cards for your starting gear. The same builder renders natively inside DNDCards, DND.chat, and DNDWar, so these steps look the same wherever you start.

What you'll need: a signed-in DND account — the builder saves the sheet under your own user. Everything here is free during beta.

Where to start

There are four ways into the builder, and all of them mount the same SharedCharacterBuilderHost wrapper around the published @dnd/character-builder package:

• The character roster at /characters — click New Character.
• An empty roster shelf — the same call to action.
• Your campaign board — start a character in the context of that board.
• A handoff from DND.chat — when chat sends you over to build.

The wizard is identical across all three apps; each app only supplies its own onCreated adapter, which fires the side effects covered at the end.

Step through the wizard

The builder walks the CORE_STEPS in order. Each step has a gate (canAdvance) that must be satisfied before you can move on.

1. Identity — type a name (required, at least 2 characters). alignment is optional.
2. Species — pick a species. If it has subraces, choosing the required subrace is part of the gate.
3. Class — pick your class.
4. Background — pick your background.
5. Abilities — set your six scores by point-buy, standard array, or manual entry. Species that grant a floating ability bump (the MPMM-style "+2/+1 anywhere") add floating ASI picks you must fully assign here.
6. Skills — choose exactly the number of skills your class grants — no more, no fewer.
7. Equipment — take the listed starting gear, or take starting gold instead.
8. Portrait (optional) — generate an AI portrait, upload your own, or skip.
9. Flavor (optional) — add backstory, ideals, bonds, flaws, and quirks.
10. Review — confirm everything, then the primary action saves the sheet.

You cannot advance past a step until its gate passes: a name under 2 characters, a missing required subrace, incomplete floating ASI picks, the wrong number of skills, or unresolved equipment choices will all hold you in place.

What Review computes and saves

When you confirm on Review, the builder runs draftToInsert to turn your draft into a characters row. It computes:

• Final ability scores via applySpeciesAsi (your base scores plus species bonuses and any floating ASI).
• hp_max as your class's maximum hit-die roll plus your CON modifier (startingHp).
• Saves from your class, and speed, languages, and senses from your species.
• Wallet from your equipment choice (gear taken, or the starting gold).
• Flavor columns if you filled them in.

The row is always inserted with user_id = auth.uid(), so the sheet belongs to you under row-level security. See how the apps connect for how that shared data travels between sites.

// The shape draftToInsert assembles before the characters row is written
{
  "name": "Brenna Stonewill",
  "species": "Dwarf",
  "klass": "Cleric",
  "background": "Acolyte",
  "alignment": "Lawful Good",
  "abilities": { "str": 14, "dex": 10, "con": 15, "int": 8, "wis": 16, "cha": 12 },
  "hp_max": 10,
  "ac": null,
  "speed": 25,
  "wallet": { "gp": 15 },
  "user_id": "<auth.uid()>"
}

Side effect 1 — a linked player card

If a campaign is in scope when you save, ensurePlayerCardForCharacter mints a board card in the player category, linked to your sheet by character_id. It prefills the card's stats with your Race, Class, and HP, copies your portrait as the card art, and tags it with source: 'Character'.

The card drops into a preferred list if your board has one — On Deck, In Play, Party, or Players — otherwise it lands in the first list. This is the only way a player card is ever made; you cannot hand-author one. For the full card model, see Cards & the compendium.

Side effect 2 — your starting kit as item cards

Next, ensureStartingKitCards turns the gear you chose into owned item cards on the board, each tagged source: 'Starting equipment'. That's what makes your kit show up in the sheet's Inventory. It only fires if the character doesn't already own any item card, so it won't double-stock you on a re-run.

After you save

• With a portrait, the host routes you straight to your new sheet.
• Without one, it offers CharacterArtOffer — a post-create AI portrait (generated with gpt-image-1 and stored in the card-art bucket). The optional AI flavor blurb uses gpt-4o-mini.

Full sheet editing — leveling, inventory, spell slots, conditions — lives on DNDCards. DND.chat and DNDWar render and play your character, but the sheet's home is DNDCards.

Gotchas

• AC starts as null. draftToInsert never computes Armor Class, so a freshly built character has no AC. Combat falls back to a null AC until a DM edits it in the resolution panel or the sheet sets it later — and the linked player card only includes an AC stat once character.ac is non-null.
• The side effects are idempotent and non-fatal. Both ensurePlayerCardForCharacter and ensureStartingKitCards skip work they've already done — a re-fired onCreated won't duplicate cards. If no board is in scope, they simply do nothing; the character is still created.
• No campaign, no player card. The player card and starting-kit cards only appear when a campaign board is in scope. Build a character with no campaign and you still get a saved sheet, just no board cards yet.

Related: the character roster on DNDCards, the Homebrew Forge guide for authoring custom content your character can use, the adventure format reference, and the FAQ.