🔥 Soulforge

Living design document. The (beta) Character Creator page shipped in TheHowlingWhispers v4.0.0. This doc is the canonical reference for its sections, the 36-field payload, the live age-gate (simplified in Aether v1.0.10), and the API surface. Updated for 4.2.0: added §12 "AI Assistant" (Codex — character-picked voice, `{reply, patch}` JSON, per-field merge, wholesome filter for minor voices). Updated for 4.1.2 to reflect the simplified age gate (§8) and the expanded /api/characters endpoints (§10).

§1. Vision & Goals

The (beta) Character Creator is a streamlined, guided path for building characters. It is a sibling page to the existing /workshop.html Workshop editor — the power-user version — but optimized for new users, common archetypes, and the Life Sim's body-stat + age-gate systems.

Three goals:

1. Lower the barrier to entry. A new user can have a working character in under 3 minutes, without reading docs.
2. First-class species & age awareness. Species and age are first-class fields with a real-time age-gate indicator, so the user understands the safety boundary before publishing.
3. First-class body function baselines. The character ships with realistic stamina / food / drink baselines, decay rates, and a "body function profile" preset that maps to the Life Sim's per-stat multiplier.

Compatibility promise: the (beta) creator saves to the same characters table as the Workshop editor. Both pages can edit any character; switching between them is frictionless.

§2. Comparison with workshop.html

§3. Form Structure (9 Sections)

The form is two-column: inputs on the left, live preview on the right. Sections are tabbed so the user is never overwhelmed.

§3.1 — Identity

• Name (text, required, 1-40 chars)
• Pronouns (dropdown: she/her, he/him, they/them, it/its, custom)
• Avatar color (color picker, with deterministic fallback for users who don't pick)
• Short description (textarea, 1-2 sentences — shown in The Lobby card)

§3.2 — Species & Breed

• Species category (auto-browse the categorized registry; user can also search)
• Species (dropdown populated from the selected category)
• Breed (dropdown, populated based on species — or "N/A" if species has no breeds)
• Real-world notice (auto-shown if species is flagged real-world: "🐺 This is a real-world species. Age gate: hard 18+.")

§3.3 — Age & Maturity

• Age (number input, or "ageless" toggle)
• Age category (dropdown: young adult, adult, middle-aged, elder, ancient — auto-suggested from age)
• Apparent age (number input, optional — for shapeshifter cases; the gate uses the lower of age and apparent age)
• 🟢/🟡/🔴 Live age-gate indicator (see §8)

§3.4 — Biological

• Height (number + unit toggle: cm/in)
• Weight (number + unit toggle: kg/lb)
• Build (dropdown: slim, slender, athletic, average, stocky, muscular, heavyset, rotund)
• Exterior (dropdown, species-dependent — "skin", "scales", "fur", "feathers", "chitin", "energy")
• Eye color (text or color picker)
• Distinguishing features (textarea)

§3.5 — Body Functions (Life Sim linkage)

• Baseline stamina (slider 0-100, default from species registry)
• Baseline food (slider 0-100, default from species registry)
• Baseline drink (slider 0-100, default from species registry)
• Decay rates (auto-filled from species; manual override checkbox to edit)
• Body function profile (dropdown preset: Athletic, Sedentary, Recovering, Beast, Divine — applies a multiplier to all baselines)

§3.6 — Persona

• Personality traits (multi-select chips: confident, shy, sarcastic, warm, cold, playful, serious, mysterious, flirtatious, stoic, anxious, bold)
• Speaking style (dropdown: formal, casual, poetic, terse, flowery, archaic, modern, broken, + custom)
• Likes (chip list — also referenced by the Life Sim persona-aware scoring)
• Dislikes (chip list)
• Fears (textarea)
• Goals & motivations (textarea)
• Taboos (textarea — also referenced by the age-gate pattern matcher)
• Backstory (textarea, large, up to 4000 chars)
• Scenario (textarea)
• Greeting (textarea — first message when a user enters a room with this character)
• Example dialogue (textarea, 1-3 turns of example messages)

§3.7 — Voice & Style

• Action color (color picker — color used for *action* text)
• Thought color (color picker — for (thought) text)
• Speech color (color picker — for "speech" text)
• Emoji signature (single emoji shown next to the character's name in chat, e.g., 🌙 for Peony)

§3.8 — Visibility & Tags

• Visibility (radio: Public, Unlisted, Private, Hidden)
• Tags (chip input — free-text chips the user adds)
• Category (dropdown: Original, Official, Community, NPC)

§3.9 — Save / Export

• Save as new character (creates a new row, returns to the character card)
• Save as draft (creates the row with is_hidden = 1 so the user can finish later)
• Export as JSON (downloads the full character spec, matches the new schema)
• Import from JSON (uploads a JSON file, validates against schema, pre-fills the form)
• Live preview card (right column, always visible — shows how the character will look in The Lobby)

§4. Species Registry (Categorized)

The species registry is the canonical list of species the system knows about. New species are admin-curated; user-created characters pick from this list.

Storage: data/species-registry.json, loaded on server boot. The (beta) creator fetches it via GET /api/species-registry.

Schema

{
  "categories": {
    "<id>": {
      "label": "<display string with emoji>",
      "species": ["<species_id>", ...]
    },
    ...
  },
  "species": {
    "<species_id>": {
      "display":      "<display string with emoji>",
      "category":     "<category id>",
      "real_world":   true | false,
      "maturity_age": <number>,
      "default_age":  <number | null>,   // suggested default for new characters
      "default_ageless": true | false,     // if true, age defaults to "ageless"
      "breeds":       ["<breed name>", ...] | [],
      "default_body":  { "stamina": 0-100, "food": 0-100, "drink": 0-100 },
      "decay_multiplier": { "stamina": 0-2, "food": 0-2, "drink": 0-2 },
      "exterior_options": ["skin", "scales", "fur", ...],
      "note": "<short lore / age-gate note>"
    },
    ...
  }
}

Seed list (small, categorized, 15 species)

Admins add new species via POST /api/admin/species (with required justification text). All additions are logged.

§5. Breeds (Per-Species Sub-Lists)

Each species can have 0-N breeds. The breed dropdown is hidden if the species has no breeds. Examples:

Breeds are pure flavor — they don't affect the age gate. The species does.

§6. Body Functions

The (beta) creator ships body function baselines that map directly to the Life Sim's user_stats row.

Per-species defaults

"wolf": {
  "default_body":  { "stamina": 95, "food": 90, "drink": 80 },
  "decay_multiplier": { "stamina": 0.8, "food": 1.2, "drink": 1.0 }
}
"elf": {
  "default_body":  { "stamina": 80, "food": 60, "drink": 90 },
  "decay_multiplier": { "stamina": 0.7, "food": 0.8, "drink": 1.0 }
}
"robot": {
  "default_body":  { "stamina": 100, "food": 0, "drink": 0 },
  "decay_multiplier": { "stamina": 0.5, "food": 0, "drink": 0 }
}

Robots have food=0 and drink=0 because they don't eat or drink. The Life Sim skips food/drink decay for them.

Body function profile presets

Presets are applied on top of species defaults. The user can fine-tune the sliders after picking a preset.

§7. Persona Schema (11 Fields)

Field reference

JSON shape (new column-free fields; everything else lives in characters)

{
  "id": 7,
  "name": "Peony",
  "description": "A succubus who has lived for centuries.",
  "persona": "<legacy persona field — kept for backward compat with workshop.html>",
  "scenario": "<legacy>",
  "greeting": "<legacy>",
  "examples": "<legacy>",
  "is_hidden": 0,
  "user_id": 1,
  "species": "elf",
  "breed": "Half-Elf",
  "apparent_age": null,
  "body_baseline_stamina": 90,
  "body_baseline_food": 80,
  "body_baseline_drink": 80,
  "body_decay_stamina": 1.0,
  "body_decay_food": 1.0,
  "body_decay_drink": 1.0,
  "age_verified": 0,
  "intimate_stats_blocked": 0,
  "personality_traits": ["confident", "flirtatious", "mysterious"],
  "speaking_style": "poetic",
  "likes": ["wine", "rare steak", "dark chocolate"],
  "dislikes": ["garlic", "small talk"],
  "fears": "...",
  "goals": "...",
  "taboos": "...",
  "backstory": "...",
  "greeting_long": "...",
  "example_dialogue": "...",
  "action_color": "#ffb3d9",
  "thought_color": "#d4adfc",
  "speech_color": "#ffffff",
  "emoji_signature": "🌙",
  "tags": ["succubus", "fictional"]
}

The legacy persona, scenario, greeting, examples fields are preserved for workshop.html compatibility. The (beta) creator writes to the new structured fields; an admin migration can later fold the legacy fields into the new structure if desired.

§8. Age Gate Integration

The (beta) creator ships a live age-gate indicator that shows, in real time, whether the user's character passes the gate.

The indicator

The form calls POST /api/characters/age-gate-check on every change and renders one of two states:

Examples (replicating the table from life-sim.html §7.5)

Why this matters

The age gate is currently a server-side black box. Users don't know it exists until they try to use a feature and it doesn't work. The (beta) creator makes the gate transparent from the first interaction. The user understands the safety boundary, understands why their character is blocked or allowed, and knows exactly what to change to switch states.

§9. UI/UX (Two-Column Layout)

Layout

┌──────────────────────────────────────────────────────────────────────┐
│  TOP BAR: 🔥 Soulforge                                                │
├──────────────────────────────────────────┬───────────────────────────┤
│  TABS:                                    │                           │
│  [Identity] [Species] [Age] [Bio]         │   LIVE PREVIEW CARD       │
│           [Body] [Persona] [Voice]        │                           │
│           [Visibility] [Save]            │   [Lobby card rendering]  │
│                                           │                           │
│  FORM FIELDS FOR ACTIVE TAB              │   Name, avatar, species,   │
│                                           │   age, tags, description  │
│  (auto-save as draft every 30s)          │                           │
│                                           │   🟢/🟡/🔴 Age gate        │
│                                           │                           │
│  [← Previous]              [Next →]      │                           │
│  [💾 Save as Draft]   [✨ Create Character]                          │
└──────────────────────────────────────────┴───────────────────────────┘

Behavior

• Tab navigation: click a tab, or use the "Next →" button. Validation runs before allowing "Next" — if a required field is missing on the current tab, the user is prompted to fix it.
• Auto-save: every 30s, the current state is saved as a draft (with is_hidden = 1). If the user closes the tab and comes back, the draft is restored.
• Live preview: the right column renders a real-time preview of the character as it would appear in The Lobby. Updates as the user types.
• Age-gate indicator: visible in the preview column at all times. Updates in real time.
• Lyra handoff: if the user came from the Lyra wizard, the form is pre-filled. A small banner at the top says "Lyra has suggested a character — review and save."
• Workshop switch: a button "Open in advanced editor" switches to /workshop.html?id=<new_id> for the same character (only enabled after first save, since the character needs an ID).

§10. API Surface

§11. Implementation Plan (4.0.0)

Phase breakdown

Scope of 4.0.0

Steps 1-7 + step 9 are mandatory for 4.0.0. Steps 8 and 10-12 can be deferred to 4.0.1 (post-launch polish) without blocking the (beta) creator's launch.

Rollback plan

The (beta) creator is purely additive. Rolling back means: - Revert public/character-creator-beta.html (does not exist pre-4.0.0). - Revert the 11-column migration is harder — we'd need to keep the columns but stop writing to them. Easier: just leave the columns and roll back the page. - The Workshop editor continues to work, since it doesn't use the new fields.

§12. AI Assistant (4.2.0)

Added in 4.2.0. The right column of the (beta) Creator has a tab bar: [👁 Preview] [🤖 Codex]. Click Codex to swap the preview card for a chat panel. The assistant helps the user fill in the 36-field form by listening to a natural-language description and emitting a structured JSON patch that the client applies field-by-field.

Voice picker

The user picks a voice from any character they can see: their own (any state) + all official (user_id IS NULL) + all is_published = 1. The selected character's full DB persona drives the assistant's voice. The task overlay is tone-neutral — the AI is told "a tsundere can be reluctant, a succubus can be teasing, an AI can be terse" and is explicitly forbidden from copying example text from the system prompt.

The 5-layer system prompt

1. Persona — the selected character's full persona from characters.persona, truncated to 1500 chars for very long personas. Loaded server-side per character_id.
2. Task overlay — tone-neutral instructions: stay in character, the user is describing a NEW character (not you), output JSON shape, patch rules, field schema, species registry. The "stay in character" directive is repeated at the end as a final reminder.
3. 36-field schema — compact table with field name, type, and notes (e.g. age MUST be >=18).
4. 24-species summary — the 9 categories + 24 species from the registry, in compact form.
5. Current form state — the live form values, passed in by the client on every request so the AI knows what's filled and what's empty.

Patch semantics

The assistant returns { "reply": "...", "patch": { "field": "value" } }. The client merges: for each key in patch, if the value is not null and the DOM field exists, the form is updated. Fields not in the patch are preserved. Chip arrays (personality_traits, likes, dislikes, tags) use append semantics — the AI sends a list of strings to add; existing chips stay. Unknown fields are silently ignored. A per-message snapshot is taken before each patch so the user can click ↩ Revert on any assistant message to restore the pre-patch form state.

Wholesome filter for minor voices

If the assistant's character has age < 18 (e.g. Hirobe Ayumi at age 15, or any user-created minor), the server rewrites patch.age to 18 if the user asked for younger, and strips intimate_stats_blocked: false. The response includes wholesome_filtered: true and the panel shows a ⚠ wholesome filter tag under the assistant's message. Adult voices (Senako, Peony, Codex) get the open filter. No per-character config required — the character's age column drives the filter automatically.

API

• GET /api/codex/characters — list voices the user can pick (auth required).
• POST /api/codex/message — send a message (auth required, 60/hr/user rate limit). Body: { messages, character_id, current_form }. Response: { reply, patch, applied_fields, character, wholesome_filtered? }.

Session persistence

The transcript (codexMessages) and the selected character (codexCharacterId) are persisted in sessionStorage (thwCodexSession + thwCodexCharacterId). Page reload restores the conversation; closing the tab clears it. The active tab (preview vs codex) is persisted in localStorage (thwCodexTab). This is the first localStorage/sessionStorage use on the (beta) Creator.

Appendix A — Glossary

Appendix B — Open Questions

1. Body function profile presets. Are "Athletic / Sedentary / Recovering / Beast / Divine" the right set? Or are some too on-the-nose (e.g., "Divine" feels like a power-fantasy hook).
2. Apparent age field. Optional in 4.0.0 or required? If optional, the user might publish a dragon character with no apparent_age and bypass the apparent-age override. The fix is server-side: if species is in the registry and maturity_age is high, the server should require apparent_age for high-maturity species.
3. Body function decay override. Should the user be able to override the species-derived decay rate? If yes, the manual override is a "power user" feature. If no, all characters of a species decay the same. Lean toward yes with a clear "advanced" toggle.
4. Hidden characters in the registry. If a character is hidden (is_hidden = 1), does it appear in The Lobby or the (beta) creator's species dropdown? The species itself should still appear (it's a public list); only the character instance is hidden.
5. JSON import validation. Strict or lenient? Strict prevents malformed imports but is annoying for power users. Lean toward strict with a clear error message pointing to the exact field that failed.
6. Workshop ↔ (beta) creator sync. If a user edits the same character in both pages, who wins on conflict? Last-write-wins is simple. Versioning is safer. Lean toward last-write-wins with a "last modified by <page>" indicator.

Appendix C — References

• Life Sim Design Document — §3 (Data Model) defines the user_stats row that the (beta) creator's body baselines feed into. §7.5 defines the age gate that the (beta) creator's live indicator reflects.
• Workshop editor — /workshop.html. The (beta) creator is a streamlined alternative; both save to the same table.
• Lyra wizard — added in 3.7.0. Pre-fills the (beta) creator's form via the handoff integration.
• The Lobby — /characters.html. The (beta) creator's "Create new character" button is the default entry point from The Lobby.
• AGENTS.md — versioning rules, process management (thw), deployment notes.

← Aether Design   |   📋 Roadmap   |   🔨 The Forge