Skip to content
Back to search

immersive-character-sheet

Build beautiful, immersive two-page PDF character sheets for tabletop RPG characters (D&D 5e / D&D Beyond): page 1 is an illustrated full-body portrait on a themed background with stats on painted parchment scrolls and laurel ability medallions; page 2 (printed duplex) is a one-page rules reference with the full text of the character's spells, features and items. Use this skill whenever the user wants a character sheet, a "fiche de personnage", a party of sheets, an illustrated/printable RPG sheet, or wants to pull a character from D&D Beyond into a polished hand-out, even if they don't say the word "skill". Vector SVG generated in Python and exported by Inkscape: exact data, no text overflow by construction, about 15 s per character.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/thecoolhippo--dnd-immersive-character-sheet/badge.svg)](/listings/thecoolhippo--dnd-immersive-character-sheet)

HTML

<a href="/listings/thecoolhippo--dnd-immersive-character-sheet"><img src="/api/listings/thecoolhippo--dnd-immersive-character-sheet/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Copy this folder to `~/.claude/skills/immersive-character-sheet/`, or to a project's `.claude/skills/`. Claude picks the skill up when you ask for a character sheet.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 173 lines
  1. ---
  2. name: immersive-character-sheet
  3. description: >-
  4. Build beautiful, immersive two-page PDF character sheets for tabletop RPG
  5. characters (D&D 5e / D&D Beyond): page 1 is an illustrated full-body portrait
  6. on a themed background with stats on painted parchment scrolls and laurel
  7. ability medallions; page 2 (printed duplex) is a one-page rules reference
  8. with the full text of the character's spells, features and items. Use this
  9. skill whenever the user wants a character sheet, a "fiche de personnage", a
  10. party of sheets, an illustrated/printable RPG sheet, or wants to pull a
  11. character from D&D Beyond into a polished hand-out, even if they don't say
  12. the word "skill". Vector SVG generated in Python and exported by Inkscape:
  13. exact data, no text overflow by construction, about 15 s per character.
  14. ---
  15. # Immersive RPG character sheets (v4.3, SVG + Inkscape)
  16. The deliverable is one US-Letter PDF per character, **printed duplex**:
  17. | Page | Content |
  18. |---|---|
  19. | **Recto** | Name and subtitle, combat badges (AC · Init · Speed · HP · Hit Die · Prof), six laurel medallions, and a full-body cutout portrait in front of a themed background. Three parchment scrolls hold the data: **left** has skills, weapons, resources, gear; **right** has spells, features, defenses, proficiencies; **centre** has saves and senses. |
  20. | **Verso** | A three-column rules reference with the **full text** of every spell, class/race feature, background feature, feat, weapon and magic item. Players never need the books or D&D Beyond at the table. **Always exactly one page.** |
  21. The method is a pipeline of scripts, not hand layout. Every number is computed from the D&D Beyond JSON. Every string is measured with the real font before it is placed. The portrait is auto-sized against a mask of the text. Text overflow and a figure covering text are therefore **impossible by construction**. What is left to judge is the art.
  22. ## Requirements
  23. | Tool | Notes |
  24. |---|---|
  25. | Python 3.10+ | `pillow numpy scipy pypdf pypdfium2` |
  26. | Inkscape ≥ 1.2 | Found via the `INKSCAPE` env var, then PATH, then `C:\Program Files\Inkscape\bin\inkscape.exe` |
  27. | Palatino Linotype | Files `pala.ttf palab.ttf palai.ttf palabi.ttf`. The `FONT_DIR` env var defaults to `C:\Windows\Fonts`. Text is measured with these exact files, so the PDF font must be the same. |
  28. | Browser with Gemini | For portraits and backgrounds. Needs a file-upload tool (Claude in Chrome `file_upload`) to send a reference image. |
  29. ## The working folder
  30. All scripts run **from the working folder** (or set `SHEET_WORKDIR`). Each character is one `key`:
  31. ```
  32. work/
  33. <key>.json # raw D&D Beyond JSON (fetch_ddb.py)
  34. <key>.overrides.json # what the API cannot know (see below)
  35. art/<key>_bg.png # background, portrait 3:4 or similar
  36. art/<key>_cutout.png # transparent full-body figure, >= 1600 px tall
  37. ```
  38. Copy the `scripts/` folder anywhere and call them by path:
  39. `python <skill>/scripts/sheet_svg.py <key> [out_dir]`.
  40. ## Phase 1: data (never type a stat by hand)
  41. ```bash
  42. python scripts/fetch_ddb.py <character_id> <key>
  43. ```
  44. This writes `<key>.json` and seeds `<key>.overrides.json`. The character must be **public**; if D&D Beyond refuses, ask the user to make it public. If curl/urllib is blocked, open the URL in the browser and read `document.body.innerText`.
  45. `ddb_parse.py` computes everything else. Dump it with `python scripts/ddb_parse.py <key>.json` and **read the dump against the D&D Beyond sheet**. It covers:
  46. - abilities, PB, AC (armor type, unarmored defense, shield), speed, HP;
  47. - saves, skills (Jack of All Trades), weapons (finesse, Dueling, merged duplicates);
  48. - spell DC, attack, slots and lists;
  49. - features, proficiencies, senses, defenses, gear and money.
  50. Rules are **5e 2014**. Weapon mastery and other 2024 content is ignored. `SKIP_FEATS` drops the campaign boons D&D Beyond attaches to everyone ("Hero's Journey Boon", "Dark Bargain").
  51. `<key>.overrides.json` holds only what the API does not carry (example in `examples/`):
  52. | Key | Use |
  53. |---|---|
  54. | `resources` | Lines for the Resources block, e.g. `"Lay on Hands — 10 HP / long rest"` |
  55. | `feature_labels` | Rename a feature on the recto, e.g. `{"Lay on Hands": "Lay on Hands (10 HP)"}` |
  56. | `defenses_extra` | Extra defense lines, e.g. `"Reroll natural 1s on d20 (Lucky)"` |
  57. | `skip_feats` | Feats to hide on both pages |
  58. | `weapons_replace` | `[{"name","hit","dmg","type"}]` replaces or adds a weapon row |
  59. | `art` | `background`, `figure` (paths relative to the working folder), `glow` (name halo colour) |
  60. ### Characters without D&D Beyond (NPCs, monsters, pregens)
  61. Two optional files in the working folder replace the D&D Beyond JSON:
  62. | File | Effect |
  63. |---|---|
  64. | `<key>.parsed.json` | Used **instead of** `ddb_parse.parse`. Same schema as its output: dump a real character with `ddb_parse.py` and copy the shape. |
  65. | `<key>.entries.json` | Verso sections used instead of `build_entries`: a list of `[title, subtitle, [entries]]`. Each entry is `{"name", "meta", "body": [["p", [[word, "b" or "r"], ...]]], "prio"}`: one pair per word, `b` bold, `r` roman; lowest `prio` is condensed first (0 = generic boilerplate, 4 = keep). |
  66. `<key>.overrides.json` is still read for `art` and the other keys.
  67. ## Phase 2: art (the only manual part)
  68. Details and prompts are in `references/data-and-art.md`. In short:
  69. 1. **Start from the character's existing art**: the D&D Beyond avatar (`decorations.avatarUrl`) or the user's portrait. Upload it to Gemini as a reference. Never generate a face from text alone; it will not match.
  70. 2. **Portrait**:
  71. - full body, tall and narrow (weapons vertical, arms close);
  72. - on a **flat magenta #FF00FF** background (another key colour if the character wears magenta or purple);
  73. - download at full size (≥ 1600 px tall).
  74. 3. **Cutout**:
  75. - `python scripts/normkey.py raw.jpg key.png [--floor] [--wm]` snaps key tints to pure magenta. Add `--floor` if Gemini drew a purple floor gradient and `--wm` if its sparkle watermark is in the bottom-right corner;
  76. - `python scripts/detour.py key.png tmp.png`;
  77. - `python scripts/defringe.py tmp.png art/<key>_cutout.png [erosion]`. Use erosion 3 by default, 1 when there are thin blades or staves.
  78. - Translucent glows (magic auras): `python scripts/glowcut.py key.png out.png` instead of detour/defringe; it unmixes the key colour into soft alpha.
  79. - Magenta reflected in polished armour (holes inside the figure): `python scripts/fillholes.py key.png raw.jpg out.png` keeps them and recolours them as steel.
  80. - Look at the result on a dark background at 100 %.
  81. 4. **Background**: a rich, lit scene themed to the character, with no people in it.
  82. ## Phase 3: build
  83. ```bash
  84. python scripts/sheet_svg.py <key> [out_dir]
  85. ```
  86. The build takes about 0.6 s, plus about 13 s for the two Inkscape exports in parallel. Outputs:
  87. - `{Firstname}_fiche_immersive.pdf` (2 pages, metadata stamped with `SKILL_VERSION`);
  88. - `{Firstname}_fiche_apercu_p1.png` and `_p2.png`;
  89. - a JSON report.
  90. **Recto:** the three scrolls share **one** text scale, binary-searched between 0.7 and 1.25 so the fullest panel just fits. The centre scroll is vertically centred. The figure is fitted on a 0.5 mm grid: largest width and lowest feet that touch no text box, bullet or medallion value, with the head allowed over the medallions' upper rim.
  91. The z-order is background → scrim → header and badges → side scrolls → medallions → figure (drop shadow) → centre scroll. The figure stands in front of the side scrolls and its feet tuck behind the centre one.
  92. **Verso:** the design is deliberately minimal so the text gets the room. It has:
  93. - a parchment field and a double-rule frame;
  94. - filigree corners and three mid-edge ornaments;
  95. - a one-line header;
  96. - three columns separated by thin rules.
  97. The body size is binary-searched between **8.6 pt and 6.5 pt**.
  98. ### Verso rule: page 2 is ALWAYS one page, and generic text goes first
  99. When space is short, generic text is removed **before** shrinking further:
  100. - **Generic class rules** (Spellcasting, Pact Magic, Ritual Casting) repeat the book and add nothing once DC, slots and spells are listed. If the best size is below `COMFORT_PT` (7.2 pt), they collapse to one line (`GENERIC` in `reference_page.py`).
  101. - **Mundane gear descriptions** go next: rope, rations and the like merge into one "Other gear" line.
  102. - Spells, class/race features and magic items keep their full text. They are condensed only if nothing fits even at 6.5 pt. Tell the user if that happens.
  103. If a new class has another boilerplate feature, add it to `GENERIC` with a one-line summary rather than letting it eat space.
  104. ## Phase 4: verify, then look
  105. ```bash
  106. python scripts/verify_sheet.py <key> <pdf> [crop_dir]
  107. ```
  108. It checks:
  109. - 2 pages, US Letter, version stamp;
  110. - the recto text layer contains the computed AC, HP, hit dice, speed and every skill value;
  111. - the name is real text, not rasterised;
  112. - the verso lists every spell;
  113. - distances are in feet;
  114. - the cutout has no magenta residue and is ≥ 1600 px tall.
  115. It must print `ALL CHECKS PASS`. Then **open the saved crops** (face, medallions, verso) and the two preview PNGs, and judge the art: cutout edges, face, colour harmony, verso legibility. Scripts cannot judge art quality. Use `references/checklist.md`.
  116. ## Changing the method
  117. Bump `SKILL_VERSION` at the top of `sheet_svg.py` whenever a script changes, so every PDF says which version made it. Rebuild the `.skill` (zip of this folder without `__pycache__`), test it from an unzipped copy, and keep every copy in sync.
  118. ## Pitfalls already paid for
  119. - **`&` in a path** (e.g. a folder named "D&D") breaks the SVG. Image hrefs go through `img_href()`, which escapes them and makes them relative.
  120. - **PDF size**: Inkscape stores every raster losslessly (about 6 MB per sheet). `pdf_shrink.py` runs at the end of the build. It re-encodes colour channels as JPEG q88 and only the noisy parchment alpha masks as JPEG; crisp figure alpha stays lossless. The result is about 4 MB with no visible change, small enough to e-mail or upload through a browser.
  121. - **Gemini glitches**: look at horns, hands and weapon ends at 100 %. Smeared horizontal streaks happen. Fix them by uploading the image to a new chat with "Reproduce the attached image exactly … with one fix: …".
  122. - **SVG filters rasterise** what they touch. The name halo is a blurred *copy* under the real text, so the name stays vector. Inkscape exports with `export-dpi=200` to keep the PDF around 7 MB.
  123. - **Backslashes in heredoc-generated Python**: `\b` and `\n` turn into control characters. Edit scripts with a file editor or use `chr(92)`.
  124. - **Proficiency markers** compare `value − abilityMod ≥ PB`. Jack of All Trades adds PB/2 everywhere and must not mark every skill as proficient.
  125. - **Spell ranges**: "Self" stays "self", feet only, no metres.
  126. - **Weapon ranges** are shown only for ranged attacks (`attackType == 2`). A rapier must not show "5/5".
  127. - **Inkscape crashes at random** (0xC0000409) when two instances export in parallel. `export_svg` retries automatically; a crash that survives the retries is real.
  128. - **Inventory duplicates** (two "Map or Scroll Case" rows) are merged with summed quantities on both pages. When mundane gear is condensed, **all** of it goes into "Other gear" together.
  129. - **Monk unarmed strike** uses the Martial Arts die and max(Str, Dex). The verso lists carried weapons the character is proficient with, even when they are not equipped.
  130. - **Gemini keeps the pose** of the reference image when you edit it. To change the pose (e.g. a lute held across the body cut by the frame), start a **new chat**, upload the best image as a look reference, and begin with "NEW POSE, do not copy the pose of the attached picture".
  131. - **Gemini**: start each prompt with "Generate an image." (Escape deselects the image tool). Edit in the same conversation ("Edit the last image: …") to keep the face. Downloads can land a few seconds late.
README.md · README · 35 lines
  1. # dnd-immersive-character-sheet
  2. A [Claude Code](https://claude.com/claude-code) skill that builds illustrated, two-page PDF character sheets for D&D 5e (2014 rules).
  3. - **Page 1:** a full-body portrait on a themed background. Stats sit on painted parchment scrolls, with laurel medallions for the ability scores.
  4. - **Page 2:** a one-page rules reference with the full text of the character's spells, features and items. It is meant to be printed on the back.
  5. The pages are vector SVG generated in Python and exported by Inkscape. All data comes from D&D Beyond or a hand-built JSON, never typed by hand. Text cannot overflow, by construction. A validator checks every number against the PDF's text layer.
  6. ## Install
  7. Copy this folder to `~/.claude/skills/immersive-character-sheet/`, or to a project's `.claude/skills/`. Claude picks the skill up when you ask for a character sheet.
  8. ## Requirements
  9. | Tool | Notes |
  10. |---|---|
  11. | Python 3.10+ | `pip install pillow numpy scipy pypdf pypdfium2` |
  12. | Inkscape 1.2 or later | Set the `INKSCAPE` env var or put it on PATH |
  13. | Palatino Linotype | `pala*.ttf`; set the `FONT_DIR` env var if the fonts are not in `C:\Windows\Fonts` |
  14. | An image generator | Used for the portrait and background, e.g. Gemini with a reference image |
  15. ## Workflow
  16. 1. **Data.** `fetch_ddb.py <character_id> <key>` reads a public D&D Beyond character. For NPCs and pregens, write `<key>.parsed.json` and `<key>.entries.json` by hand instead.
  17. 2. **Art.** Generate the figure on flat magenta, then cut it out with `normkey.py`, `detour.py` and `defringe.py`.
  18. 3. **Build.** `sheet_svg.py <key> [out_dir]` takes about 15 s.
  19. 4. **Verify.** `verify_sheet.py <key> <pdf>` must print `ALL CHECKS PASS`. Then look at the previews.
  20. [SKILL.md](SKILL.md) has the full method and the pitfalls already paid for.
  21. ## Notes
  22. - Rules are 5e 2014. 2024 content such as weapon mastery is ignored.
  23. - No artwork ships with the skill. Your characters' art and data stay in your own working folder.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.