From 2abfe4abd167295e165a087570494b6b56aeed3e Mon Sep 17 00:00:00 2001 From: Parley Hatch Date: Sun, 17 May 2026 11:16:07 -0600 Subject: [PATCH] Initial commit: design docs Working title 'tgame' is provisional. Top-level samples/ and docs/samples/ are gitignored; visual/art pipeline lives outside this repo. --- .gitignore | 2 + docs/00-concept.md | 29 ++ docs/01-core-loop.md | 36 ++ docs/02-roster.md | 60 +++ docs/03-crafting.md | 73 ++++ docs/04-expeditions.md | 65 ++++ docs/05-economy-progression.md | 62 +++ docs/06-asset-pipeline.md | 93 +++++ docs/07-item-cards.md | 163 ++++++++ docs/08-ux-ui.md | 135 +++++++ docs/09-art-style.md | 97 +++++ docs/10-tone.md | 72 ++++ docs/11-setting.md | 58 +++ docs/12-onboarding.md | 97 +++++ docs/13-reveal-choreography.md | 127 +++++++ docs/14-materials.md | 90 +++++ docs/15-audio.md | 132 +++++++ docs/16-engagement-layers.md | 124 ++++++ docs/17-foldins-2026-05-12.md | 410 ++++++++++++++++++++ docs/18-expedition-engagement.md | 308 +++++++++++++++ docs/19-concepts-player-and-ui.md | 53 +++ docs/20-north-star.md | 70 ++++ docs/21-smoke-test-caewins-forge.md | 110 ++++++ docs/99-open-questions.md | 71 ++++ docs/GLOSSARY.md | 562 ++++++++++++++++++++++++++++ docs/README.md | 24 ++ 26 files changed, 3123 insertions(+) create mode 100644 .gitignore create mode 100644 docs/00-concept.md create mode 100644 docs/01-core-loop.md create mode 100644 docs/02-roster.md create mode 100644 docs/03-crafting.md create mode 100644 docs/04-expeditions.md create mode 100644 docs/05-economy-progression.md create mode 100644 docs/06-asset-pipeline.md create mode 100644 docs/07-item-cards.md create mode 100644 docs/08-ux-ui.md create mode 100644 docs/09-art-style.md create mode 100644 docs/10-tone.md create mode 100644 docs/11-setting.md create mode 100644 docs/12-onboarding.md create mode 100644 docs/13-reveal-choreography.md create mode 100644 docs/14-materials.md create mode 100644 docs/15-audio.md create mode 100644 docs/16-engagement-layers.md create mode 100644 docs/17-foldins-2026-05-12.md create mode 100644 docs/18-expedition-engagement.md create mode 100644 docs/19-concepts-player-and-ui.md create mode 100644 docs/20-north-star.md create mode 100644 docs/21-smoke-test-caewins-forge.md create mode 100644 docs/99-open-questions.md create mode 100644 docs/GLOSSARY.md create mode 100644 docs/README.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0b69549 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +samples/ +docs/samples/ diff --git a/docs/00-concept.md b/docs/00-concept.md new file mode 100644 index 0000000..e57bc65 --- /dev/null +++ b/docs/00-concept.md @@ -0,0 +1,29 @@ +# Concept + +A mobile game where the entire game is the **crafting half** of an MMO. No exploration, no avatar walking around a world, no real-time combat. You run a polymath crafting guild from a single screen and everything you see and do feeds back into making things. + +## The pitch + +You're the master of a guild that does *all* the trades — alchemy, smithing, weaving, enchanting, glassblowing, cooking, jewelry, beast-taming, cartography, and more. You hire named adventurers, equip them with gear you craft, send them on AFK expeditions to gather materials, and run the workshops that turn raw ingredients into finished goods. The adventurers are your employees; you never leave the guild hall. + +## Design pillars (working set) + +- **Always something shiny.** Every interaction — completed craft, returned expedition, new applicant, level-up, discovery — produces a moment worth a tap. The game pulses. +- **No grindy skill-ups.** No "craft 300 daggers to level Smithing." Progression comes from *unlocks* (recipes, stations, regions, hires) and *quality bands* (Crude → Common → Fine → Masterwork → Legendary), not repetition. +- **Crafting is the engine.** Every other system exists to feed crafting better inputs or give crafted output a destination. +- **Breadth over depth-per-skill.** Many trades, lots of variety, broad recipe catalog. Pick paths to chase. +- **Pre-rendered, fully offline runtime.** AI tooling lives in production (asset generation on the workstation), not in the shipped game. Game has no network calls except cloud save / future bazaar. +- **Pixel art aesthetic** with Floyd-Steinberg dithering and a palette-locked visual vocabulary — see [09-art-style.md](09-art-style.md). +- **Confident fantasy stylization with muted weight** — WoW × Quake × Machinarium triangulation; substantial enough for adults, accessible enough for anyone — see [10-tone.md](10-tone.md). +- **Generic medieval fantasy setting** with two flavor pockets (gnomish steampunk, dark elf necromancy) for variety without worldbuilding burden — see [11-setting.md](11-setting.md). + +## Reference points + +- **Melvor Idle** — tradeskill breadth and the idle/active hybrid pacing +- **Little Alchemy** — the "what does X+Y make?" discovery loop +- **Shop Heroes / Recettear** — you craft, NPCs adventure +- **Holy Potatoes! We're In Space?!** — crafting for a roving crew of named characters +- **Darkest Dungeon** — named characters with traits/relationships you grow attached to +- **Shadow of Mordor/War** — the roster screen and Nemesis-style relationship texture +- **Merge Mansion** — the tactile mobile satisfaction +- **Crusader Kings** — templated procedural event reports diff --git a/docs/01-core-loop.md b/docs/01-core-loop.md new file mode 100644 index 0000000..99eeed8 --- /dev/null +++ b/docs/01-core-loop.md @@ -0,0 +1,36 @@ +# Core Loop + +The engine that drives the game. Everything else hangs off this. + +``` +Gather (expeditions, AFK, background) + ↓ +Refine + Craft (active sessions, drag-to-station) + ↓ +Equip / Sell / Fulfill Patron Orders + ↓ +Hire & Upgrade Roster, Unlock Stations & Regions + ↓ +Send better-equipped teams to richer zones → better materials +``` + +Crafting is the engine. The meta-game exists to feed crafting more interesting inputs, and to give crafted output a destination. + +## Pacing + +Hybrid active + idle: +- **Active** — when you sit down to play, you're *deciding*: picking ingredients, combining at stations, choosing expedition teams and destinations, managing the roster. +- **Background** — slow processes tick while you're away: expeditions are AFK timer-resolved, long crafts (smelting, fermenting, curing) finish in the background, the hire pool refreshes daily. + +Mobile cadence: pick up for 5–15 minutes, put down, come back later, find new things waiting. Never required to grind. + +## Why this loop + +Each step of the loop is a *pull* into the next: +- You crafted a great dagger? Now equip a soldier with it. +- Better-equipped soldier? Now you can escort gatherers into harder zones. +- Harder zones? Better materials drop. +- Better materials? More interesting crafts available. +- More interesting crafts? Patrons pay more for them, fund the next round of hires. + +No step is a dead end, no step is filler. diff --git a/docs/02-roster.md b/docs/02-roster.md new file mode 100644 index 0000000..4f80b7c --- /dev/null +++ b/docs/02-roster.md @@ -0,0 +1,60 @@ +# Roster + +The minions you hire are persistent named characters, not fungible workers. This is one of the most important design choices — it's where the game gets its heart. + +## Identity + +- Named characters with portraits, traits, backstory blurbs. +- Roster cap of ~10–30 (raises with Guild Rank). +- Killable / loseable in the worst case (see expeditions). +- You grow attached. That's the point. + +## Classes (working set) + +- **Gatherer** — herbalist, miner, hunter, fisher subspecialties; biome-specific yield. +- **Soldier** — escorts gatherers into hostile zones; defends the guild hall in raid events. +- **Engineer** — operates workshops; subspecialties: smith, alchemist, weaver, jeweler, etc. Each unlocks/upgrades a station type. +- **Merchant** — boosts sale prices, unlocks distant markets, runs caravans. +- **Scholar / Cartographer** — generates recipe hints, scouts new zones, deciphers relics. +- **Beastmaster** — tames creatures from expeditions for unique materials and companion bonuses. + +Subspecialties unlock at level milestones. Classes are fixed at hire; subspecs branch later. + +## Traits + +Rolled at hire. Modify outcomes across systems. Examples: +- Greedy (better loot rolls, occasional pocketing) +- Brave (resists fear/morale events, lower retreat chance) +- Lucky (chance to upgrade craft quality band when assisting) +- Devout (better at enchanting, immune to corruption) +- Ill-tempered (rivalry chance, refuses to team with certain trait combos) +- Drunk (random; may sleep through an event, may roll a critical, narratively rich) + +Trait pool gets richer as you go. Some traits are gained or lost via expedition events. + +## Paper-doll portraits + +Layered sprite composition (no runtime AI): +- Base character art in a fixed pose/perspective. +- Gear pieces (helmets, chestpieces, weapons, cloaks, accessories) are transparent overlay sprites in the same pose. +- Engine composes them at runtime: `base + helmet + chest + weapon + ...`. +- Hire-time variety from layered face/hair/skin/costume sprites combined combinatorically — small library, lots of unique-looking applicants. + +Trade-off: characters live in a fixed pose. Standard 2D RPG constraint, fine. + +## Relationships (Nemesis-style texture) + +Emerge from shared expeditions: +- **Bonds** — combat/teamwork bonuses for paired minions. +- **Rivalries** — extra negative event chance when forced together. +- **Mentorships** — XP transfer; senior minions train juniors. +- **Grudges** — refuse to team after a betrayal event. + +Open question: how mechanically deep should this go? Could be flavor only, or could become a real meta-game. + +## Hiring + +- Daily refreshed applicant pool at the Guild Hall. +- Pool quality scales with Guild Rank reputation. +- Each applicant: portrait + name + class + traits + one-line backstory (all from authored pools, combinatorial). +- Hiring costs gold; firing costs a bit of reputation; resignations happen if morale tanks. diff --git a/docs/03-crafting.md b/docs/03-crafting.md new file mode 100644 index 0000000..5f8b515 --- /dev/null +++ b/docs/03-crafting.md @@ -0,0 +1,73 @@ +# Crafting + +The core gameplay loop. Where the player's hands are most of the time. + +## Stations + +Workshops unlock as you hire matching Engineer specialties. Working list: +- Forge +- Alchemy Table +- Loom +- Enchanting Circle +- Kitchen +- Glassworks +- Jeweler's Bench +- Tannery +- Carpenter's Shop + +Each station has tiers (I → V) that you upgrade with materials + a master Engineer. Higher tiers unlock more slots, higher-quality recipes, faster crafts. + +## Mechanic + +Drag ingredients into station slots, hit craft. +- Each station has 3–6 ingredient slots depending on the recipe. +- A finished item typically needs 4–5 components. +- Components are themselves crafted from upstream raw materials. Multi-tier supply chains — see [14-materials.md](14-materials.md) for the materials taxonomy and Raw → Refined → Component → Final pipeline. + +After Craft is hit, the result auto-resolves on the craft's timer. **Master's Touch** ([16-engagement-layers.md](16-engagement-layers.md)) is an optional skill-timing mini-game that runs during the resolution window — two-meter input that nudges quality and crit chance up. Skippable; veteran auto-craft is a first-class workflow. + +### Example: Moonsilver Dagger +Final craft at the Forge: +- Refined Moonsilver Ingot (Forge — from raw moonsilver ore + flux) +- Tempered Hilt (Carpenter's Shop — from seasoned hardwood + bone) +- Wrapped Grip (Tannery — from cured leather + waxed thread) +- Balance Jewel (Jeweler's Bench — from cut gem + silver wire) + +Each component is its own craft. Each upstream material came from gathering or earlier crafts. The player can outsource components to engineer minions running queues, or make them by hand for higher quality. + +## Quality bands + +Crude → Common → Fine → Masterwork → Legendary + +Output quality is a function of: +- Average ingredient quality +- Station tier +- Assigned engineer's skill + subspec match +- Trait modifiers (the Lucky engineer; the Drunk one) +- Luck roll + +Critical successes promote one band. Critical fails demote. Quality drives sale price, equipment effectiveness, and patron contract eligibility. + +## Discovery + +Three ways to learn recipes: +1. **Library research** — Scholars convert time + reagents into recipe unlocks. +2. **Patron / expedition rewards** — recipes drop as loot. +3. **Experimentation** — drag off-recipe ingredients into a station and see what happens. + +Experimentation outcomes: +- Most produce generic byproducts ("Failed Decoction"). +- Some accidentally hit a real catalog recipe → **"New Discovery!"** flourish, recipe added to your book. +- Scholars generate **hints** ("Theora believes moonpetal + ghoul-fang at the alchemy table may yield a sleep draught") — these constrain experimentation enough to keep it fun without removing the joy. + +## Catalog + +The game ships with a fixed catalog of craftable item *recipes* (~500–1000 target). Players don't know all recipes; experimentation reveals which combos map to which catalog entries. + +Crucially, **items are composed visually at runtime from layered sprites** — see [07-item-cards.md](07-item-cards.md). The same recipe instantiated with different component choices, materials, and quality outcomes produces visibly different cards. Two players who craft the same falchion recipe but use different pommel gems get visibly different swords. This means "uniques" are the norm, not the exception. + +## Open questions + +- How do we surface the recipe book without it becoming a spreadsheet? Maybe by-station view, by-discipline view, "in progress" filter? +- How aggressive is the experimentation penalty? Wasting rare ingredients should sting a little but not feel cruel. +- Quality at finished-item level: does it cascade fully from components, or can a great Engineer save a Crude component? Probably some of both. diff --git a/docs/04-expeditions.md b/docs/04-expeditions.md new file mode 100644 index 0000000..e34edc5 --- /dev/null +++ b/docs/04-expeditions.md @@ -0,0 +1,65 @@ +# Expeditions + +How materials, recipes, and trouble enter the game. AFK timer-resolved, no real-time gameplay. + +## Mechanic + +- Pick a destination (zone). +- Pick a team (1 minion solo, or up to N for team expeditions). +- Set off. Time passes (minutes to hours depending on distance + risk). +- They come back with a report — loot, events, possibly injuries or worse. + +## Risk tiers + +- **Safe** — predictable, modest rewards, low variance, no real risk. +- **Standard** — some variance, decent rewards, occasional minor injuries. +- **Dangerous** — high variance, premium rewards, real injury and (rare) death risk. + +Riskier missions need better gear, better team comp, and Soldiers as escort. Soft-gating: you *can* send an underprepared team into the Mire, but they'll come back hurt or not at all. + +## Team composition + +- **Soldiers** required for hostile zones, otherwise penalty. +- **Beastmasters** can pacify creature zones, reduce hazard rolls. +- **Scholars** boost recipe-find rate. +- **Gatherers** boost yield by biome subspec. +- **Merchants** boost found-coin and trade-route bonuses. + +Team comp is its own puzzle separate from gear loadout. + +## Resolution: procedural event log + +No LLM, no runtime AI. Templated text snippets with slot fills: +``` +[hazard, biome=Mire, severity=medium] +"{minion} stumbled into a {creature} nest. {teammate} pulled them out, but {item} was lost in the muck." +``` + +Selected by zone + risk tier + team composition + trait rolls. Templates have conditional branches (different snippet if a Brave minion is present, etc.). Authoring the template pool is real work but standard work. + +## Drops + +See [14-materials.md](14-materials.md) for the materials taxonomy. + +- **Raw materials** (primary) — biome-appropriate; ore, wood, botanicals, bone, hide, etc. +- **Refined / components** (occasional) — when expeditions encounter abandoned camps, ruins, or merchants +- **Recipes** (occasional) — sometimes specific to the zone's flavor +- **Trophies & curiosities** (rare) — relics, artifacts, named weapons, lore items +- **Trait shifts** (sometimes) — minions return changed by what they saw +- **Relationship changes** (always-ish) — who saved whom, who was reckless +- **NPC encounters** (very rare) — recruitable adventurers met on the road + +## Wounds vs. death + +Working position: **wounded by default**, true death only on catastrophic failure in the highest-tier zones. +- Wounded → infirmary for X hours, can't expedition during that time. +- Wounded with Brave trait → shorter recovery, gains scar (cosmetic + flavor). +- Death → permanent loss, with a memorial entry in the Library. + +Reasoning: losing a leveled-up portrait you've grown attached to is brutal. Permadeath everywhere makes players resent the game. Permadeath as the *worst possible outcome of the worst possible expedition* makes it dramatic. + +## Open questions + +- How granular is the destination picker? Region → zone → encounter, or just region → zone? +- Do players watch a real-time progress bar, or does the report just appear on completion? +- Should expeditions chain (a successful expedition opens a follow-up that's only available for 24h)? diff --git a/docs/05-economy-progression.md b/docs/05-economy-progression.md new file mode 100644 index 0000000..bb76e24 --- /dev/null +++ b/docs/05-economy-progression.md @@ -0,0 +1,62 @@ +# Economy & Progression + +What you do with crafted output, and what makes the game advance over time. + +## Market + +Two destinations for finished goods: + +### NPC Merchants +- Always-on, instant sell. +- Base prices, no negotiation. +- Merchants in your roster boost prices and unlock distant markets (better rates for specific item types). + +### Patron Orders +- Specific finished items requested by NPC patrons. +- Often 4–5 component crafts with quality requirements ("Fine or better"). +- Sometimes time-limited. +- Premium rewards: gold, reputation, unique recipes, relics. + +## Patrons + +Named NPC characters with personalities, factions, and grudges with each other. Filling one patron's order well may anger another faction. Patron tier raises with Guild Rank — you start outfitting villagers and end up arming kings. + +Patron board is the main "directed objectives" surface — players who want a quest will look here. + +## Future bazaar (architecturally stubbed) + +Single-player at launch, but designed so a player-to-player **bazaar** (auction house) and **leaderboards** can be added later without a rewrite. See `06-asset-pipeline.md` and a future `architecture.md` for the multiplayer-ready design choices that matter now (stable IDs, event-sourced state, server-shaped local services, signed saves). + +## Progression spine: Reputation / Guild Rank + +One meta-progression bar. Earned from: +- Completed patron orders +- New discoveries (recipes, ingredients, items) +- Masterwork / Legendary crafts +- Notable expedition outcomes +- Achievements + +Each Guild Rank unlocks: +- Max roster size +- Hire-pool quality +- Station tier cap +- Region access +- Patron tier +- Workshop slot count (parallel crafts) + +**No skill bars per minion or per craft type.** Personal mastery is implicit in unlocked recipes, station tiers, and trained engineers — not in numbers that grind up. + +## Dopamine sources (the "always something shiny" rule) + +A non-exhaustive list of moments that should light up: +- Expedition return → loot drop animation, event log opens +- Craft completion → quality reveal, sometimes a critical success flourish +- New recipe discovery → big flourish, item card unveiled +- New applicant at Guild Hall → portrait reveals +- Equipment gear-up → visible portrait change +- Patron order completion → gold + rep payout +- Guild Rank up → unlocks cascade +- Masterwork or Legendary roll → particle effects, named entry in the Library +- Bonded pair surviving a dangerous expedition together → relationship event + +The game's daily rhythm should be a series of these moments, not a series of grinds. diff --git a/docs/06-asset-pipeline.md b/docs/06-asset-pipeline.md new file mode 100644 index 0000000..cb6f26c --- /dev/null +++ b/docs/06-asset-pipeline.md @@ -0,0 +1,93 @@ +# Asset Pipeline + +AI lives in **production**, not in the runtime. The shipped game is fully self-contained, fully offline, no workstation dependency, no API calls, no surprise model regressions in prod. + +## What gets pre-rendered + +The asset library is **atomic components**, not finished items. Items get composed at runtime from layered sprites + shader passes — see [07-item-cards.md](07-item-cards.md). Many effects (glow, foil, holo, corruption, heat haze, frost, holy rays, first-reveal sweep) are pure shaders and need no PNG at all. + +| Asset | Approach | +|---|---| +| Minion base sprites (face/hair/skin) | Layered sprite library | +| Class costume layers | Layered sprites by class + tier | +| Gear overlay sprites (per slot) | Layered sprite library, hundreds of variants | +| Item base silhouettes | ~30–60 per item category (sword, dagger, vial, ring, etc.) | +| Material tints | ~20 per applicable material; applied via shader or pre-baked overlay | +| Component overlays | Pommel gems, hilt wraps, stoppers, labels, engravings — authored once, recombined | +| Effect auras | Per enchantment / effect type | +| Quality frames + flourishes | 5 quality bands + Legendary specials | +| Maker stamps / faction sigils | Per engineer + faction | +| Bespoke Legendary art | Hand-finished art for truly unique named items only | +| Ingredient & raw material sprites | One per ingredient | +| Patron portraits | One per patron + faction set dressing | +| Zone backdrops | One per zone, possibly day/night/weather variants | +| UI, icons, frames, particles | Standard authored assets | +| Audio (music + SFX) | Pre-bundled | + +## How AI fits in + +The workstation (RTX 6000 Ada) runs local diffusion + audio models during **production**. Two distinct concerns: + +### Conversion pipeline (solved, scripted) + +This is what produces consistent palette / resolution / "honest pixel art" output regardless of the source generator's style drift. + +For static assets (items, portraits, backdrops, UI elements): +1. Generate high-res candidate (Flux, z-image, or comparable diffusion model) +2. Downsample to target pixel resolution +3. Apply Floyd-Steinberg dither against the master 256-color palette +4. Optional hand-clean of ambiguous pixels +5. Commit + +For animated sprites (creatures, NPCs, characters in motion): +1. Generate the still character in Flux (locks the design) +2. Animate the still into a video clip with Wan 2.2 (or comparable) +3. Keyframe extract at 4 fps +4. Crop and convert each frame through the palette-quantize step +5. Commit as sprite sheet + +This is fully programmatic — see `samples/` for a real output of this pipeline (the skeleton attack frame). + +### Prompting discipline (ongoing, not a script) + +Style consistency, character consistency, mood, composition, perspective, framing — these are *prompting* concerns, not pipeline concerns. The conversion pipeline cannot rescue a wrong-feeling prompt; it can only normalize color and resolution. + +This means: +- Lock prompt templates per asset type (a "workshop interior backdrop" prompt template; an "enemy creature attack pose" template; a "minion bust portrait" template) +- Use LoRAs / IP-Adapter / character reference for character consistency across animations and gear updates +- Curate aggressively at generation time — bad source compositions stay bad after dithering +- Maintain a prompt library / prompt cookbook alongside the asset library + +**The prompting discipline is the ongoing art direction work. The pipeline just guarantees the floor.** + +### Audio + +Local audio gen (musicgen or similar) for ambient beds and SFX, following the audio direction in [10-tone.md](10-tone.md). Same conceptual split: prompting/curation matters, downstream encoding/normalization is automatable. + +No part of any pipeline runs on the player's device or talks to a server during play. + +## Bundle strategy + +Composition collapses asset volume substantially compared to authoring finished items. +- Rough order of magnitude (post-composition shift): ~60 item bases × ~10KB + ~20 material tints + ~150 component overlays × ~5KB + ~40 effect auras + ~300 minion portrait elements + 50 zones + UI/audio. Order of tens to low hundreds of MB rather than several hundred. +- Likely approach: **base bundle + on-demand asset packs per region/discipline** so first launch is fast and the player downloads more as they unlock. +- Texture atlasing for the sprite-heavy parts (component overlays, gear overlays, item bases). +- Bespoke Legendary art lives in its own pack, downloaded as Legendaries are first encountered. + +## Minimum viable content for v1 + +Don't try to ship the full catalog at launch. A playable v1 is more like: +- 1–2 regions with ~5 zones total +- 3 stations (Forge, Alchemy Table, Loom — covers most fantasy crafting cliches) +- ~150 catalog items +- ~20 gear overlays per slot +- ~40 minion portrait permutations +- 1–2 patron arcs + +Then expand by content patch. + +## Open questions + +- How much hand-finishing per AI-generated asset before it ships? (Quality bar matters more than volume.) +- Style consistency across thousands of assets — do we lock to one diffusion model + one LoRA stack and never change, or accept some drift? +- Audio: original score or licensed loops? diff --git a/docs/07-item-cards.md b/docs/07-item-cards.md new file mode 100644 index 0000000..8eaaa8b --- /dev/null +++ b/docs/07-item-cards.md @@ -0,0 +1,163 @@ +# Item Cards & Visual Composition + +Items aren't authored as finished PNGs. They're **composed** at runtime from a stack of layered sprites driven by the item's actual components, materials, quality, and effects. The player's crafting choices show up visually. + +This is the trick that lets the game have functionally infinite visual variety from a finite asset library. + +## Layer model + +Most items render as a card with these layers, bottom to top: + +``` +1. Card frame — quality band (Crude / Common / Fine / Masterwork / Legendary) +2. Background — effect or material flavor (forge ember, poison mist, + holy rays, cursed shadow) +3. Base silhouette — the item type (longsword, dagger, vial, ring, helmet) +4. Material tint — primary material (moonsilver sheen, obsidian gleam, bronze) +5. Component overlays — per-slot: pommel gem, hilt wrap, stopper, label, + engraving — driven by the actual components used +6. Effect aura — enchantment (poison wisp, fire flicker, curse, + holy radiance) +7. Quality flourish — Masterwork particle, Legendary frame glow +8. Stamps / marks — maker's mark (engineer who crafted it), faction sigil +``` + +Each base item sprite defines **anchor points** for component overlays — pommel anchor, blade anchor, stopper anchor, etc. Components are authored to land on those anchors, so the gem inhabits the pommel rather than floating beside it. + +## Examples + +### Lapis-infused Moonsilver Falchion (Fine) +- Frame: Fine (silver border) +- Background: faint blue arcane glow +- Base: falchion silhouette +- Material tint: moonsilver pale-blue sheen +- Component overlay: lapis lazuli at pommel anchor +- Engraving overlay: frost rune +- Aura: cold mist +- Stamp: Theodric's maker's mark + +### Cursed Ruby-binding Black Draught (Masterwork) +- Frame: Masterwork (gold) +- Background: deep crimson swirl +- Base: rounded apothecary vial +- Material tint: liquid opaque black with red glints +- Component overlay: bone stopper, red wax seal, ruby fragment in liquid +- Aura: dark heat-shimmer +- Flourish: drifting particles +- Stamp: Theora's apothecary mark + +The player sees both items and immediately knows which components went into each. Crafting decisions are visible. + +## Why this is the right call + +- **Asset count collapses.** ~30 base silhouettes × ~20 material tints × ~30 component overlays × ~15 effect auras × 5 frames = combinatorial variety from a small authored library. +- **Crafting becomes visually expressive.** Every craft choice has visible consequence — the strongest feedback loop possible. +- **Functionally infinite uniques.** Even when a recipe is shared, your specific instance has your specific components, engineer stamp, and quality. No one else's is identical. +- **Future bazaar gets richer.** Listings show full composed cards, browsing becomes part of the fun. +- **Names compose too.** `[quality adjective] [material] [base] of [effect noun]` gives Diablo-style procgen names from the layer stack itself. + +## Tradeoffs + +- **Consistency burden.** Components must be authored to compose cleanly — same perspective, same lighting direction, same scale, same color discipline. Strict style guides + a composition test step before any new component ships. +- **Color clashes.** Lapis blue + ruby red on one sword can look muddy. Either gameplay-prevent it via recipe constraints, or lean into it as visual feedback that the craft is unstable. +- **Reserve bespoke art for Legendary or named items.** When the player discovers a truly unique recipe — *Crucible-Forged Sun-Sword of Aelis* — that one gets full hand-finished treatment. Composition for 99%, bespoke for 1%. + +## Rendering: alpha layers + shader passes + +Composition isn't flat sticker-stacking. Every layer carries an alpha channel and lower layers bleed through where higher ones are transparent. Atmosphere layers (swirling shadows, drifting mist, dust motes) sit between solid layers and add depth without hiding the base art. + +After the layer stack composes into a single card texture, **post-process shaders** run on the composed result. Many effects need no PNG asset at all — they're pure fragment shaders. + +### Pass model + +``` +Pass 1 — Layer composite (alpha-aware) + frame → background gradient → atmosphere overlay (alpha) → + base silhouette → material tint → component overlays → + aura layer → flourish particles → stamps + = composed card RGBA texture + +Pass 2 — Effect shaders + apply post-process shader stack to the composed texture + (glow / holo / foil / corruption / first-reveal / ...) + = final card pixels + +Pass 3 — UI compositing + place card in inventory frame, drop shadow, hover state +``` + +**Pixel art note:** the visual style is pixel art with palette-locked dithering ([09-art-style.md](09-art-style.md)). Effect shaders on the composed card should pixelate-quantize to the pixel grid when they're large or visible (holo, foil, corruption); subtle glow/bloom can stay smooth because the eye reads it as atmosphere rather than as art. + +### Effects that need zero assets + +| Effect | Implementation | Use case | +|---|---|---| +| Outer glow | radial blur on alpha mask, colored | Magical items | +| Holographic foil | animated UV shimmer, hue rotation over time | Rare quality bands | +| Foil shimmer | specular angle-based highlight | Legendary frames | +| Heat haze | UV displacement by animated noise | Fire / forge effects | +| Frost crackle | overlay noise, hue toward white-blue | Frost enchantments | +| Cursed corruption | chromatic aberration + vignette darkening | Cursed items | +| Holy radiance | god-rays + bloom | Blessed items | +| First-reveal sweep | animated alpha mask wipe on card open | "New Discovery!" moment | +| Faded / locked | desaturation + alpha reduction | Items beyond your tier | + +This collapses asset counts even further — atmospheric / textural effects don't need a PNG, they need a shader. + +### Quality bands become partly shader-driven + +- **Crude**: no shader pass. +- **Common**: no shader pass. +- **Fine**: subtle outer glow, colored by primary effect. +- **Masterwork**: animated foil shimmer + drifting particles. +- **Legendary**: holographic shader + animated frame glow + drifting particles + bespoke art. + +Quality is felt instantly through visual treatment, not just stat numbers. + +### Performance + +- **Active card view** (focused, large): all shaders + animation enabled. +- **Inventory list** (200 thumbnails): drop the shader pass, render Pass 1 only, cache the result. Or render at reduced resolution. +- **Transition**: cross-fade from cached static thumbnail → live shader version on tap-to-focus. +- **Animation gating**: shaders pause when offscreen — save battery. +- Mobile GPUs handle this trivially at 1–2 simultaneous focused cards. Don't try to run the shader stack across 50 cards in a grid. + +### Engine implications (input, not decision) + +Pushes mildly toward an engine with strong custom-shader support. +- **Unity**: Shader Graph + URP, well-trodden mobile path. +- **Godot**: visual shader editor is solid and free, mobile improving. +- **Flutter**: possible via `FragmentShader` + `CustomPainter`, rougher for shader-heavy UI. + +## Data model implication + +Every item instance stores a composition recipe, not a baked image: + +``` +ItemInstance { + id: UUID + base_id: "falchion" + material_ids: ["moonsilver"] + component_ids: ["pommel_gem:lapis_lazuli", "hilt_wrap:silver_thread"] + effect_ids: ["frost_aura"] + quality: Fine + maker_id: minion_uuid +} +``` + +The renderer reconstructs the card on demand. Save data is tiny. Serialization for future bazaar is trivial — transmit the composition recipe, receiving client reconstructs the card. + +## UI implications + +- **Card view is a first-class UI object**, not just an icon. +- **Card flip on craft completion** is a key game moment — the reveal is where the dopamine lives. Choreography per quality band designed in [13-reveal-choreography.md](13-reveal-choreography.md). +- **Inventory, market, share screenshots, patron orders** all reuse the same card renderer. +- **Tooltips can be lighter** because the card itself communicates so much already (gem, material, aura, quality). + +## Open questions + +- Do non-card uses (inventory icons, list views) use a low-detail composition or a baked thumbnail cache? +- Where does the composition test step live in the asset pipeline — automated screenshot diffing? Curator review? +- Do we expose composition recipes to players (they see the layer breakdown), or stay opaque? +- Shader budget for mid-tier mobile devices — what's the realistic ceiling for simultaneous focused cards? +- Do atmosphere layers ever animate (scrolling UV swirls), or are they static PNGs and animation only happens via shader passes? diff --git a/docs/08-ux-ui.md b/docs/08-ux-ui.md new file mode 100644 index 0000000..a316491 --- /dev/null +++ b/docs/08-ux-ui.md @@ -0,0 +1,135 @@ +# UX / UI + +The game has no world to explore, so the UI *is* the world. Backdrops, scene navigation, and the rhythm of card reveals carry the experience. + +**Visual style:** pixel art world (palette-locked, dithered) + HD vector chrome (frames, buttons, system text). See [09-art-style.md](09-art-style.md) for the rules of mixing the two. + +## Inventory: three tiers of presentation + +See [09-art-style.md](09-art-style.md) for size-consistency rules across cards. + +Different items deserve different treatments. Cards are precious; raw materials are not. + +| Tier | What | Treatment | Example | +|---|---|---|---| +| **Stackable raw** | Gathered materials, ingredients | Simple list row: icon + name + quantity | "Moonpetal × 47", "Iron Ore × 112" | +| **Stackable refined** | Components, intermediate crafts where two of same quality are interchangeable | Simple list row, separated by quality band | "Refined Moonsilver Ingot (Fine) × 4" | +| **Unique instances** | Final assemblies — weapons, potions, jewelry, gear | Full card with composed art, maker mark, history | Your specific Lapis-Infused Moonsilver Falchion #a7f3 | + +**Rule:** if two items are interchangeable, they stack. If they have identity, they get a card. + +Stackable inventories use Stardew/Terraria-style lists — fast to scan, low visual noise. Card inventories use the full composed-card treatment from [07-item-cards.md](07-item-cards.md). + +## The Vault — three tabs + +Vault is tabbed, uniform grid (no Diablo multi-cell). Equipment is meant to flow *through* the vault — craft → equip or sell — not pile up. Stockpile is the working materials store. + +### Tab 1 — Equipment +- Card thumbnails in uniform grid (~12-20 visible at once) +- Quality border color per thumbnail; foil shimmer for Masterwork+; overlay icon for Legendary +- "EQUIPPED ON {minion}" tag on cards currently worn +- Tap thumbnail → full card showcase view + actions (Equip / Unequip / List for Sale / Move to Wall of Masterworks) +- Filter chips: All · Weapons · Armor · Jewelry · Tools · Consumables · Equipped · Available +- Sort: Recent / Quality / Value / Type +- Bulk action: "Sell all Common+ unequipped" sweep for veteran cleanup + +### Tab 2 — Stockpile +- Stackable list rows: icon · name · quantity · quality band stripe +- Filter chips: All · Raw · Refined · Components · Consumables · Trophies (categories per [14-materials.md](14-materials.md)) +- Sort: Quantity / Recent / A-Z +- Search bar (vital once the catalog grows) +- Tap row → "what recipes use this" + "where does this drop" jump-to-zone affordance +- Compact, functional — no card flourishes here + +### Tab 3 — Special +- Recipe scrolls, lore relics, patron tokens, bestiary trophies, one-off curiosities +- Card-ish presentation but smaller; some are stackable (3 unread Foreman's Tally scrolls = stack of 3) +- Tap to use / read / apply + +## Navigation + +Two top-level surfaces: + +### Guild Hall (home screen) +First-person view of the great room from your fixed vantage at the head of the hall — you're the guildmaster, this is your space. Scene-as-navigation: tap zones in the scene to enter subviews. + +- Forge corner → Forge workshop +- Alchemy nook → Alchemy Table +- Roster wall (portraits hanging) → Roster screen +- Patron board (bulletin in the foyer) → Patron Court +- Library doorway → Library +- Strongroom → Vault / inventory +- Front door → World Map (expeditions) + +### World Map +Parchment-style fantasy map. Regions are illustrated nodes; tap a region to see its zones; tap a zone to plan an expedition. Used exclusively for expedition planning. + +### Persistent bottom tab bar +Always-available shortcuts (Hall · Roster · Workshops · Map · Patrons · Library) so repeat actions don't require navigating the scene every time. Scene navigation = atmosphere; tab bar = speed. Animal Crossing Pocket Camp / Hay Day pattern. + +## Backdrops + +In a no-exploration game, backdrops are the world. Each one is high-impact and sells location-feeling. Production-time AI generation on the workstation is the right tool. + +All backdrops are **first-person POV** (the player is the camera) except the World Map, which is top-down parchment because a map is a literal artifact. See [09-art-style.md](09-art-style.md) for the perspective discipline. + +| Surface | Backdrop | +|---|---| +| Guild Hall home | First-person great room view, possibly time-of-day variants (morning, evening, night) | +| Each workshop (~9) | First-person at the station — you see the anvil / cauldron / loom from your POV | +| Each region (~10) | First-person vista per region, what an expedition member sees standing there | +| Each zone (~50) | Either own backdrop or shared region backdrop with different lighting/mood | +| Patron Court | First-person at the bulletin board / hall | +| Library | First-person at your desk / bookshelves | +| World Map | Top-down parchment map with illustrated region nodes — the one perspective exception | + +Atmospheric foreground animation (drifting smoke, bubbling liquid, embers, rain, fog) sells scenes without 3D. Looping particle layers + shader effects on top of the backdrop. + +## Card view modes + +Even card-tier inventory needs two modes: +- **Compact grid** — small card thumbnails, fast scrolling. For practical use ("pick a sword to equip Theodric"). +- **Showcase view** — full card, one or two at a time, gallery feel. For lingering / admiration. + +## Wall of Masterworks + +A Library room displaying the player's best-ever crafts as a permanent wall of cards. Pure cosmetic, deeply motivating. Possibly with social-share integration later (export wall as image). + +## The "alive hall" idea + +First-person POV solves this elegantly. Minions are *across* from you at their stations — you see them working in your shared space, not as figures shuffling around an isometric diorama. Theodric tending the forge across from you, Mira reading at the library table, Theora distilling something at the alchemy bench. + +Implementation: layered minion sprite overlays at named backdrop anchor points (per [09-art-style.md](09-art-style.md) anchor + depth-scale system). The minion's current portrait + class costume + equipped legendary gear all compose into the in-scene sprite. Each anchor has an animation track (subtle work loop — hammer swing, page turn, stir) that loops independently. + +When a minion isn't currently assigned to a station, the anchor is empty. + +## Notification surface + +The "always something shiny" rule manifests in the Guild Hall as small glowing badges on scene elements: +- Workshop with completed craft → glow + badge on that workshop +- Returned expedition → glow + badge on the front door +- New applicant → glow + badge on the recruiting desk +- Patron deadline approaching → glow + badge on the patron board +- Guild Rank-up available → glow + badge on the central altar/hearth + +The home screen at any moment communicates: "here are the ripe things to tap." Players check in for 5 minutes and can immediately see what needs attention. + +## Crafting screen specifically + +When you tap into a workshop, the workshop backdrop fills the screen. Foreground UI is: +- Station-specific composition area with ingredient slots (3–6) +- Ingredient palette / picker (filtered to applicable materials in your stockpile) +- Assigned engineer slot (drag a minion in to assist) +- Recipe book toggle (see known recipes for this station, hint glyphs for partially known) +- Craft button (with quality forecast: "expected Fine ± 1 band") +- Active craft queue (parallel slots — count grows with Guild Rank) + +The craft completion moment plays on this screen: the assembled card lifts out of the station, the shader sweep plays, the quality reveals. Then it lands in the player's vault. + +## Open questions + +- Time-of-day cycling for the Guild Hall backdrop: real time vs. game time vs. fixed sequence? +- Inventory grid model — uniform 1-cell cards (mobile-friendly) vs. Diablo-style multi-cell items (era-true, more tactile). +- ~~Onboarding flow~~ — designed in [12-onboarding.md](12-onboarding.md). +- Notifications outside the app (push) — too easy to nag, but vital for AFK expeditions. Opt-in by category? +- Settings, accessibility, color-blind palettes for quality bands and effect auras (red curse vs. green poison must be distinguishable). diff --git a/docs/09-art-style.md b/docs/09-art-style.md new file mode 100644 index 0000000..89c8adc --- /dev/null +++ b/docs/09-art-style.md @@ -0,0 +1,97 @@ +# Art Style + +**Late-90s pixel art era** — Diablo II / Infinity Engine / Fallout 1-2 territory. Detailed, atmospheric, painterly. Not the iconic-but-coarse 8/16-bit look — the *atmospheric detail* generation that came after. + +Achieved via diffusion-model generation, downsampled to 640×360 native, then **Floyd-Steinberg dithered against a 256-color palette derived by kmeans from a library of z-image generated art**. The palette is calibrated and locked. The dither pass is what erases the "AI look" — the smooth-gradient, plasticky, hyper-blended tell of diffusion model output gets quantized away into honest pixel art. + +## Why this style + +- **Erases the "AI look".** Diffusion model output has a distinctive smooth-gradient / over-blended tell. Palette quantization + dither destroys it cleanly. What ships looks like deliberate hand-pixelled art, not generated art with a filter. +- **Style consistency on AI-generated assets is solved.** Palette + dither normalizes everything regardless of model/seed/prompt drift. +- **Asset budgets shrink dramatically.** ~10–30KB per item sprite (PNG-8 indexed against the 256-palette), whole game's art likely fits in tens of MB. +- **Mobile-optimal.** Tiny textures, integer scaling, low GPU cost, perfect on any screen size. +- **Detail without the iconic-pixel-art trap.** 256 colors at 640×360 is much more expressive than NES/SNES-era pixel art. We can do *beautiful*, not just *iconic*. +- **Animation gets cheap.** 4-frame flicker on a torch is trivial. Subtle constant-motion details (bubbling cauldrons, drifting embers, blinking portraits) become affordable. + +## Asset production pipeline + +1. Generate high-res candidate on workstation (z-image or comparable diffusion model). +2. Downsample to target pixel resolution. +3. Apply Floyd-Steinberg dither against the master 256-color palette. +4. Optional hand-clean of ambiguous pixels. +5. Commit to content repo. + +Workflow is solved. It's a script. + +## Native resolution + +- **Pixel-native canvas: 640×360.** Late-90s era target — too small loses the "beautiful" we want, too big loses the pixel identity. +- Cards integer-scaled from a smaller native (likely 256×384), backdrops at 640×360 or fractional multiples for atmospheric detail. + +## Palette + +256-color palette derived via kmeans clustering from a library of z-image generated art. Calibrated against what the source diffusion model actually produces, so quantization is lossy but never *wrong*. Locked. + +Recoloring within the palette is essentially free — Common iron pulls from the gray range; Masterwork from the silver range; Cursed variants pull from purple shadow ranges. Effect-driven recolor (poison gives a green tint pass, fire gives an orange tint pass) is shader work, not new art. + +## The pixel/HD coherence rules + +Mixed-resolution UI needs a deliberate vocabulary. + +| Layer | Resolution | Examples | +|---|---|---| +| **World** | Pixel art, native res, integer-scaled, dithered, palette-locked | Backdrops, items, portraits, components, gear, particles | +| **Chrome** | HD vector / native | UI frames, buttons, dialogs, tooltips, system text | +| **Effect shaders** | Choice per effect | Holo/foil pixel-aligned; bloom and glow can be smooth at low intensity | +| **Text** | HD or BMFont pixel font | Pixel font for flavor (item names, log entries); HD for menus / system / accessibility | + +**Rule: shader effects on pixel art should respect the pixel grid** when they're large or visible. Pixelated holo shimmer reads as intentional. Smooth holo on pixel art looks wrong. Subtle glow/bloom can break the rule because the eye reads them as atmosphere, not art. + +## References + +Primary era reference (late-90s pixel art): +- **Diablo II** — the canonical fantasy item/loot/crafting UI. Composed item sprites in inventory grids, atmospheric dark palette, painterly pixel art. Closest single reference to what we're building. +- **Baldur's Gate / Planescape Torment / Icewind Dale (Infinity Engine)** — pre-rendered painted backdrops with pixel-art character sprites overlaid on anchor points. *Exactly* the Guild Hall + minion-overlay model. +- **Fallout 1 / 2** — isometric pixel art, item-driven inventory, restricted palette mood. + +Secondary modern references (style mixing rules, UI / shader treatment): +- **Loop Hero** — pixel art card-driven progression, very close in mood +- **Octopath Traveler / Sea of Stars (HD-2D)** — pixel sprites with HD lighting/depth +- **Dead Cells** — pixel art world with crisp HD UI chrome +- **Stardew Valley** — pixel art crafting / inventory at scale +- **Eastward / Hyper Light Drifter** — palette-as-identity discipline + +## Perspective discipline + +Different surfaces follow different conventions, intentionally. + +- **Backdrops: first-person POV.** You-the-guildmaster are the camera. At the Forge you see the anvil from your POV with the smith across from you. At the Alchemy Table you're looking down into your own bubbling cauldron. At the Patron Court you're standing at the bulletin board. Late-90s/early-2000s home-base interior feel (Skyrim, BG3 camp, Slay the Spire / Inscryption dealer table, Myst painted scenes). +- **Item cards: free per item.** Each card composes the item however it displays best — a ring top-down, a sword side-on, a polearm diagonal, a vial three-quarter. No unified vantage. The discipline is *size consistency*, not perspective. +- **Portraits: bust shots.** Standardized for layered composition (face / hair / costume layers). +- **World map: top-down parchment.** The one exception, because the map *is* a literal artifact you read. + +Reference: Slay the Spire / Inscryption / Hand of Fate / Reigns for first-person card-table feel; Myst / Riven for painted first-person standing-in-a-place backdrops; Diablo II town hubs for atmospheric standing-in-a-place fantasy. + +## Size consistency + +The real visual-coherence problem (rather than perspective). Three levels of rule: + +**Card canvas — fixed.** Every card renders to a uniform pixel canvas (likely 256×384). Frame is uniform. Item silhouette inside scales to fit. + +**Per-category silhouette scale** — tuned constants: +- Tiny items (rings, amulets, gems, stoppers): ~50% of canvas, padded +- Small items (daggers, potions, scrolls): ~70% +- Standard items (swords, hammers, staves): ~90% +- Large items (polearms, two-handers, longbows): rotated diagonally to fit, capped at ~95% + +**Anchor-point depth scale on backdrops.** Every first-person backdrop defines named anchor points where minion or item sprites can place. Each anchor has a depth-scale value (close-to-camera = 1.0, deep-in-scene = 0.5–0.7). Sprites render at the anchor's depth scale automatically — no accidental giant-figure-at-the-back-of-the-room moments. + +## Animation + +**4 fps** for sprite animation — confirmed via working production pipeline (Flux still → Wan 2.2 video → 4 fps keyframe → palette conversion). Era-correct for late-90s reference (Diablo II walk cycles ran 4-8 fps depending on direction). See [06-asset-pipeline.md](06-asset-pipeline.md) for the animated-sprite pipeline and `samples/` for an example. + +## Open questions + +- Pixel font choice — which font, what size, when do we fall back to HD font. +- Do we ever break the pixel rule for special moments (cinematic Legendary discoveries with HD splash)? +- Inventory grid model: uniform 1-cell cards (mobile-friendly, simpler) vs. Diablo-style multi-cell items (era-true, more tactile, Tetris-puzzle feel). diff --git a/docs/10-tone.md b/docs/10-tone.md new file mode 100644 index 0000000..c3a2815 --- /dev/null +++ b/docs/10-tone.md @@ -0,0 +1,72 @@ +# Tone + +**Confident fantasy stylization with muted weight.** Substantial enough for adults, accessible enough for anyone, never juvenile or edgy. The hand-painted fantasy illustration tradition (Brom at his subdued moments, classical fantasy book art) translated to the late-90s pixel art era. + +## Reference triangulation + +The mood is the intersection of three primary references: + +| Reference | Contribution | +|---|---| +| **WoW** | Stylized exaggeration for readability — chunky pauldrons, fat gems, weighty pommels, silhouettes that read at a glance. Confident proportions, not realism. | +| **Quake** | Muted earthen palette dominated by browns / sepias / rust-reds with restrained accent colors. Materials look weathered, real, lived-in. Adult seriousness without edginess. | +| **Machinarium** | Atmospheric environmental storytelling — every workshop tells you something about who works there. Warm interior glows against cooler exteriors. Wordless mood via lighting and texture, not subject matter. | + +Modern reference points that hit this exact mood: +- **Bastion / Transistor / Hades (Supergiant)** — closest active match. Stylized illustration, muted-but-warm palette, atmospheric lighting, accessible-but-mature. +- **Stoneshard** — pixel-art-specific reference: Diablo-influenced gritty stylized fantasy that stops short of grimdark. +- **Tunic / Death's Door** — broadly accessible without being childish, confident art direction, small-scale fantasy with weight. + +## What "muted weight" means per surface + +### Palette weighting +The 256-color palette is locked, but the *application* leans muted. Materials use earthy ranges — leather browns, iron grays, oxidized greens, ember oranges. Effect ranges use muted magical colors: +- Poison: sickly olive, not lurid neon-green +- Fire: warm ember-amber, not arcade orange +- Holy: dusty gold, not pure white +- Curse: bruised wine, not vibrant purple +- Cold: foggy slate-blue, not pure cyan +- Arcane: faded lapis, not electric blue + +The palette is rich enough to support both vivid and muted readings — we always pick the muted reading. + +### Backdrops +Warm hearth-light interiors, smoky and lived-in. Workshops have texture — tools hanging, half-finished projects on benches, rust on the bellows, candle smoke staining the ceiling. Zones are atmospheric and weather-affected — the Mire is foggy gray-green, not poison-neon green; the Ironwood is overcast and rust-red, not bright autumn. Machinarium's "every room is a story." + +### Items +WoW-style chunky silhouettes for readability — fat gems, weighty pommels, presence. But Quake-style material treatment — iron has rust spots, leather is creased, wood is grain-textured. Enchanted items glow as a soft warm ember, not a video-game halo. + +### Characters +Stylized but with weight. Real faces with slightly idealized proportions. WoW silhouette discipline — class reads at thumbnail size (the soldier visibly has thick pauldrons; the alchemist visibly has a bottle-laden belt). Not chibi, not realistic, not grimdark. + +### Writing voice +Middle register. Atmospheric, occasionally dry, never quippy. + +> *Theodric stumbled into a lurkwight nest. Mira pulled him out, but Theora's tincture was lost in the muck.* + +Not too juvenile ("OMG Theodric almost died!"). +Not too edgy ("Theodric was DEVOURED in a hideous orgy of carnage."). +Not too purple ("Theodric, our brave warrior, encountered a foul beast..."). +Just: stuff happened, here's what happened, here's what it cost. Confident, terse, atmospheric. + +Patron dialog: courtly, dry, stakes feel real but not melodramatic. +Item flavor text: evocative, terse, no winking at the player. + +### Audio +The Diablo II Tristram / Machinarium piano / Bastion plucked-string school, plus the Everquest Kelethin lineage of slow modal woodwind-led ambient. Wordless atmospheric melodic beds. Workshop ambience layered underneath (hammer rings, bubbling, page turns). Not orchestral-heroic, not chiptune-nostalgic, not ambient-droning. Melancholy-warm-confident. See [15-audio.md](15-audio.md) for production approach. + +### UI chrome +Burnished brass with riveted iron — something a craftsman would actually make. Not gold-filigree (too high-fantasy cliché), not skull-and-bones (too grim), not flat-modern (wrong era). Substantial, weighty buttons. Serif text with weight (Bookman, Garamond, or a chosen fantasy serif). No calligraphy. + +## What we're explicitly avoiding + +- **Comical / mobile-game cute** (Hay Day, Clash Royale aesthetic) +- **Grimdark / edgy** (Darkest Dungeon's narrator pitched up to 11) +- **Juvenile humor** (winking at the player, video-game-isms in the text) +- **High-fantasy purple** (every NPC speaks like a Renaissance Faire performer) +- **Photorealistic** (loses the era reference and the AI-look-erasure trick) +- **Saturated cartoon palette** (loses the muted gravitas) + +## The tone matrix one-liner + +*Confident fantasy stylization with muted weight — substantial enough for adults, accessible enough for anyone, never juvenile or edgy.* diff --git a/docs/11-setting.md b/docs/11-setting.md new file mode 100644 index 0000000..559863c --- /dev/null +++ b/docs/11-setting.md @@ -0,0 +1,58 @@ +# Setting + +**Generic medieval fantasy.** Swords and dungeons, bubbling cauldrons, candle-lit libraries, foggy moors, hooded figures. We lean on the player's existing fantasy vocabulary rather than building a world from scratch. + +## What this means + +- **No worldbuilding burden.** No proper-name continent, no original pantheon, no faction-history primer. The world is the world the player already knows from D&D, Warhammer Fantasy, Tolkien-descended fiction, *every fantasy game they've played*. +- **Standard vocabulary works.** Elves, dwarves, gnomes, orcs, mages, knights, druids, necromancers, paladins, rogues. Iron, mithril, oakwood, moonsilver, dragonscale. Forge, alchemy, enchantment. None of it needs explaining. +- **Standard visual library applies.** Stone keeps, oak doors, hearth-light interiors, tapestries, candles, ironwood doors, parchment maps, banded leather, plate armor, glass vials, clay pots. +- **Players bring their own headcanon.** When someone meets *Mira the Devout, paladin*, they fill in a paladin from their own imagination. We don't have to teach them what one is. + +## What we explicitly don't include + +- Science fiction, modern, or near-modern elements (no firearms beyond hand-cranked oddities in gnomish corners, no electricity, no laser-swords, no plasma, no holograms) +- Specific original-world lore ("This is Aelorian, the Eternal Realm of...") +- Original pantheons or religions that require setup +- Factional politics that need a primer +- Made-up vocabulary the player has to learn + +## Flavor pockets (allowed sub-tropes) + +These are well-established fantasy sub-tropes that give us visual / mechanical variety without breaking the generic-fantasy permission: + +### Gnomish steampunk +- Visual vocabulary: brass, copper, gears, steam, monocles, goggles, leather aprons, clockwork creatures +- Item variety: clockwork fittings, gear-driven mechanisms, brass-tubed contraptions, pressure-glass vials +- Zone: a workshop enclave (think Gnomeregan / Mechanus / Dishonored's Karnaca lite) +- Patrons: tinker-magnates commissioning clockwork prosthetics, brass armor, steam-augmented weapons +- Tonal note: lightest pocket — quirky, inventive, not grim + +### Dark elf necromancy +- Visual vocabulary: obsidian, bone, purple-black gemwork, ritual circles, drip candles, shadow-veins, sigils +- Item variety: necrotic reagents, bone components, cursed bindings, shadow-touched gems, soul-glass +- Zone: subterranean enclaves, ancient crypts, moonless groves +- Patrons: cabalists commissioning dark blades, anti-paladins in disguise, secret cults +- Tonal note: darkest pocket — sinister, secretive, not edgy-grimdark + +### Mainline (the rest) +- Standard medieval-fantasy human / dwarven / elven / mixed cultures +- Standard knights, mages, druids, clerics, scholars, merchants +- Standard zones: forests, mires, ruins, mountains, river valleys, ancient roads +- Tonal middle — mature, atmospheric, neither gnomish-light nor dark-elf-shadowy + +## Naming conventions (quick reference for procgen pools) + +- **Human** names lean Latin / Germanic / Celtic roots: Theodric, Mira, Theora, Aelis, Bran, Caewin, Roderic, Una +- **Dwarven** names lean Norse / Germanic-hard: Brokk, Durin, Tora, Halgrim +- **Elven** (high) names lean Latin-flowing: Aelandir, Sylvana, Faedron, Elara +- **Dark elven** names lean sibilant / apostrophe: Vae'shar, Drael, Lys'thala, Karovar +- **Gnomish** names lean alliterative / quirky: Tinkin Tappet, Wibble Wickum, Glia Greaseworth, Pim Pendlebrass +- **Place names** use generic fantasy conventions: the Mire, the Ironwood, Greybell Hollow, Ashfen Marsh, the Cracked Tower, Last-Light Crossing + +## Why this works for the game + +- **Patron variety.** Three tonal pockets × multiple class archetypes = a wide patron board without needing original lore. A patron is "gnomish artisan named Glia who wants brass-fittings for a clockwork hawk" or "dark elf cabalist named Vae'shar who needs a cursed dagger pommel" or "Knight-Captain Roderic who wants ten Fine longswords for his guard." +- **Zone variety.** Three pockets × multiple environments = many distinct expedition destinations. Players see meaningful art variety without the world-building cost. +- **Recipe variety.** Mainline crafting + clockwork + necromantic = three overlapping but distinct material/component vocabularies in the recipe book. +- **Visual variety per zone.** The tone doc's muted palette guidance still applies, but each pocket gets its own warm-vs-cool / earthen-vs-shadowed bias. diff --git a/docs/12-onboarding.md b/docs/12-onboarding.md new file mode 100644 index 0000000..dcd8cf6 --- /dev/null +++ b/docs/12-onboarding.md @@ -0,0 +1,97 @@ +# Onboarding (First 10 Minutes) + +A 5-minute walkthrough that exposes every system in the order it actually flows, ending with the player released into the live game with anticipation cooking. Built around two design principles: **skip the wait** (pre-completed first expedition so the player doesn't hit a 30-min timer in beat 1) and **forced critical success** (a designed wow-moment on the player's first craft so the dopamine hook is set). + +## The five beats + +### Beat 0 — Drop-in (~30s) + +- Player loads into the Guild Hall first-person view +- Short framing line: *"Welcome, Master. The guild is yours."* +- One starter minion already on the roster — authored character, name + portrait + decent traits. Working name: **Caewin the Steady**. He stays a real minion after the tutorial. +- Two notification badges glowing in the scene: the **front door** (returning expedition) and the **patron board** (waiting bounty) +- Bottom tab bar visible but no popups yet — let the badges pull + +### Beat 1 — The returning expedition (~1 min) + +Tap the front door → expedition return screen. + +- Caewin returns with a hand-tuned starter haul: iron ore, hardwood, oil, glass, leather, flint +- Brief procedural event log: *"Caewin scouted the lower hills and brought back what he could carry."* +- Drop is exactly enough for a Crude Pickaxe + Trusty Lantern, plus a couple of low-value extras so the inventory looks real + +Teaches: expeditions exist, return with loot, minions have identity. + +### Beat 2 — The patron board (~1 min) + +Tap the patron board → first patron unlocks. + +- **The village foreman** — friendly, unintimidating, becomes a recurring low-tier patron later +- Ask: *"Bring me a Trusty Lantern, Fine quality or better. Pay: 50 gold, reputation, and a scroll for the Foreman's Tally."* + +Frames the *why* of the next craft — the player has a goal, not "click around and see." + +Teaches: patrons exist, bounties are specific, rewards include recipe unlocks. + +### Beat 3 — The first crafts (~2 min) + +Soft-guide to the workshops. Two crafts in sequence: + +**Crude Pickaxe** — quick, two ingredients, zero ceremony. Teaches drag-to-station, hit craft, get item. Common quality, lands in the vault. + +**Trusty Lantern** — four ingredients (iron, glass, oil, leather). The player encounters their **first Master's Touch meter** ([16-engagement-layers.md](16-engagement-layers.md)) — two slow, wide-green meters that are essentially impossible to miss at this difficulty. Both lock in green. **Forced critical success.** Shader sweep, particles, "Masterwork" ribbon, sound flourish, card lifts and rotates. The +resource bonus from the crit drops a **Foreman's Tally** — a gather-yield-boosting tool. + +**Critical:** never tell the player it's a tutorial crit. The result panel shows plausible math: *"Caewin's steady hand + Lucky trait + perfect timing on both meters."* The player feels they nailed it. The hook is set — every craft from now on has a chance at this feeling, and the meter mechanic is taught. + +(The earlier Crude Pickaxe craft introduces the Master's Touch meter on its slowest, easiest setting — so the mechanic is taught with no stakes before it matters.) + +Teaches: crafting interface, quality bands, the critical-success moment, equipment items. + +### Beat 4 — Equip and send (~1 min) + +Soft-prompt: open the roster, tap Caewin, drag lantern + Tally into equipment slots. + +- Caewin's portrait visibly updates (lantern at the belt, Tally tucked in pack) — paper-doll showcase +- Soft-prompt: open the World Map +- Two zones unlocked in starting region — player picks one +- Expedition sets off, tutorial timer ~2–5 minutes (short by design — second payoff if they keep playing, satisfying completion if they put the phone down) + +Teaches: equipment changes portrait visibly, world map navigation, expedition planning, second-loop priming. + +### Beat 5 — Release (~30s) + +Brief outro: *"The guild is yours, Master. There's always something to do."* + +- Tutorial overlay closes +- All tabs unlocked +- Patron screen shows patron 1 completed (green check, rewards paid) +- Patron 2 populates with a slightly meatier ask +- Player is dropped into the live game with sense of completion + sandbox + expedition cooking + +## Design rules + +- **Soft, not modal.** No forced arrows. Badges glow in priority order. Contextual one-liners surface on first-open of each screen. Player can tap around freely — tutorial just biases toward an order. Crafting the pickaxe before checking the patron board is fine. +- **Authored, not procgen.** Caewin, the foreman, the starter haul, the recipes — all hand-tuned. Procgen kicks in for the *next* of everything. +- **Forced crit hidden as a real roll.** Result panel must show plausible math. Player attributes the win to themselves. +- **Skip-friendly.** Returning players / repeat installs can skip after Beat 1. +- **Save-resume at every beat.** Closing app mid-tutorial picks up exactly where left. +- **No second tutorial.** After this 5 minutes, contextual hints only. New systems unlock with one-line tooltips on first encounter, never multi-step popups. Treat the player as an adult after the door closes. + +## State after the tutorial + +- 1 starter minion (Caewin) equipped with Masterwork Trusty Lantern + Foreman's Tally +- 2 expedition zones unlocked, 1 expedition in progress +- 1 workshop tier unlocked (Forge + Tinker's Bench, whatever crafts pickaxe + lantern) +- 2 recipes known (pickaxe, lantern), 1 recipe scroll in vault (Foreman's Tally upgrade path) +- 50 gold + initial reputation +- Patron 2 populated and waiting + +A complete first-session arc: receive → craft → crit-magic → equip → send → exit with anticipation. + +## Open questions + +- Onboarding skip threshold — Beat 1 (after the returning expedition) feels right, but worth testing. +- Push notification opt-in — when do we ask? Right after the first expedition is sent (so they get notified when it returns), or wait until session 2? +- Tone of the framing voice — terse and atmospheric (matches the tone doc) vs. warmer and more guiding for onboarding only? +- Authored characters' continuity — does Caewin show up in the starting roster every game, or do we vary him? +- What if the player crafts the pickaxe twice (because it's quick) and skips the lantern? Forced crit might want to fire on whatever first-Fine-eligible craft they make, not specifically the lantern. diff --git a/docs/13-reveal-choreography.md b/docs/13-reveal-choreography.md new file mode 100644 index 0000000..5985b6c --- /dev/null +++ b/docs/13-reveal-choreography.md @@ -0,0 +1,127 @@ +# Reveal Choreography + +The card-flip moment after a craft (and other reward reveals) is the highest-leverage dopamine in the game. Designed around one principle: + +**Length scales with magnitude. Buildup is the signal, not manufactured suspense.** + +Players learn the visual/audio language quickly ("oh, it's spinning, that's at least Fine") and never get baited-and-disappointed. Reference: Vampire Survivors chest opens — simple, honest, scales gracefully with the actual reward. + +## Anti-pattern we're avoiding + +The slot-machine pattern: long buildup → suspenseful flourish → common item flops → player feels cheated. We're doing the opposite — a Common item gets a quick honest reveal so the player isn't promised more than they're getting. The reveal *is* the result, not a teaser for one. + +## The five band tiers + +### Crude +- Card sits on the station, faint dust puff +- Single quick flip +- Lands face-up with a soft thud +- Brief result text, no glow, no particles +- **Total: ~0.5s.** Sound: soft *thump* + +### Common +- Card on station, slight tremble +- One flip with a satisfying *crunch* +- Settles with a small wobble +- Subtle highlight on the quality border +- **Total: ~0.8s.** Sound: hammer-crunch + +### Fine +- Card on station, harder tremble +- Silver shimmer along the edges +- Two flips, metallic *ring* on the second +- "Fine" ribbon appears with a small particle burst +- **Total: ~1.5s.** Sound: hammer + chime + +### Masterwork +- Card vibrates with a low resonant hum +- Golden glow brightens, particles begin drifting up +- Three rotations, increasing speed +- Lands with a metallic *clang* +- Burst of golden particles, "Masterwork" ribbon flies in +- Holographic foil shader kicks in and stays +- **Total: ~2.5s.** Sound: hum → rising chime → clang → soft choir flourish + +### Legendary +- Screen subtly darkens around the card +- Low rumble, vibration intensifies +- Radiant white-gold light pillars from underneath +- Multiple rotations (5+) with motion blur +- **Time briefly slows (~0.7×) for the apex** — reserved exclusively for Legendary +- Bursts in a flare of radiant light, screen flash +- "Legendary" ribbon arrives with a deeper sound +- **Bespoke hand-finished art piece revealed** (Legendaries get the bespoke treatment per [07-item-cards.md](07-item-cards.md)) +- Holo foil + ambient glow + drifting particles continue after settle +- **Total: ~4–5s.** Sound: rumble → slow rising swell → *crack* of light → choir + organ swell + +## Special cases + +### Critical success (band promotion mid-reveal) + +The choreography starts at the *expected* band, then mid-flip kicks up to the next band: +- A "wait — no" beat: particles intensify, light shifts +- Reveal upgrades to one band higher than expected +- "**Critical Success!**" ribbon arrives with the upgraded reveal sequence +- Player thought Common, got Fine. Player thought Fine, got Masterwork. *Best feeling in the game after Legendary itself.* + +Critical success can be earned two ways: lucky engineer rolls, or hitting both Master's Touch meters perfectly ([16-engagement-layers.md](16-engagement-layers.md)). Same choreography either way, different earnings paths. The forced crit in onboarding ([12-onboarding.md](12-onboarding.md)) is the player's first encounter with this moment — earned by their meter timing on impossibly forgiving meters. + +### New Discovery (recipe unlock, parallel layer) + +Stacks on top of the quality reveal — runs concurrent on a separate channel: +- Card flutters before settling +- Scroll/parchment animation overlays +- "**New Discovery!**" ribbon +- Recipe added to book with a *whoosh* + book-shut sound +- ~3s + +## Design principles + +- **Length scales with reward magnitude.** This *is* the signal. Eliminates the disappointment problem. +- **Honesty over manufactured suspense.** No fake-outs. A Common reveal doesn't pretend to be a Legendary. +- **Audio carries equal weight to visual.** Each band has an audio signature players learn quickly. +- **Time slowing is reserved for Legendary.** Rarest cue for the rarest moment. Don't dilute by using elsewhere. +- **Skippable after the first.** Long-press skips to end-state after ~0.5s. The *first* of each tier the player ever sees shouldn't be skippable; every subsequent one should be. Veteran players' time matters. +- **Bespoke Legendary art revealed at the apex.** Hand-finished one-of-a-kind art is part of why Legendary *is* Legendary. + +## Implementation sketch + +Choreography is a state machine layered on top of the static card composition system. On craft result: + +1. Receive result `{quality_band, was_critical, was_discovery, components, maker, ...}` +2. Pick choreography preset by band (or one band lower if `was_critical=true`) +3. Run sequence: tremble → buildup → flips/spins → reveal → settle +4. Audio + particles + shaders sync to sequence beats +5. If `was_critical`, mid-sequence break to the upgraded preset +6. If `was_discovery`, fire the parallel discovery overlay +7. On settle, card slides into the vault + +Performance: +- Single focused card, full shader stack is fine +- Particles cheap (small counts, short-lived) +- Time-slow via tween scaling, not actual game time +- Choreography assets (audio clips, particle definitions, shader configs) preloaded per session + +## Same framework, other reveals + +The pattern extends to other reward moments — same toolkit, different presets: + +| Reveal moment | Preset analog | +|---|---| +| Expedition return — small haul | Common-tier choreography | +| Expedition return — rare drop | Masterwork-tier swell | +| Expedition return — Legendary relic | Full apex treatment | +| New applicant — common | Quick portrait fade-in | +| New applicant — rare trait or class | Fine/Masterwork-tier flourish | +| Patron reward payment | Scales with payout magnitude | +| Guild Rank up | Apex variant — meta-progression milestone | + +Each variant reuses the same shader / particle / audio toolkit; just different sequence presets. + +## Open questions + +- Skip-after-first per tier vs. per session vs. per install — when does the "first time" lock release? +- Do we play screen flash on Legendary reveals, or is that too aggressive on mobile? (Accessibility: photosensitivity opt-out should exist regardless.) +- Do crit-promotion sequences happen visibly on the way up the band ladder, or do we shortcut straight to the upgraded band's preset? +- Audio mixing — does music duck during reveals so the choreography sounds occupy full headroom? +- Haptic feedback (vibration patterns per band) — yes for Masterwork+, none for Common/Crude? diff --git a/docs/14-materials.md b/docs/14-materials.md new file mode 100644 index 0000000..95c86cd --- /dev/null +++ b/docs/14-materials.md @@ -0,0 +1,90 @@ +# Materials Taxonomy + +Working draft. The vocabulary that everything else hangs off of — expedition drop tables, recipe authorship, refining stations, Stockpile filter chips, component overlay sprite library. Polish later. + +## Categories + +### Raw materials +Gathered direct from expeditions, unprocessed. The "what your gatherers come back with." + +| Type | Examples | +|---|---| +| Ore | iron, copper, moonsilver, mithril, obsidian | +| Wood | hardwood, softwood, ironwood, ebony, lacquerwood | +| Hide / leather | deer, bear, drake, exotic | +| Botanicals | moonpetal, nightshade, sunroot, healwart, herbalist greens | +| Bone & teeth | skeleton bone, drake fang, ghoul fang, ancient ivory | +| Liquids | oil, sap, swamp-water, blood, alcohols | +| Stone & rough gems | rough sapphire, jade, lapis, ruby, granite | +| Cloth fibers | flax, raw silk, cotton, wool | +| Beast parts | feathers, claws, horns, tails, eyes | +| Magical raw | fae dust, soul shards, ectoplasm, manacrystal | +| Gnomish steampunk raw | brass scrap, copper wire, gear blanks | +| Necromancy raw | shadowsilk, grave-dust, soul-essence, bone fragments | + +### Refined materials +Single-step crafted from raw at a refining station. The intermediate stock you build crafts from. + +| Type | Refined from | At | +|---|---|---| +| Ingots (iron, mithril, brass) | Ore | Forge | +| Timbers (seasoned hardwood, lacquered wood) | Wood | Carpenter's Shop | +| Cured leather (light, heavy, exotic) | Hide | Tannery | +| Distillates / tinctures / powders | Botanicals, bone | Alchemy Table | +| Cut gems (faceted, polished, cabochon) | Rough stone | Jeweler's Bench | +| Spun thread (silk, woolen, gold) | Fibers | Loom | +| Glass (clear, stained, leaded) | Stone + flux | Glassworks | +| Worked bone | Raw bone | Carpenter's Shop / Jeweler | + +### Components +Multi-step sub-assemblies, ready to slot into a final craft. Multiple refined inputs. + +- **Hilts** — tempered hilt, ornate hilt, gem-set hilt +- **Pommels** — silver pommel, jeweled pommel, runed pommel +- **Vials** — clear vial, stoppered vial, runed vial +- **Stocks / clockwork frames** — steampunk crafts +- **Settings** — jewelry mounts +- **Stringings** — bowstring, wire, sinew + +### Consumables / catalysts +Spent in crafting, no output mass. Influence quality and effect. + +- Fluxes, mordants, catalysts (additives) +- Inks, quills (scribing) +- Fuel — charcoal, oil, lamp wicks (per-craft consumption, often abstracted) + +### Trophies & curiosities +Special, often unique or quest-tied. Lives in the Special tab of the vault, not the Stockpile. + +- Recipe scrolls — single-use to learn a recipe +- Lore relics — for Scholars to decipher +- Patron tokens / faction sigils — affect reputation +- Bestiary trophies — display in Library, sometimes valuable to specific patrons + +## Supply chain depth + +General pattern: **Raw → Refined → Component → Final Item** (3-step pipeline). Variations: + +- Some items skip a step: Crude Pickaxe = Refined Iron + Hardwood Timber, no separate Components needed +- Some items add a step: Legendary weapons may require sub-sub-assemblies (e.g., enchanted runed pommel = runed pommel + magical infusion + scholar inscription) +- Quality bands compound through the chain: a Masterwork weapon often requires Fine+ components, which require Fine+ refined materials, which require Fine+ raw + +## Quality at every stage + +Every tier supports the same five quality bands (Crude / Common / Fine / Masterwork / Legendary). A Crude Iron Ingot is interchangeable with another Crude Iron Ingot but stacks separately from a Fine Iron Ingot. Quality cascade rules (whether a great Engineer can rescue a Crude component) are still TBD — see [03-crafting.md](03-crafting.md). + +## How materials enter the game + +- **Expedition drops** (primary) — raw materials, occasional refined, rare components from special encounters +- **Patron rewards** — sometimes specific refined or component items as part of payment +- **Scholar research** — can convert lore relics into refined materials of unusual provenance +- **Beast taming** — Beastmasters may tame creatures that periodically produce specific raw materials over time +- **Market** (when bazaar ships) — buy from other players + +## Open questions + +- Do we want a "scrap / salvage" mechanic — break a finished card into components for partial refund? +- How aggressive is the Crude → Common → Fine quality progression? Should Crude be common from low-tier zones and Fine be rare even in high zones, or does the floor rise with zone tier? +- Should some materials have unique properties beyond quality (e.g., moonpetal is *fundamentally* a magical reagent, regardless of quality), or is everything reducible to type + quality? +- Steampunk and necromancy material pockets — are they geographically gated (only found in specific zones), or do they crosscontaminate (e.g., gnomish brass scrap shows up rarely in mainline forests because gnomish travelers passed through)? +- Cataloging: how many distinct material entries do we author for v1? Probably ~30 raw, ~25 refined, ~20 components for a playable starting set. diff --git a/docs/15-audio.md b/docs/15-audio.md new file mode 100644 index 0000000..8ce7c6f --- /dev/null +++ b/docs/15-audio.md @@ -0,0 +1,132 @@ +# Audio + +Audio is the weakest area of solo production capacity, so the plan here is **pragmatic and refinable** — a workable starting point that can ship and improve over time, not a finished design. + +## Direction + +**Music: Kelethin-style mellow fantasy ambient.** Slow, modal, woodwind-forward with string accompaniment. Long compositions, lots of breathing room, gets out of the way. Reference set: + +- **Everquest Kelethin / Greater Faydark / Felwithe** — the canonical "wistful fantasy ambient" sound, slow flowing melodies that loop without feeling looped +- **Diablo II Tristram** — solo acoustic guitar atmospheric, the gold-standard town-hub theme +- **Machinarium** — minimal piano and wordless vocal, very atmospheric +- **Bastion** — plucked strings, folk percussion, atmospheric +- **Planescape Torment / Baldur's Gate** — orchestral fantasy, often subdued + +**SFX: clean, satisfying, era-appropriate.** Hammer rings, page turns, glass clinks, soft chimes, low rumbles. Nothing cartoonish, nothing synthetic-sounding. Sample packs as the foundation, layered + tweaked + rotated so nothing becomes a Wilhelm scream. + +## Music production approach + +### MIDI generation pipeline (recommended) + +1. Generate MIDI compositions with AI tools (ACE / similar) using prompt parameters: mood = "mellow fantasy ambient," tempo = 60-80 BPM, instrumentation = woodwinds + strings + harp, length = 3-5 min, key/mode = Aeolian / Dorian / Phrygian for fantasy modal feel +2. Curate the best +3. Optional MuseScore pass for hand cleanup +4. Render through a high-quality soundfont (FluidR3_GM, GeneralUser GS, or a specialty fantasy soundbank) via FluidSynth +5. Export as OGG Vorbis at 96-128 kbps mono or low-bitrate stereo +6. Keep MIDI source files committed alongside audio so re-instrumentation is possible later + +**Why MIDI-source over direct audio gen:** +- Tiny working files (10s of KB vs. multiple MB) +- Procedurally controllable (transpose, tempo shift, re-instrument at runtime if you want) +- Better quality results from AI tools than direct audio gen for instrumental music +- Vanilla MIDI sounds dated, but a good soundfont makes it sound like real instruments + +### Anti-repetition strategies + +The Kelethin trick is that the music never feels like it's looping at you. Apply these: + +- **Long compositions** — minimum 3 min per loop, ideally 5+ +- **Multiple variants per location** — 2-3 themes for each major surface, crossfade between them randomly +- **Time-of-day mixes** — if Guild Hall has morning/evening backdrop variants, the music has matching mixes (lighter morning instrumentation, denser evening) +- **Silence is allowed** — music doesn't play 100% of the time. 30-60 sec gaps with just ambient SFX (hearth crackle, wind) are restorative, not awkward +- **Same key signature across related themes** — when crossfading between Guild Hall and Workshop themes, key continuity makes transitions feel natural + +## Music inventory (working set for v1) + +| Surface | Theme | +|---|---| +| Guild Hall (home) | 2-3 mellow themes, primary ambient — player hears these most | +| Forge | Workshop variant, slightly more rhythmic to match hammer ambience | +| Alchemy Table | Wispy, sustained chords, glass-bell accents | +| Library | Quieter, sparser piano + cello | +| Patron Court | Slightly more formal/regal but still mellow | +| Each region (~10) | One zone theme per region, all in related modes for tonal coherence | +| Special stings | Short (5-10 sec) musical moments for: rank up, Legendary craft, Patron completion | + +## SFX production approach + +### Sourcing +- **Sonniss GDC bundles** (free, ~30GB+/year) — covers most generic SFX needs +- Targeted purchases from Sound Effect Studio, GameDev Market, Boom Library for specific gaps +- **Layer simple sounds for complexity** — a "craft completion" can be hammer + chime + soft applause = unique signature, even though each component is a stock sound +- **Pitch/tempo shift** in DAW to create variants — same source sound, six different timbres + +### Anti-Wilhelm discipline +- Every frequently-played UI sound has **4-6 variants** in a rotation pool +- The audio engine picks one at random per trigger, never repeats consecutively +- Workshop ambient loops are slow-evolving (no obvious 2-second loop point) + +## SFX inventory (working set for v1) + +### UI +- Tap (3-4 variants — soft thunk, light click, small chime) +- Swipe / tab change (2-3 variants) +- Modal open / close +- Notification chime (3 tonal variants — info / positive / warning) +- Badge appears on Guild Hall scene (subtle ping) + +### Workshop ambience (looping under music) +- Forge: bellows, hammer rings, occasional metal clang +- Alchemy: bubbling, glass clink, drip +- Loom: rhythmic click-shuttle +- Carpenter: saw, plane, chisel +- Library: page turn, quill scratch, candle flicker + +### Crafting (per [13-reveal-choreography.md](13-reveal-choreography.md)) +- Crude reveal: soft thump +- Common reveal: hammer crunch +- Fine reveal: hammer + metallic chime +- Masterwork reveal: hum → rising chime → metallic clang → soft choir flourish +- Legendary reveal: low rumble → slow rising swell → *crack* of light → choir + organ swell +- Critical-success break: rising "wait — no" tone before upgrading +- New Discovery: parchment whoosh + book shut + +### Expedition +- Door open / close (Guild Hall front door) +- Soft footsteps fade-out (departing party) +- Soft footsteps fade-in (returning party) +- Coin drop (loot received) +- Map page flip (world map open) + +### Ambient (per backdrop) +- Hearth crackle +- Wind (soft, looping, with subtle variation) +- Rain (for relevant zones) +- Distant tavern murmur (for town-adjacent zones) +- Insect chitter (for forest zones) +- Cave drip (for subterranean zones) + +## Mobile audio engineering + +- **Format**: OGG Vorbis throughout (smaller than MP3, no licensing concerns, native support in every engine) +- **Music**: 96-128 kbps, stereo or low-bitrate stereo +- **SFX**: 64-96 kbps, mono (mobile speakers are mono; saves space) +- **Master normalization**: all assets normalized to a consistent loudness target so nothing pops at full volume +- **Bus mixing**: separate buses for Music / Ambient / SFX / UI with independent volume sliders in settings (accessibility requirement, also good for player preference) +- **No spatial audio needed** — 2D card game, no 3D positioning required. Slight stereo positioning of workshop sounds (forge slightly left, alchemy slightly right) is a nice touch but optional. + +## Accessibility + +- Independent volume sliders per bus (Music / Ambient / SFX / UI) +- "Reduce ambient loops" setting (some players hate constant hammers / bubbling under everything) +- Music-off / SFX-only mode +- Visual feedback for all important audio cues (the reveal choreography is already visually complete — audio enhances, never replaces) + +## Open questions + +- Which AI MIDI tool ends up best for this style — ACE, MuseNet-style, or something newer +- Soundfont selection — do we ship with FluidR3_GM (free, decent) or invest in a fantasy-specific soundbank +- How many distinct music tracks for v1 — probably 8-12 minimum (Hall + a few workshops + ~3 zone themes + stings) +- Total audio budget on disk — likely 30-80 MB for music + SFX combined, plenty for mobile +- Voice acting — none planned (matches our "no LLM in critical path" discipline and saves significant scope), but worth confirming +- Haptic feedback on mobile — paired with audio cues (vibration patterns per quality band) — meaningful enhancement or unnecessary? diff --git a/docs/16-engagement-layers.md b/docs/16-engagement-layers.md new file mode 100644 index 0000000..76ee033 --- /dev/null +++ b/docs/16-engagement-layers.md @@ -0,0 +1,124 @@ +# Engagement Layers (Crafting Feel) + +Crafting is the *primary* action of the game — not seasoning on a meta-game like Stardew or Minecraft. That means the bar is higher. Drag-to-station with a strategic input layer is enough for *thinking* engagement, but it's not enough for *feeling* engagement. Three additive layers fix that: + +| Layer | What | Status | +|---|---|---| +| **Layer 1: Juice** | Visceral feedback on every interaction (drag-snap, particles, audio, haptics) | Recommended, not formally accepted | +| **Layer 2: Master's Touch** | Brief skill-timing mini-game per craft, opt-in, difficulty-scaled | **Designed** (this doc) | +| **Layer 3: Adjacent-station synergy** | Passive bonuses for thoughtful parallel-craft scheduling | Recommended, not formally accepted | + +References for "primary-action games that feel amazing": **Vampire Survivors** (almost no decisions, every kill is a tactile pop), **Forager** (click rock → satisfying), **Cookie Clicker** (literally just clicking, juiced perfectly), **Slay the Spire** (cards already chosen, but each play feels meaningful). + +## Layer 1: Juice (recommended) + +The single biggest miss in vanilla drag-to-station crafting. Make the *act* feel like bubble wrap: + +- Ingredients drag with weight. They *snap* into station slots with a small particle burst, audio per placement, brief haptic +- Stations have idle animations that intensify when you hover ("ready to receive") +- A small visual countdown / heartbeat as the craft "thinks" +- Workshop ambient SFX layer up briefly during craft action +- Card lift-out at completion uses the reveal choreography (already designed in [13-reveal-choreography.md](13-reveal-choreography.md)) + +Forager and Vampire Survivors are mechanically simple games whose secret is *all* in the juice. Worth taking that lesson seriously — this layer carries the moment-to-moment feel for every player whether they engage with the others or not. + +## Layer 2: Master's Touch (designed) + +Inspired by the dart mini-game in *Sherlock Holmes: Case of the Serrated Scalpel* — two-axis energy meters, simple input, difficulty-scaled. Brief skill-timing per craft that *nudges* outcomes without dominating them. + +### The mechanic + +After the player hits Craft, the result auto-resolves over the craft's duration. *During that window*, two energy meters appear in sequence: + +- **Meter 1 — Quality**: horizontal bar with a moving indicator and a green zone. Tap to lock. Hitting green nudges the quality roll up. +- **Meter 2 — Critical**: appears after Meter 1 locks. Same mechanic. Hitting green increases critical-success chance. + +**If the player ignores the meters, the craft auto-resolves on its timer with the engineer's roll alone. No penalty.** This is the foundational rule — engagement is opt-in. + +### Difficulty scales meter behavior + +Faster meter + smaller green zone = harder timing. Difficulty is a function of: + +- **Recipe baseline** — Crude Pickaxe = slow; Lapis-Infused Moonsilver Falchion = fast +- **Target quality vs. engineer skill** — attempting Masterwork roll with a journeyman narrows the zone further +- **Critical-attempt toggle (opt-in)** — further narrows the zone in exchange for bigger crit bonus + +A player attempting ambitious crafts is leaning in, timing carefully. A player banging out 20 Crude pickaxes for sale hits Craft → wait → done. + +### Themed skinning per station + +Universal input mechanic, station-specific visual: + +| Station | Skin | +|---|---| +| Forge | Hammer-strike rhythm — meters are timing of two hammer falls | +| Alchemy Table | Stir-and-pour — stir tempo + pour-in moment | +| Loom | Shuttle-pass timing | +| Carpenter | Plane-stroke + chisel-tap | +| Glassworks | Furnace-pull + blow-rhythm | +| Jeweler | Setting-press + polish-stroke | + +Same inputs, recognizable craft motions per discipline. Players develop favorites without learning new mechanics. + +### Reward magnitude (bounded) + +The nudge matters but doesn't dominate. Working numbers: + +- **Hit both green** → +1 to quality-band roll, +5% critical chance bump +- **Hit one** → small partial bonus +- **Miss both / skip** → engineer-skill roll only, no penalty +- **Critical-attempt toggle** → +15% crit chance if both hit, smaller margin for error + +**Engineer skill remains dominant.** A Master Engineer with both meters missed should beat a Journeyman with both meters hit on average. The mini-game polishes the result; it doesn't replace the strategic layer. + +### Trait integration + +Roster traits become visibly meaningful in the meter: + +- **Lucky** — widens green zones for that engineer's crafts +- **Steady** — slows meters slightly +- **Hasty** — narrows zones (penalty), small speed bonus to craft duration +- **Drunk** — meters wobble erratically; high variance + +This is how traits become *felt* during play, not just stat numbers in a tooltip. + +### Tie-ins + +- **Onboarding** ([12-onboarding.md](12-onboarding.md)) — the forced-crit Lantern moment is "you nailed both meters." Player feels they earned it. The earlier Crude Pickaxe craft gently introduces the meter on slow speed with a wide green zone (essentially impossible to miss) so the mechanic is taught before it matters. +- **Reveal choreography** ([13-reveal-choreography.md](13-reveal-choreography.md)) — critical-success mid-flip fires both from lucky engineer rolls AND from perfect Master's Touch timing. Same dopamine moment, different earnings paths. +- **Veteran auto-craft** — toggle in settings to skip the meters by default for queued bulk crafts. The mini-game is for the items that matter, not for filling sale queues. + +### Accessibility + +- Auto-craft toggle (skip meters always) — no penalty +- Larger green zones option (motor-impairment / casual mode) +- Visual feedback for meter timing strong enough that audio-only or visual-only players can both engage +- Pause-during-meter-tap for cognitive load (no tight reflex pressure) + +## Layer 3: Adjacent-station synergy (recommended) + +Reward thoughtful parallel-craft scheduling without adding a new active mechanic. Pure rule additions to the existing system: + +- **Shared-warmth** — two parallel crafts sharing an ingredient type (both use iron) → both get a small quality bonus +- **Chained refining** — one craft's output is the next queued craft's input → small efficiency bonus, faster turnaround +- **Engineer cross-assist** — same engineer assigned to two adjacent crafts → fatigue cost, small bonus to both +- **Discipline pair** — Smith + Jeweler crafting at the same time → set-piece bonus when their outputs combine into one final item later + +This is a *thinking* hook that emerges from existing systems. Players who optimize feel clever; players who don't still get fine results. No new UI, no new mini-game. + +## What we're explicitly NOT building + +- A mandatory mini-game per craft (kills veterans, hates the loop) +- Skill bars / mastery numbers per craft type (deliberately cut earlier) +- Real-time combat or twitch-action elements (wrong game) +- A sticker-album of mini-games (one per station with totally different mechanics is fragmenting; the themed-skinning approach keeps the input language unified) + +## Summary + +The combination — Juice everywhere, Master's Touch as opt-in skill nudge, Synergy as opt-in optimization — gives crafting **viscera + skill + strategy** without any single layer having to carry alone. Players who want to button-mash get satisfying button-mashes. Players who want to optimize have meaningful levers. Players who want to roleplay just craft and equip and admire. + +Open questions: +- Visual representation of the meter — vertical / horizontal / pendulum / circular dial? +- Sound design per station's themed meter (hammer-rhythm vs. shuttle-click vs. pestle-grind) +- Critical-attempt toggle — is this a craft-time choice, or a default setting per item type? +- Layer 1 and Layer 3 — these are recommended but not yet formally accepted. Worth pulling on each as separate threads later. diff --git a/docs/17-foldins-2026-05-12.md b/docs/17-foldins-2026-05-12.md new file mode 100644 index 0000000..fbd15c2 --- /dev/null +++ b/docs/17-foldins-2026-05-12.md @@ -0,0 +1,410 @@ +# Fold-ins: Brainstorm Session 2026-05-12 + +Loose notes on what shifted, expanded, or got added during the May 12 brainstorm. Not a spec. May not all make the game. Existing docs (00–16) stay as-is; this rolls in the deltas without rewriting them. + +## Strategic shifts + +### Platform: mobile → Steam-first + +[00-concept.md](00-concept.md) opens with "A mobile game." Working assumption now is **Steam (PC) as primary**. Mobile deferred or dropped. Reasons: + +- Premium monetization is the *default* on Steam, the exception on mobile +- ~5–10× revenue per copy at comparable conversion rates +- Wishlist/Next Fest discovery system actually exists on Steam +- Existing design (drag-to-station, info-dense UI, reveal choreography) is structurally Steam-shaped; we were working around mobile constraints +- Pixel art is more welcome on Steam than mobile +- Steam Workshop is a force multiplier given the data-driven architecture + +Mobile port stays *possible* later — offline-first / no-live-service architecture choices leave the door open. + +### Pacing: real-time idle → session-based, idle-within-session + +Existing docs lean Melvor-style real-time idle. Steam shifts this to **session-based, idle-within-session** — expeditions resolve in *in-session minutes*, not real-world hours. Loop Hero / FTL shape. The "AFK" is *within* the session, not while the game is closed. + +Numbers throughout existing docs (expedition durations, craft times, rank cadence) need re-scaling against in-session minutes, not real-world hours. Defer the actual rescaling to sim-driven tuning. + +### Monetization lane + +Premium upfront, ~$10–15 on Steam, demo for Steam Next Fest. Off the table: gacha, energy timers, IAP-to-skip-friction, FOMO events. + +Realistic envelope: $0–2k (flop) / $5–30k (modest indie success) / $50k+ (hit). Designing for the *modest indie success* lane. + +### Moral guardrail: the morning-after test + +Articulated as a design constraint: *would a player who put 30 minutes in last night wake up and feel fine about it? Not addicted, not wrung out, not "I don't know why I did that"?* If a mechanic only works by failing this test, it's out. Pair with "always something shiny" — both apply. + +### Niche positioning (sharpened) + +Was: "Melvor meets Darkest Dungeon." +Now: *"A crafting-guild idle with Wartales-style provisioning, CK3-style event streams, and open-ended expedition sessions you recall at will. Pixel-art, single-screen, Steam premium."* + +The Wartales/Battle Brothers provisioning lineage is the actual differentiator (see Consumables below). Nothing in the crafting-primary genre does this. + +## Stack and tooling (tentative — spike before committing) + +Developer fluent in Python, C, C++, Rust, IEC61131, JS/TS — *not* C#. Strongly prefers terminal/code-editor workflows over GUI editors. + +Leading candidates: + +1. **TypeScript + Phaser (or PIXI) + Tauri** — code-first, peak AI productivity for the developer's stack, web stack is natively brilliant at animated UI, Tauri ships small native binaries to Steam +2. **LÖVE + Lua** — code-first, Balatro-tier shipping track record, smaller corpus +3. **pygame-ce** — deepest Python familiarity, but framework grain doesn't match info-dense animated UI + +Out for this project: Godot (GUI-editor primary grain), C# stacks (extra language), Bevy/Rust (compile-time iteration tax), C++/raylib (UI work in C++ is painful), Hazel (teaching engine). + +Recommended spike before committing: one weekend in Phaser+TS+Tauri, one in LÖVE+Lua. Same toy each — single workshop screen, drag-an-ingredient-to-station, Master's Touch meter, one card reveal. + +## Data pipeline + +User owns the visual asset pipeline (ComfyUI + Python scripts) — out of scope for tooling discussions. + +The *data* pipeline: + +- **Source format**: TOML files per domain (`data/materials/`, `data/recipes/`, `data/patrons/`, etc.), git-versioned, text-editable +- **CSV as bulk-import escape hatch**: for AI-generated or spreadsheet-brainstormed batches; converted to TOML once imported +- **Validation**: Pydantic schemas at the tooling layer +- **Procedural expansion**: templates × materials × quality bands × affixes → expanded item space (potentially 10k+ permutations) +- **Runtime artifact**: SQLite (same engine for content and save state) +- **Simulator**: Python initially; port to TS if/when stack settles there, so sim and game share logic + +**Strategic milestone**: sim + recipe scope locked first; *then* game code. Lock the 30–60 hour content envelope by simulation before touching the runtime. + +## Progression model — substantial revision + +[05-economy-progression.md](05-economy-progression.md) correctly rejected per-skill XP grind ("craft 300 daggers to level Smithing"). But it over-corrected — no visible quantified bars means players have nowhere for the "I'm almost there" feeling to live. + +### Multiple visible progression surfaces + +| Surface | Visible bar | Advances by | Avoids grind because | +|---|---|---|---| +| Guild Rank (spine) | XP toward next rank | Orders + discoveries + masterworks + expeditions | Multiple sources; can't farm one | +| Recipe Library | % discovered (47/200) | First craft of a recipe | Repeats don't count | +| Material Catalog | Found (32/120) | New material drop | Repeats don't count | +| Patron Favor | Per-patron (8/10) | Fulfilling their orders | Bounded per patron | +| Engineer Career Arc | Apprentice → Journeyman → Master | First-Masterwork, first-Legendary, time-served | 3 stages, milestone-gated | +| Quality Records | Best so far per recipe | New quality band on that recipe | Bounded by recipe count | +| Region Map | % explored | Expeditions to new places | Discovery-gated | + +A glance at the session opening shows multiple "almost there" hooks at once. None advance by repetition. + +### Capability stack — the positive constraint + +A craft attempt's success depends on the *sum* of: + +| Factor | Gates | Built by | +|---|---|---| +| Engineer career stage | Quality ceiling | Apprentice → Journeyman → Master, milestone-gated | +| Engineer traits | Modifiers (Lucky, Steady, Hasty, Drunk) | Hire pool quality | +| Station tier | Recipes attemptable at all | Crafted upgrades + materials | +| Tools equipped | Discipline-specific bonuses (Masterwork Smith's Hammer) | Crafted in-game | +| Materials provided | Output ceiling (Crude inputs can't yield Masterwork) | Expeditions, market, rewards | +| Target quality band | Difficulty multiplier | Player choice, opt-in | + +Effective capability vs. recipe demand → outcome. + +### Attempt risk gradient (over-capability attempts) + +| Mismatch | Outcome | +|---|---| +| Mild | Result drops one quality band below target; materials consumed | +| Moderate | Chance of total failure, material waste, tool damage | +| Severe | Engineer fatigue/injury, station damage, occasional cursed outcomes | +| Long-shot | Small chance of against-the-odds Masterwork — Library entry, story moment | + +Recipe from expedition you're under-capability for? Burn the materials trying now, or save the scroll and build up? Either is a real decision. + +### Pillar additions + +- **Capability matters.** Items, gear, stations, engineers, and materials compound systemically. +- **Friction is real.** Attempts above capability cost real things. Sends above capability risk real things. +- **Progression visibility.** Players always have 3+ visible bars they're proximate to advancing, each by varied play. + +## Expedition system — substantial expansion + +[04-expeditions.md](04-expeditions.md) treats expeditions as "AFK timer with procedural narrative report on return." Major shift. + +### Risk tiers with visible legibility + +Risk is gradient, telegraphed *before* the player commits. + +| Tier | Example | Failure modes | Stakes | +|---|---|---|---| +| 1 | Moo-Moo Meadows | Empty haul, minor scrape | Time only | +| 2 | Misty Hollow | Minor injury, scuffed gear | Days off-duty | +| 3 | Burned Hills | Serious injury, gear loss | Weeks off-duty | +| 4 | Ravenwood Crypt | Death, capture, permanent loss | Roster member gone | +| 5 | The Inverted Spire | Party wipe, story consequences | Multiple losses, rep hit | + +Pacing principle: **tier 1–2 frequent and chill**, tier 4–5 are *campaigns* you prepare for. Before sending: visible math (*"Dora vs. Ravenwood: 60% severe injury, 25% death, 85% return empty-handed."*). Telegraphed deaths are *story*; surprise deaths are *punishment*. + +### Interactive event stream (the CK3 layer) + +Expeditions surface decision/flavor moments into a queue (sidebar feed), not as modal interrupts. Player works them at their own pace. + +Event mix per expedition: + +- **~70% flavor pings** — zero-choice texture (*"Brom found clover honey, +1"*). Cheap to author, constant pulse of life-happening-out-there. AI generates these in batches. +- **~25% light decisions** — binary, low stakes +- **~5% substantive decisions / story moments** — real branches, real stakes + +Trait- and capability-gated dialog: this is where roster identity matters most. *"Brom's Lucky trait reveals a third option."* *"Read the inscription (requires Lettered — none of your party has it)."* Equipped gear changes available options. + +### Auto-resolve via character traits + +If the player ignores an event too long, the party defaults to a trait-driven auto-choice. **The auto-choice IS the character.** Cowardly Dora retreats. Brave Brom pushes through. No nag pressure; character expression preserved. + +### Player-controlled return (significant shift) + +| Pattern | Example | Feel | +|---|---|---| +| A. AFK timer | Melvor mobile | Set duration, get loot | +| B. Active mission | XCOM, Darkest Dungeon | Escort scripted party through run | +| **C. Open-ended + player recall** | **This design** | Adventurer lives in field, you call them home | + +Pattern C is new for the crafting-guild genre. Adventurer remains in the field, generating events and loot, until the player recalls them. Closest analog: Stardew daytime exploration + CK3 event streams. + +What this enables: + +- Open-ended exploration — deep dives in a region searching for specific rare drops +- Time-as-resource — adventurer-hours budget across the roster +- Risk compounds with time — Tier-4 region kept-running is *very* dangerous +- Triage decisions when carry is full (the onyx example) + +### Forcing functions for return + +Player-controlled recall, but with mandatory-return conditions: + +- Fatal injury or near-death +- Out of rations +- Captured (rescue required, not recall) +- Patron deadline pressing on inventory needed at the guild + +### Death/loss mixed roll + +When things go wrong: not always permadeath. Roll across: + +- **Permadeath** (Darkest Dungeon — gone) +- **Captured / ransomed** (recoverable but expensive, time-pressured; possible side-quest) +- **Long-term wounded** (returns eventually, scarred — XCOM) +- **Lost gear/inventory only** (the run was a wash; person survived) + +Variance keeps return moments narratively alive. Permadeath stays on the table for severe mismatches. + +### Carry capacity + +Hybrid slots-with-weight-tiers: + +- N normal slots, each 1 item +- Heavy items (large onyx, masterwork weapons, large recipe tomes) take 2 slots +- Bag/saddlebag/cart capacity is another crafted-item axis — cobbler crafts the Pack of Holding + +Each rare find when carry is full is its own triage moment. + +## Consumables as core economic driver (new framing) + +**The expedition envelope.** Every expedition is bounded by what the party brings: + +- **Rations** → how long they stay (no food = short auto-return timer) +- **Carry capacity** (saddlebags, pack mules) → how much they bring back +- **Survival kits** (torches, ropes, antitoxins, climbing gear) → what zones they can survive in +- **Combat consumables** (potions, scrolls, bombs) → how many encounters they can stomach + +Unprepped trio auto-returns in 5 minutes with rabbit pelts. Same trio with Dark Elven Lumbass Bread, Five-Alarm Chili, Sturdy Saddlebags, and healing draughts stays out an hour and brings back several times the haul. + +What this fixes: + +1. **Closes the economy loop.** Materials → crafted consumables → expeditions burn them → expeditions yield materials. The economy was open at one end before. +2. **Tradeskill breadth gets *structurally* justified.** Alchemy, Cooking, Leatherworking, Tailoring all feed expedition capability. Pure-smithing guild bottlenecks on expedition depth. +3. **Engineer roster specialization becomes strategic.** "I need an alchemist before tier-3 viability" is a real gate. +4. **Pre-expedition planning** is a real surface (provisioning UI) without a new mini-game. +5. **Everything crafted has a downstream destination.** Nothing is dead loot. + +Balance target: **2–4× net multiplier** (prepped vs unprepped), not 10×. Sim finds the actual number. The user-facing *feel* of "way more loot with prep" can still be true at 3×. + +## Named character emergence and titles + +A unification that emerged this session: **all named characters in the world — patrons, engineers, adventurers, specialists — start *generic* and crystallize into named identities through specific gameplay moments.** The player doesn't pick from a static roster on day one; they *grow* the cast through play. + +### Character lifecycle (unified across roles) + +``` +generic role → named identity → signature crafts/feats → arc evolution → legacy +"Apprentice "Miles Tannen, Rhinestone Love Handles, Reaches Master, Heirloom items + Leatherworker" Lucky Halfling Studded Doom-Boots, leaves for own bearing his name + Tanner of Sunken The Bag of Holding shop → becomes in the Library + Reach" "Lover's Embrace" a patron +``` + +The same model produces three patron *origins* as variations on one system, not three separate systems: + +- **Encountered patrons** — Dorothy the Undead-Exploder, a rare encounter in Ravenwood Crypt. Survive the encounter; she takes interest in your guild; eventually commissions specialized arms. +- **Groomed-from-roster patrons** — Miles Tannen reaches Master tier; eventually opens his own shop in Goldshore; now *sends* orders to your guild rather than crafting in it. +- **Reputation-unlocked patrons** — At Guild Rank 5, Lord Aldric of Westmark notices you and begins commissioning. + +### Naming triggers (generic → named) + +| Trigger | Character class | Example | +|---|---|---| +| Crit on a signature craft | Engineers, specialists | Apprentice → "Miles Tannen" on the saddlebags crit | +| Survival of a high-tier expedition | Adventurers | Returns alive from Ravenwood → "Dora the Undaunted" | +| Milestone count | Anyone | First Masterwork / First Legendary / 10 Fine crafts | +| Rare encounter in the field | Future patrons | Dorothy the Undead-Exploder | +| Discovery moment | Adventurers, specialists | First to find Adamantine; first to read a crypt inscription | +| Time-in-roster + activity | Slow-burn | "She's been with us since the beginning…" | + +The trigger determines the *flavor* of the identity — crit triggers produce craft-signature names; survival produces adventure-signature names; discovery produces lore-signature names. + +### Procedural naming + signature items + +Given input traits + heritage + triggering event, AI batches: + +- A name with backstory fit ("Miles Tannen, Lucky Tanner of Sunken Reach") +- A *signature variant* of the craft ("Rhinestone Love Handles" replaces "Dusty Saddlebags" as his go-to) +- A short flavor blurb for the Library + +Signature items are where whimsy compounds. Generic items are functional; signature items are *characterful*. Same stats, different soul. Players collect characters' signature crafts the way Pokémon trainers collect badges. + +### Titles (LotRO-style layer) + +Each named character has: + +- A *name* (set on crystallization) +- A pool of *earned titles* (accumulated through specific deeds) +- One *displayed title* (player's choice) +- A *locked* flag (set on death/retirement; freezes display state and item attributions) + +Display format: +> **Miles Tannen, the Harebrained** +> *Lucky Halfling Tanner of Sunken Reach* + +#### Trigger taxonomy (whimsy + serious pair per achievement) + +| Trigger type | Example | Whimsy variant | Serious variant | +|---|---|---|---| +| Quantitative count | Crafted 100 saddlebags | "The Saddle-Stuffed" | "The Provisioner" | +| Subject-specific | Collected 50 rabbit pelts | "The Harebrained" | "Keeper of Hares" | +| Quality milestone | First Legendary | "The Touched" | "The Brilliant" | +| Survival | Survived 10 Ravenwood runs | "The Twice-Wraithed" | "The Crypt-Tested" | +| Discovery | First to find Adamantine | "The Lucky Idiot" | "The Bold" | +| Patron | 20 orders for Lord Aldric | "Court Pet" | "Court Favorite" | +| Easter egg | Crafted at midnight | "The Night-Owl" | "The Vigilant" | + +Each achievement seeds *two* title options. Player picks per character (or per earn, or with a default setting). Tone register flexes to the player. + +### Lost characters become legacy + +When `is_locked` flips (death/retire): + +1. **Display freezes.** "Miles Tannen the Harebrained" stays that way even if future achievements would've promoted his title. +2. **Item attribution permanence.** Rhinestone Love Handles crafted by Miles stay attributed to "Miles Tannen the Harebrained" forever. Legacy items carry their maker's identity *as it was*. + +Dora's +7 Teddy Bear of Banish Undead, after she falls in Ravenwood, can be equipped on another adventurer — but it's never *not Dora's bear*. The death/loss mixed roll now carries item-narrative weight. + +### Why this is structurally significant + +1. **Player agency in casting.** Two players end up with entirely different rosters and stories. The cast isn't designed by the designer; it's *grown* by the player. +2. **Emergent narrative without authored prose.** "Miles became Miles on day 8" — the player remembers because they were there. Cheap to produce, deeply meaningful. +3. **Investment compounds; losses sting more.** Each named character is *earned*. +4. **AI is the engine.** Procedural names, signature items, title pools, flavor blurbs — all perfectly AI-batched under a spec. +5. **Roster size constraint earns new purpose.** Was a balance number; now a constraint *forcing emotional investment*. You can only develop so many; choose wisely. +6. **Customization without dark patterns.** Title choice is expression, not gating. No premium title pack, no FOMO. Player agency in tone. + +### Data model sketch + +``` +Character { + id + procedural_name // set on crystallization + base_role // Apprentice Leatherworker, Recruit, etc. + heritage // Halfling, Dwarven, ... + traits // [Lucky, Steady, ...] + state // generic | named | retired | dead | legacy + earned_titles // [{title_id, earned_at, variant: whimsy|serious}] + current_title_id // the displayed title + is_locked // becomes true on death/retire; freezes display + item attributions + signature_items // [item_id, ...] + trigger_history // [crafts, expeditions, milestones — for title progress] +} + +Item { + ... + crafted_by_character_id + crafted_by_attribution_snapshot // captured at craft time; never updates +} +``` + +The sim has to model emergence rates — strategies that mass-recruit and burn through generics produce very different cast graphs than strategies that invest deeply in a few. Title-earning rates are a sim-tunable lever. + +## Tone reinforcement: whimsy is in scope, and a competitive advantage + +[10-tone.md](10-tone.md) already cites Machinarium + Quake (silly-meets-heavy). This session reinforces and sharpens: + +- Dark Elven Lumbass Bread, Five-Alarm Chili, +7 Teddy Bear of Banish Undead, 90lb-of-arbitrary-weight onyx, Grobb Plaguebringer's spring potpourri +- Voice spans named items, named adventurers, named expeditions, expedition events, titles +- A thousand serious medieval crafting games exist; whimsy is the differentiator +- Lean in: not everything serious, not everything silly. Tonal range *is* the texture. + +### Tonal anchor: darker WoW × Shrek + +Late-session reframing: the target tonal triangulation is **"darker WoW crossed with Shrek."** WoW was unafraid to put the grim plague-stricken-village quest right next to the goblin punt-yourself-from-a-slingshot quest. Shrek subverted fantasy seriousness while still earning real emotional beats. Both leaned into *"we know this is silly, and also this matters."* That's the range. + +Tools of the voice: + +- **Play on words** (Lumbass Bread, Plaguebringer's potpourri, Whirligig Crown) +- **Pop-culture jabs** in moderation — winks, not load-bearing references +- **Anachronisms welcome** (rhinestones, propeller hats, teddy bears, the absurd-weight onyx) +- **Earnest emotional beats** when they come — roster grief, character retirement, legacy items + +Constraint: **don't get carried away.** The world is mostly serious; whimsy is the *texture on top*. If everything's a joke, nothing lands. If the joke surface is too thin, the whimsy stops being a register and becomes a tic. + +### Design tenet: optimization creates absurd outcomes, and we lean in + +Most games hide stat-min-maxing behind transmog / glamour systems — "make it look the way you want." This game doesn't. **Crafted gear identity overrides character aesthetic.** If Miles Tannen's Whirligig Crown gives +12 Wisdom, your terrifying necromancer wears the propeller hat. The Archmage shows up in Lucky Bunny Slippers because they're BiS for that slot. + +Why this matters as a design choice: + +- **Player optimization is honored**, not hidden. The cost is visible silliness; that's the *trade*. +- **Crafter identity persists in worn gear.** "That's clearly Miles's hat" is part of why you remember Miles. +- **Comedy emerges from the system**, not from authored jokes. The propeller-hat-on-the-Archmage moment is funny *because the player chose it for rational reasons.* +- **Signals the game has a sense of humor about itself** — which makes the *serious* beats land harder when they arrive. The grief over Dora's death in Ravenwood works *because* the rest of the game has shown it can laugh. + +## Production characteristics (session synthesis) + +Observations that emerged late in the session, worth capturing because they validate (or constrain) the production envelope: + +### Production feasibility + +- **Not asset-heavy.** Everything is procedural — items, characters, signature variants, expedition events, titles, narrative blurbs. AI tooling handles the bulk; no hand-illustrated cutscenes or keyframed animations required. +- **No bespoke animation pipeline.** Shaders + code tricks (tweens, particles, reveal choreography) carry the visual layer. No animator hire, no rig system, no skeleton/IK work. +- **No combat to simulate.** Expedition resolution is dice + capability + traits + narrative events. No real-time combat, no melee/ranged math, no enemy AI. Enormous scope relief. +- **No twitch mechanics, low skill ceiling.** Master's Touch is opt-in skill-timing with auto-resolve. Players who can't or don't want timing aren't locked out. +- **Young-player accessible.** Whimsy + low skill ceiling + emotional investment lets the game work for kids without designing *down*. Adults get the same experience. +- **The retention engine is care, not pressure.** Roster grief, signature items, earned titles, patron arcs — emotional investment carries the long tail. + +### Worldbuilding stance: deep lore, shallow world + +There is no walking around. No avatar in a town square. No environmental storytelling through level geometry. Lore lives entirely in: + +- Item descriptions and flavor blurbs +- Expedition event text and character barks +- Patron and adventurer backstories that surface in event prompts +- Library entries for crafts, characters, regions +- Region descriptions and rumored encounters + +This requires **deep written content in narrow places**, but **no expansive world authoring**. The game sits on something that *could* be a larger story — the world *could* have an overarching plot — but the design is intentionally shallow on the macro, rich on the micro. The player imagines the world from textures they encounter; the game doesn't insist on filling it in. + +Right tradeoff for solo / AI-augmented production. World-walking would explode scope; lore in flavor text is AI-batchable and fits the established voice. + +### The texture, in one sentence + +*"Grobb Plaguebringer just returned from the depths of Ravenwood Crypt with essence of nightshade to put the final touches on his spring potpourri mastercrafted skill-up."* + +Named character (Grobb), earned title (Plaguebringer — serious variant on a grim subject), tier-4 expedition return (Ravenwood, with named drop), signature craft (spring potpourri), absolute whimsy on grim source material. If we ship 200 sentences with this texture, we have a game. + +## Still-open threads (parked for next session) + +- **Per-discipline capability vs. single engineer rank** — breadth pillar suggests per-discipline (Master Smith AND Common Loom-worker), but UI/state complexity is real +- **Per-recipe memory** — does the guild remember masterworking the Falchion? Diminishing returns on familiar recipes vs. fresh thrill of new? +- **Simulator structure** — discussed inputs/outputs, haven't designed it +- **Death/loss mixed-roll probabilities** — directional decision made, specific roll weights not pinned +- **Replayability shape** — Steam expects 8–30 hr; NG+, ascension, sandbox, or "you've seen it"? diff --git a/docs/18-expedition-engagement.md b/docs/18-expedition-engagement.md new file mode 100644 index 0000000..b0dff50 --- /dev/null +++ b/docs/18-expedition-engagement.md @@ -0,0 +1,308 @@ +# Expedition Engagement & The Latent Party Matrix + +Continuation of 2026-05-12 brainstorm. Extends [04-expeditions.md](04-expeditions.md) and builds on [17-foldins-2026-05-12.md](17-foldins-2026-05-12.md). Loose design notes, not a spec. + +## Premise + +The Steam pivot ([17-foldins](17-foldins-2026-05-12.md)) reframed pacing from mobile pop-ins to in-session minutes. A 5-min mobile pickup didn't need a spine — the pop-in was the spine. A 30–90 minute Steam session does. The session needs an arc that opens, escalates, resolves. + +**The expedition is the session spine.** A run is the contained arc: launch → orchestrate → recall → wind down. Everything else — crafting, hire pool, patron orders — happens *around* and *during* the run, but the expedition is what gives the session shape. + +The concern that prompted this work: "is there enough to actually *do* in this game?" Diagnosis — "always something shiny" was sized for the entire 5-min interaction. For a Steam session, the shiny-pulse is texture, not structure. The expedition has to do the structural work. + +## Sealed-run principle + +**Once an expedition launches, the player cannot reach into it.** No mid-flight gear swap, no resupply courier, no mid-run provisioning, no remote orders. The party is in the field on its own; the player is the home base. + +Engagement lives in the book-ends and the event stream: + +1. **The Brief** — pre-flight planning, party assembly, provisioning, routing +2. **The Stream** — in-flight event responses (decisions only, no material interference) +3. **The Report** — post-flight debrief, haul triage, narrative compile + +This rule is intentional. In-flight intervention destroys the morning-after test (cultivates compulsive check-ins) and trivializes the planning surface (any pre-flight mistake is recoverable mid-run). Sealing the run forces commitment, makes planning matter, and respects the player's time. + +## Three engagement surfaces + +### 1. The Brief + +Pre-flight is a real puzzle, not a checkbox. Working surfaces: + +- **Routing within the zone.** A destination isn't a single picker. Each zone has *paths* — Ravenwood has river road (slow, safe), ridge cut (fast, exposed), old culvert (capability-gated: needs torch + Lettered). Different paths bias different material distributions, event tables, and risk profiles. +- **Declared goal.** "We're after moonpetal" / "open hunt" / "patron job" / "discovery run." Biases event resolution and drop weights toward the goal. The party plays *toward* what you told them. +- **Risk dial.** Cautious / Standard / Aggressive. Modulates how the party auto-resolves events the player ignores. Aggressive Dora pushes into the cave-in; Cautious Dora retreats. Distinct from trait disposition — this is *party temperament for this run*. +- **Provisioning as commitment.** Carry capacity is shared between outbound provisions (rations, kits, consumables) and inbound haul. Bring 2 extra rations = stay longer, but 2 fewer slots for return loot. Real trade-off. +- **Party-comp synergies that read.** Tooltip-surfaces both known synergies (from Library entries earned through play) and budget shape. The build *takes shape* visibly as the player slots members. + +### 2. The Stream + +In-flight events are the only interactivity, so they have to work harder than flavor pings. Event class taxonomy: + +- **Flavor pings (~70%)** — zero-choice texture. AI-batchable. Carry tone and party-chemistry signal. +- **Light decisions (~20%)** — binary, low stakes, fast. +- **Capability-puzzle events (~5%)** — gated on party composition. "Cave-in. Strong clears it; Lettered reads the inscription; Lucky finds the cache. Your party has Strong only — push through or detour?" Party comp retroactively matters. +- **Chain events (~3%)** — multi-stage. Event 3 plants a clue; event 7 calls back; event 11 closes. A single thread stretches across the run. +- **NPC encounters (~2%)** — recurring named strangers across runs. Build relationships that pay off in future expeditions or patron emergence. + +Critical: events shape the *report*, not just the loot. Choices ripple into the post-run library entry, into trait shifts, into character titles earned. Decisions echo. + +### 3. The Report + +Debrief is a verb, not a popup: + +- **Triage sort.** Haul drops as a pile to sort — stockpile / sell-queue / patron-order / gift-to-engineer. Some materials are time-sensitive (fresh moonpetal sells higher, ages in-session). +- **Story compile.** Run produced N notable moments. Player picks which becomes the Library entry — editorial agency over the narrative record. +- **Trait evolution moment.** "Dora was tested in the cave-in. Mark her: Tested, Scarred, or let it pass?" Small post-run decision that shapes roster development. +- **Patron payoff.** If the run filled an order, the handoff is its own beat — Aldric pleased/displeased, rep shifts, named NPC reacts. + +## Optional rhythm: legs + +Single in-flight interactivity that respects the sealed-run principle: **between-leg check-ins.** + +An expedition has discrete phases — Approach → Subzone A → (optionally) Subzone B → Return. Inside a leg: pure event stream, auto-resolve baseline. Between legs: party radios in with a real decision-gate. *"We've cleared the foothills, hauling 6 ore. Push into the deep pit (Tier 4, better drops) or beat retreat?"* + +The player is answering a check-in, not reaching into the run. The party's already there; the player is choosing the next leg's character. FTL-map shape inside one expedition. Adds rhythmic decision points without breaking the seal. + +Trade-off: doubles authoring surface (per-leg event tables). Working position: include legs but keep most expeditions to 2 legs (Approach + Single Subzone + Return); 3-leg expeditions are higher-tier opt-ins. + +## Token-budget party model + +A party isn't *just* who's there — it's the shape of the budgets those people contribute to. Small World–inspired: each combination plays differently because the token flow is different. + +Working set of budgets: + +| Budget | What it spends on | Contributors | +|---|---|---| +| **Reach** | Legs unlocked, depth into zone | Scouts, Halflings, light-encumbrance, certain consumables | +| **Stamina** | Each event drains; party retreats when empty | Steady, Brave, healers, ration prep, alchemy supplies | +| **Carry** | Haul capacity | Strong, pack animals, saddlebags, Bag of Holding | +| **Insight** | Unlocks capability-puzzle events (Lettered, perceptive, lore) | Scholars, Lettered trait, certain heritages | +| **Standing** | NPC encounters, trades, negotiations | Merchants, Charming, faction-tagged characters | + +A party's *build* is its budget shape. Same headcount, different shape, different game. The number on the screen matters less than the readability of the shape — players should see *what kind of party* this is at a glance. + +## Builds as a real noun + +Budget shapes have natural archetypes. Players name them in their heads: + +- **The Foothold** — Steady gatherer + Brave defender. Tall Stamina, short Reach. Predictable run. +- **The Wedge** — Halfling scout + Lettered scholar. Tall Reach + Insight, almost no Carry. Library-hunter. +- **The Plunder Run** — Greedy gatherer + Drunk beastmaster + soldier. Tall Carry, weird Stamina, rich event texture. +- **The Quiet Path** — Stealth-tagged pair. Skips encounter events. Low ceiling, high consistency. +- **The Wraith Detail** — Necromancy-aligned trio for Ravenwood. Death-resistant in that biome; would die in a meadow. +- **The Mentor Run** — Master + Apprentice. Slow, but apprentice gains trait shifts faster. Investment, not haul. + +These aren't designer-authored archetypes shipped with the game. They're *emergent shapes* players discover and name. The system has to *produce* them, not enumerate them. + +The hire pool constrains exploration (you don't pick the ideal party, you pick from who applied) — which forces players into combos they wouldn't have chosen voluntarily. That's where surprise lives. + +## The latent party matrix (MBTI-adjacent) + +This is the structural core. A four-axis latent model that determines a party's chemistry — never exposed to the player, always shaping outcomes. + +### Why this works + +A 4-axis matrix is the smallest authoring surface that produces emergent character chemistry at scale: + +- **16 types from 4 binary axes** — vastly more compressible than authoring pair-by-pair (6 traits × 6 = 36 pairs before heritage/class/gear) +- **Each axis is independently meaningful** — author behavior per-axis, compositions inherit naturally +- **AI batches cleanly along axes** — "write events for high-Curious, high-Wandering, conflicted-Engagement parties in Burned Hills" is a tractable prompt; "write events for Brom + Miles" is not +- **Player folk-knowledge tracks coherence, not labels** — humans notice patterns without naming them. "Brom and Dora always find weird stuff" is exactly what happens when output filters through a consistent latent space + +The fact that it's **never surfaced** is what makes it work. The moment players see "Brom: ENFP," the magic is gone — optimization replaces mythology. Hidden, it stays folklore. + +### MBTI-adjacent, not literal MBTI + +The four-axis discipline is what we want. The I/E/S/N/T/F/J/P labels carry corporate-workshop baggage and validity debates we don't need to inherit. Internal labels for tgame, mapped roughly to the MBTI shape: + +| Axis | Pole A | Pole B | MBTI rough-equivalent | What it modulates | +|---|---|---|---|---| +| **Engagement** | Bold (+) ←→ Withdrawn (−) | E / I | How often events fire vs. get sidestepped | +| **Lens** | Concrete (+) ←→ Curious (−) | S / N | Drop bias — mundane resources vs. unusual/lore/cursed/whimsical | +| **Disposition** | Pragmatic (+) ←→ Sentimental (−) | T / F | Auto-resolve defaults — takes the loot vs. rescues the captive | +| **Tether** | Disciplined (+) ←→ Wandering (−) | J / P | Route adherence vs. tangent-following | + +A party type is the 4-tuple of axis tilts. 16 archetypes if axes are treated as binary; in practice the axes are continuous and the type is the *shape of the vector*. + +### The math + +Each character has a latent 4-vector, computed from heritage + traits + class. Each axis ranges roughly [−1, +1]. + +``` +# Character vector composition +character.vector = clamp( + heritage.bias_vector + + sum(trait.modifier_vector for trait in character.traits) + + class.bias_vector, + min=-1, max=+1 +) +``` + +**Example: Brom — Human, Brave, Soldier** + +| Component | Engagement | Lens | Disposition | Tether | +|---|---|---|---|---| +| Human heritage | 0 | 0 | 0 | 0 | +| Brave trait | +0.5 | 0 | +0.2 | 0 | +| Soldier class | +0.3 | 0 | 0 | +0.2 | +| **Brom** | **+0.8** | **0** | **+0.2** | **+0.2** | + +**Example: Dora — Halfling, Lucky + Cautious, Gatherer** + +| Component | Engagement | Lens | Disposition | Tether | +|---|---|---|---|---| +| Halfling heritage | −0.3 | +0.2 | 0 | −0.4 | +| Lucky trait | 0 | +0.4 | 0 | +0.1 | +| Cautious trait | −0.4 | 0 | 0 | +0.2 | +| Gatherer class | 0 | +0.1 | −0.1 | 0 | +| **Dora** | **−0.7** | **+0.7** | **−0.1** | **−0.1** | + +### Party aggregation + +Per-axis combination: + +``` +for each axis: + member_values = [m.vector[axis] for m in party] + party.vector[axis] = mean(member_values) + + if all(v >= 0 for v in member_values) or all(v <= 0 for v in member_values): + party.conflicted[axis] = False + else: + party.conflicted[axis] = True +``` + +**Important:** simple averaging produces muddy mid-types and erases chemistry. The conflicted-axis flag preserves the *interesting case* — when members pull opposite directions, that's not a wash, that's a distinct latent state with its own event class. + +**Example: Brom + Dora party** + +| Axis | Brom | Dora | Mean | Conflicted? | Reading | +|---|---|---|---|---|---| +| Engagement | +0.8 | −0.7 | +0.05 | **Yes** | They push-pull on every encounter | +| Lens | 0 | +0.7 | +0.35 | No | Tilts Curious | +| Disposition | +0.2 | −0.1 | +0.05 | No | Mildly mixed, neither pole | +| Tether | +0.2 | −0.1 | +0.05 | No | Roughly balanced | + +Reading: **mildly Curious, conflicted Engagement, neutral on the rest.** Their runs will be characterized by argument-events on engagement (push vs. retreat) and a bias toward unusual finds. Always weird, sometimes glorious, sometimes a mess. Player notices: *"Brom and Dora always find strange stuff."* + +**Example: Miles + Reynold (both Drunk + Gatherer + Brave)** — heavily Wandering, neutral Engagement (both Brave + both wandering = high Tether-negative + high Engagement-positive), mildly Curious. Reading: **Bold + Wandering + Curious.** They engage everything, follow every tangent, find weird things — but they also *come back drunk with immaculate pelts* because both are Gatherers with high quality bias on hide. Different flavor entirely from Brom+Dora. + +### Event weighting + +Each authored event has axis affinities — required (hard gate), preferred (soft weight), and conflict-affinity (events that only fire when an axis is conflicted). + +``` +def event_weight(event, party): + weight = 1.0 + for axis in AXES: + # Hard gates + if event.required[axis] is not None: + if sign(party.vector[axis]) != sign(event.required[axis]): + return 0 + if abs(party.vector[axis]) < event.required_magnitude[axis]: + return 0 + + # Soft preferences + if event.preferred[axis] is not None: + if sign(party.vector[axis]) == sign(event.preferred[axis]): + weight *= 1 + abs(party.vector[axis]) * AFFINITY_STRENGTH + + # Conflict bonus + if event.prefers_conflicted[axis] and party.conflicted[axis]: + weight *= CONFLICTED_BONUS + + return weight +``` + +Same shape applies to **material drop tables.** Drops are tagged with axis affinities; the sampler weights drops by party shape. A high-Curious + Wandering party in Burned Hills doesn't get the same haul as a high-Concrete + Disciplined party in the same biome. **Same zone, different game.** + +### Signal-to-noise + +For folk-knowledge to register, the latent type has to *visibly* skew outcomes. Working targets: + +- Tilted axes (|value| > 0.5) should produce **>75/25** bias in event sampling on that axis's affinities +- Conflicted axes should fire conflict-specific events at **>30%** rate when both poles are represented +- Signature finds (rare items, named events, library-worthy moments) should be **latent-gated** so they happen *to* characters who have the right chemistry, not randomly + +Players should notice a party's chemistry within **3–5 runs** of the same pairing. If the curve is longer than that, the system isn't doing its job. + +### AI authoring loop + +This is what makes the matrix economically viable. Authoring is per-axis-shape, not per-character-pair. + +``` +prompt: "Generate 30 expedition events for the Burned Hills biome, +targeting a party reading [high Bold, high Curious, neutral Disposition, +high Wandering, conflicted on nothing]. Tone: darker WoW × Shrek. +~70% flavor pings, ~25% light decisions, ~5% substantive moments. +Tag each with required/preferred axis affinities." + +→ AI produces a tagged event pool. +→ Runtime sampler weights toward party-matching events. +``` + +A few hundred prompts cover 16 types × ~5 biomes × ~3 leg-stages at sufficient density. The pool tags itself. Adding events post-launch is the same pipeline, indefinitely. **The system gets richer over time without redesigning anything.** + +Signature events — the rare, character-naming ones — gate to specific latent shapes. "Found the 90lb onyx" only fires for high-Curious + Wandering parties, so when it happens to *your* Brom and Dora, it feels like *their* story. Because it is. + +## Material properties as expression of party choice + +This is the closing loop — the part that makes the matrix more than a flavor system. **Material properties are exposed *through* the party profile.** + +### The pipeline + +``` +Party latent vector + ↓ +Material drop weights (tagged by axis affinity) + ↓ +Material properties surface based on what comes back + ↓ +Recipes reflect the materials available + ↓ +Crafted items express the materials' character + ↓ +Items carry the tone of the run that produced them +``` + +A whimsical party (high Curious + high Wandering) brings back whimsical materials — odd provenances, unusual properties, cursed-by-storage edge cases. Those materials demand recipes that handle their character. The recipes the player actually engages with are the recipes that work with *what they have to work with*. The crafted items inherit the absurdity. + +A pragmatic party (high Concrete + high Disciplined) brings back clean ore, predictable hides, standard botanicals. Their recipes are the clean ones. Their items are the reliable ones. + +### Tone emerges from play + +**The game is agnostic to the "best" path.** There is no canonically optimal flavor. Players gravitate naturally to combinations that resonate with them — some lean whimsy, some lean grim, some lean efficient. The game's tonal character on a given save is *produced by* the player's pairing choices. + +This is structurally significant: + +- **No tone authored by the designer.** The whimsy / seriousness mix on a given save is a player-driven outcome. Two players have demonstrably different games. +- **Recipes don't drive expedition choices; expedition choices drive which recipes matter.** This inverts the conventional crafting-game flow. Materials → recipes → items, not the other way around. +- **Absurd parties get absurd items, which fuel more absurdity.** A whimsy spiral is *positively reinforced* by play. So is a serious spiral. The player's gravitational well deepens with each run. +- **No "wrong" way to play.** Min-maxing optimal Concrete + Disciplined builds produces a coherent serious-craft game. Min-maxing chaotic Curious + Wandering produces a coherent whimsy game. Both are legitimate, both are deep. + +This is the design pillar this whole session was building toward. The expedition system + party matrix + material properties together form a **player-expression engine** — the player's flavor of the game emerges from their roster choices, not from a tone dial the designer set. + +### Property exposure mechanics + +Materials have multiple layers of identity ([14-materials.md](14-materials.md) covers type + quality): + +- **Provenance** — where it came from (Burned Hills moonsilver smelts hotter than Mire moonsilver). Set on drop. +- **State** — fresh / aged / cured / cursed-by-storage. Time-evolves. +- **Properties** — discovered through use. First few crafts surface property hints. Library populates. +- **Axis tags** — invisible to player; biased by the producing party's latent vector. Drives what *can* be discovered, what *can* be crafted. + +A high-Curious party's haul might include moonsilver tagged with whimsy-affinity. That moonsilver, when used in a recipe, biases the output toward absurd variants — propeller-hat results, rhinestone-decorations, lumbass-bread effects. The player doesn't see the tags. They just notice: *"the things I make with this kind of party always come out weird."* + +## Open threads + +- **Axis selection** — Engagement / Lens / Disposition / Tether is a working set. Want to prototype with placeholder axes and verify event ideas slot in naturally before locking. The four axes are load-bearing; wrong axes produce bland or contradictory output. +- **Combination math** — current sketch is per-axis mean + conflicted flag. May need to weight by trait strength (Brave is louder on Engagement than Cautious; Drunk is loud on Tether but mild on Lens). Sim-tuneable. +- **Conflicted-axis event density** — too many conflict events makes mixed parties feel like a mess. Too few makes the conflict-as-spice mechanic vanish. Target ~30% fire rate when conditions met, tune in sim. +- **Folk-knowledge surfacing aids** — beyond just outcomes, do we audio-tell, visually-tell, narratively-tell what kind of run this is? Subtle cues (different music sting, different report tone, different narrator voice) help players read the chemistry without spelling it out. +- **Stable-pairing pull** — folk knowledge requires repeated pairings. Current roster mechanics (mix-and-match, hire pool churn) may pull against this. Bond-via-shared-runs is the natural lever; may need other nudges (paired training, paired equipment, shared dwellings) to keep ~3–5 favorite duos in heavy rotation. +- **Material property authoring** — how many distinct properties per material category? How are they procedurally generated vs. hand-authored? AI batching here is similar to event authoring; same pipeline likely applies. +- **Surfacing without exposing** — Library entries that say "Brom and Dora have an unusual rapport in the field" are surfacing the *consequence* without exposing the math. How explicit does this go? Too explicit = "MBTI score." Too implicit = invisible. Target the middle: Library notes *patterns observed*, never *underlying axes*. + +## What this commits to + +Nothing yet — this is brainstorm notes. But the design is now coherent enough that the next session can move on whether the player-expression engine is the right pillar to anchor on, or whether it's overreach for a 6-month solo build. The sim ([17-foldins § Data pipeline](17-foldins-2026-05-12.md)) will need to model latent-axis dynamics to estimate authoring cost, content variety per save, and whether the folk-knowledge curve actually lands in 3–5 runs. diff --git a/docs/19-concepts-player-and-ui.md b/docs/19-concepts-player-and-ui.md new file mode 100644 index 0000000..9161e4e --- /dev/null +++ b/docs/19-concepts-player-and-ui.md @@ -0,0 +1,53 @@ +# Player & UI Concepts — 2026-05-12 brainstorm + +Continuation of [17-foldins](17-foldins-2026-05-12.md) and [18-expedition-engagement](18-expedition-engagement.md). Format is a scannable concept glossary — one short paragraph per idea. Categorize / prioritize later. + +## Player identity + +**Omnipresent observer.** The player has no avatar, no name, no in-fiction position. They watch the cast, occasionally intervene. Closest reference is Black & White's spatial framing (third-person, disembodied) — but not the deity-role implications. The cast doesn't worship or defer to the player. + +**Player as character volition.** When the player makes a decision for Brom, they *are* Brom in that moment. No "override" friction, no compliance dialogue, no resentment system. The character just does it. Player intervention is a lever on the cast's mind, not a command from above. + +**Three engagement levels are all valid.** Lean-in (read every bark, weigh every fork). Check-in (drop in periodically, intervene on what matters). Walk-away (launch and read the report). The party self-completes regardless; the player picks their depth per session. Honors the morning-after test. + +## UI pivot + +**Context-switched screens, not persistent HUD.** Each screen is a complete composition: hall, workshop, world map, expedition view, library, etc. No always-on portrait bar across all screens — UI elements belong to the screens they serve. Notification glow on the hall scene signals "there's something to look at" without forcing constant visibility. + +**Eye-of-the-Beholder portrait bar.** Persistent UI element *within* the expedition view. 4–6 framed portraits along the bottom: status overlays, expression shifts (4 fps), speech banners. The portrait *is* the character to the player's mental model. Same vocabulary as the hall's roster wall. + +**Journey graph (Oregon Trail × FTL).** Expedition view's central artifact. Branching node graph: round = flavor, square = decision, diamond = leg-end. Party-marker advances node-to-node, stepwise. Branches visible — decisions are *forks*, geographically committing. Past nodes stay on the graph as visited history. + +**Not a card game.** Cards-the-genre signifier is overloaded. The game uses illustrated artifacts (portraits, journal pages, dispatches, maps, item cards in inventory) but never has cards "in hand," a deck to draw from, or a discard pile. No mana, no hand management. The art format is honest; the gameplay framing is not card-game. + +**The "alive hall" stays first-person.** Existing 09-art-style discipline preserved. In-fiction reframe: the observer hovers close to the hall (peers into it as a doll's house) rather than standing in it as guildmaster. Minor revision to 08-ux-ui language needed. + +## Voice & content + +**Character voice is the personality channel.** The latent matrix (the MBTI-adjacent 4-axis system from [18-expedition-engagement](18-expedition-engagement.md)) expresses through *how each character speaks*. Bark library + journal voice + decision phrasing all flow from the character's latent profile. Players develop favorites by mouthfeel, not by stats. + +**Mixed addressing dynamic.** Characters chatter among themselves, narrate their own observations, occasionally address the player during decisions. Loose, not rigid. Texture difference between flavor (overheard) and decisions (directed) is natural. + +**Chronicler is a party role.** A character with the right traits (Lettered, Scholar, Cartographer) chronicles the run — produces journal entries. No chronicler in the party = sparse, garbled updates. Knowledge of the run is a capability gate, not a free service. The chronicler's voice shapes the journal's prose style. + +## Mechanism + +**Auto-quests with loot tables.** The whole expedition system reduces to a quest catalog with conditional triggers and weighted loot tables. Each auto-quest is a small state machine — nodes, decisions, branches, outcomes. Bounded, simulatable, AI-batchable. 90s CRPG mechanism dressed in modern surfacing. + +**In-character play is rewarded by access, not bonus.** No "stay in character +10" score. Decisions just route which content branches actually fire. Brom-played-Bold walks into the fight chain; Brom-played-Cautious walks past it. The triumphant-fight loot table doesn't roll if there was no triumphant fight. The system doesn't measure coherence; it routes content through actual decisions. + +**Out-of-character runs feel thinner, not punished.** The texture flows either way — a Cautious-Brom run still has flavor and outcomes, just less signature texture. Player learns experientially that letting characters be themselves produces richer runs. No tooltip teaches it. + +**Sim-tractable shape.** The Python sim ([17-foldins § Data pipeline](17-foldins-2026-05-12.md)) can now model expeditions concretely: party + decision policy + quest catalog → run outcomes (drops, character state, narrative arcs). Monte Carlo runs measure content variety, loot balance, in-character outcome gaps. Tunable before game code exists. + +## Content envelope + +**Quest catalog target.** ~200–500 auto-quests across all zones/tiers for v1. ~5 nodes each, 2–3 branches per fork. Tagged with axis affinities, capability gates, zone+leg constraints. Loot tables hang off the existing materials taxonomy. + +**Bark catalog target.** ~50–100 lines per character, latent-vector-shaped, context-tagged (route start, encounter, decision-pending, ration-low, wounded, etc.). AI-batched per character at crystallization. + +**Illustration target.** ~1000 quest-node images, AI-batched against the palette/dither pipeline. Plus per-character expression sets. Plus per-zone backdrops. + +## Glossary format trial + +This whole document is the proposed format for the broader idea glossary. One concept per blurb. Short. Cross-linkable. Sortable into categories (must-have / nice-to-have / parking-lot / future). If this format works, the next move is to back-fill the existing 00–18 docs by lifting their concept anchors into a single index file. diff --git a/docs/20-north-star.md b/docs/20-north-star.md new file mode 100644 index 0000000..f76eeb7 --- /dev/null +++ b/docs/20-north-star.md @@ -0,0 +1,70 @@ +# North Star + +The orienting principle for the project. Pinned 2026-05-12. All design decisions check against this. + +## The pin + +> **You start as an apprentice with rough tools and rough work.** +> **You grow into a guildmaster whose named legends bear your maker's mark across the realm.** +> **Every session, the visible world is a little richer. That richness *is* the reward.** + +## The design tenet + +> **Every meaningful progression beat has a visual expression.** +> **Stat increases without visual change are not events. Visual changes are.** + +Stats are bookkeeping. The visual change is the celebration. The game serves the felt experience of *watching your guild become a metropolis* — SimCity's logic applied to a craft hall. Underneath, complexity can be deep; on the surface, what the player sees grows. + +## Discovery, not demonstration + +The peak is **not shown upfront**. Players discover the climb as they make it. Aspirations are *near aspirations expanding outward*, never the legend revealed in hour one. This rules out the "previous master's wall" framing — it gives away the Lamborghini before the player has earned the right to want it. + +The Tier 5 visual splendor exists in the world's *lore* (whispered, rumored, occasionally glimpsed) but is never put on display for the new player. When you reach it, the reveal is yours. + +## Pacing curve + +| Phase | Hours | Feel | Player experience | +|---|---|---|---| +| **Apprentice** | 0–2 | Tutorial ramp | First Common. First hire. First expedition. First tier transition is the tutorial graduation. Player feels capable by hour 2. | +| **Journeyman** | 2–15 | Discovery | New zones unlock. Hire pool deepens. First Masterwork attempt. First patron tier. Player starts to feel the shape of the system. | +| **Master** | 15–30 | Mastery | Roster matures. First named legends crystallize. Signature crafts emerge. Player has favorite characters and a working strategy. | +| **Grandmaster** | 30–50 | Plateau & effort | Specific rare materials. Masterwork patron arcs. Deep specialization. Progress slows, intentionally — every step is earned. | +| **Legend** | 50+ | Endgame | The epic questline. The committed players' time-sink. Prestige rewards. The Lamborghini, finally revealed. | + +The early ramp is **fast** — mainstream-friendly, mobile-comfortable, hits dopamine quickly. The mid is **steady** — discovery and accumulation. The plateau is **earned** — players know why they're grinding. The endgame is **optional but worthy** — those who get there will engage. + +## The first tier transition + +Apprentice → Journeyman is the tutorial graduation. The onboarding arc ([12-onboarding](12-onboarding.md)'s Crude Pickaxe → Lantern) is the first half; the back half is the player's first independent expedition concluding in a Journeyman promotion ceremony — backdrop shift, banner, named acknowledgement from the cast. **First taste of "tier-up as event."** + +## The endgame questline + +The Legend tier (hours 50+) is the equivalent of MMO raid content — a specific bounded questline with prestige rewards that only committed players reach. Content volume can be modest; what matters is that it *exists* and is *worthy*. The fully-realized Lamborghini visual treatment lives here. + +## Concepts that fall out + +**Tier transitions as celebration scenes.** Backdrop swap, banner unfurl, narrator beat, new anchors filling in. Not a stat popup. A *moment.* + +**Visible-but-locked aspirations.** Drip-fed at the edges of the player's reach. Not exposed upfront. Always *one more rung* visible, never the whole ladder. + +**The Lamborghini.** The legendary tier visual peak. Animated holo + ornate paperdoll + bespoke art + named-and-titled cast. Fully revealed only on arrival. + +**Cosmetic-only customization stays earned.** Visual style is achieved, not picked. Resist transmog. Title choice and gear-within-tier are fine; tier-aesthetic itself is climbed to. + +**The "alive hall" grows with the climb.** More anchors filling in as roster expands. The hall is the metropolis-skyline. Empty hall = sad; bustling hall = the win condition. + +## What this pin commits to + +- **Production effort concentrates on visual systems** — paperdoll layering, tier-variant gear, shader/glow/particle stack, backdrop tier variants. This matches the AI-augmented pipeline (ComfyUI + palette/dither). +- **The 60-hour content envelope** has a concrete tier-shaped frame: 5 tiers × distinct-content-per-tier. Tractable for sim-driven scoping. +- **Story is texture, not load-bearing.** Whimsy and voice serve the experience but don't carry it. Risk concentrates on systems quality (manageable for the dev's background), not artistry quality (high-variance bet avoided). +- **Replayability shape has a default answer.** Arc closes at the Legend questline. Post-arc = open sandbox (keep playing your legend) and/or NG+ with kept signature heirlooms as starting gear. +- **The first hour's job is "make the player feel the first transition."** Not "show them the peak." The peak reveals itself through play. + +## What it rules out + +- Telegraphing the endgame visual treatment in early hours +- Stat-only progression beats (every meaningful rank-up has visual expression) +- Free-form cosmetic transmog systems +- Pure-narrative / coloring-book design as primary motivator +- A flat difficulty/progression curve — early ramp must be *fast*, late grind must be *earned* diff --git a/docs/21-smoke-test-caewins-forge.md b/docs/21-smoke-test-caewins-forge.md new file mode 100644 index 0000000..e6eb591 --- /dev/null +++ b/docs/21-smoke-test-caewins-forge.md @@ -0,0 +1,110 @@ +# Smoke Test: "Caewin's Forge" + +Visual pipeline validation exercise. Bounded scope (1–2 days). Defined 2026-05-13. + +## What we're validating + +**This is a vibe test, not a pipeline test.** The pipeline is already proven (see [samples/README.md](samples/README.md) — C64 multicolor tiger demonstrates extreme-constraint capability; skeleton sample demonstrates target-aesthetic capability). Mechanical correctness is solved. + +The open question: can the human-in-the-loop (prompting + curation + composition discipline) produce work with **vibe** — atmospheric storytelling, faces with inner lives, items with identity beyond function, tier differences that evoke *wanting*? Or does competent-but-lifeless output cap the project's ceiling? + +If vibe lands, "every meaningful progression beat has a visual expression" is structurally credible and the bones-first roadmap is greenlit. If it doesn't, we know now — before committing 4–6 months to data layer, sim, and game code that all assume a visual layer with soul. + +## The character + +**Caewin the Steady** (already canonized in [12-onboarding.md](12-onboarding.md) as the starter minion). + +- **Heritage:** Human, late 20s / early 30s +- **Class:** Apprentice Engineer, Forge specialty +- **Traits:** Steady, Lucky +- **Bearing:** Competent, grounded, soot-stained working clothes. The kind of person who rarely raises his voice but everyone in the workshop listens when he does. Not heroic, not chibi, not idealized. +- **Visual cues:** Dark hair, slight beard, leather apron over plain linen tunic, sleeves rolled. Calluses you can't see in a bust shot but can feel in the silhouette. + +## Asset 1 — Backdrop: The Forge (Tier 1) + +- **Canvas:** 640×360 native, palette-locked + Floyd-Steinberg dither +- **Perspective:** First-person POV, looking across the workshop floor from the player's vantage as guildmaster +- **Composition:** Anvil center-foreground, forge to the right with embers glowing, bellows visible, tool rack on the left wall, one window with warm afternoon light slanting in, smoke staining the ceiling +- **Tier-1 humble cues:** Exposed timber beams, cracked plaster, half-finished projects on the bench, dust motes in the light. No banners, no polished surfaces — apprentice's workshop, not guildmaster's forge +- **Anchor point:** Clear space where Caewin would stand to work (right of anvil, between anvil and forge). Should *read* as a place a figure could stand without obscuring the forge mouth +- **Atmosphere:** Warm hearth-light dominant. Muted earthen palette — browns, sepias, rust-reds, restrained ember oranges +- **References:** Diablo II Lut Gholein blacksmith, Baldur's Gate Friendly Arm Inn workshop, Machinarium's atmospheric interiors + +## Asset 2 — Portrait: Caewin the Steady + +- **Canvas:** ~256×384 (or your standard portrait canvas), palette-locked + dither +- **Framing:** Bust shot, frontal, slight off-axis +- **Expression:** Focused, calm, mouth closed, eyes attentive. *Not* smiling, *not* glowering +- **Wardrobe:** Leather apron over linen tunic, soot stains, no ornamentation, no gear, no jewelry +- **Background:** Simple atmospheric — soft blur of workshop tones, or flat muted neutral. Low contrast so the face reads +- **Tone target:** Competent and grounded. If it slips toward heroic-fantasy-protagonist or mobile-cute, it's missing + +## Asset 3 — Item Card: Crude Pickaxe (Common quality) + +- **Canvas:** 256×384 card canvas, palette-locked + dither +- **Frame:** Common quality border (silver-toned, no flourish, no gold inlay) +- **Silhouette scale:** Standard tool at ~85% of canvas, slight diagonal +- **Composition layers** (per [07-item-cards.md](07-item-cards.md)): + - Base: pickaxe silhouette + - Material tint: iron head (cool gray, slightly rusted), hardwood haft (warm brown) + - Component overlays: simple iron pommel cap at the haft base, basic leather grip wrap + - Effect aura: none (Common tier) + - Maker's mark: small stamp (e.g., "C." or whatever your mark style allows) +- **Tone target:** Honest, functional, almost-but-not-quite drab. The tool a competent apprentice produces — workmanlike, no embarrassment, no glory + +## Stretch goal — Same recipe, Fine quality + +If time permits, generate the **same pickaxe at Fine quality (Tier 3 reveal)** for direct side-by-side comparison: + +- Frame: silver border with subtle gold inlay +- Material: refined moonsilver pickaxe head (pale blue sheen), lacquered ironwood haft (deep brown with grain) +- Component overlays: ornate silver pommel cap, dyed leather grip wrap with small copper studs +- Effect aura: subtle outer glow (per [13-reveal-choreography.md](13-reveal-choreography.md) — Fine tier visual treatment) +- Same maker's mark, same silhouette, same scale + +**The test:** Common and Fine placed side by side. The visible difference should be *immediately readable at a glance*, without reading the quality label. If it isn't, the north star is in trouble. + +## Vibe evaluation — the actual eval + +This is the load-bearing question. Per asset: + +**Forge backdrop — atmospheric storytelling.** Does the workshop feel *lived in*? Details that suggest someone just was here — half-finished hilt on the bench, rag draped over tongs, a boot print in soot. Lighting that tells you the time of day and mood. The eye knows where to settle. +- *Failure mode:* forge + anvil + bellows + fire + tools all rendered correctly, reads as a list of objects in a room. No mood. + +**Caewin portrait — a face with inner life.** Do you look at it and think "yeah, that person would be quiet, notice things, never panic"? Personality readable. Traits (Steady, Lucky) subtly legible without being telegraphed. +- *Failure mode:* competent human male in leather apron, all features correct, no spark. Could be any tutorial NPC. + +**Item card — object with identity beyond function.** Does the pickaxe feel like a specific tool a specific person made and used? Wear pattern on the haft, character to the iron. Not generic stock-photo pickaxe. +- *Failure mode:* functionally-correct pickaxe centered in a frame that neither fights nor helps it. + +**Common vs. Fine (stretch) — the Fine makes you want it.** Not because of the border, but because materials are obviously richer, construction obviously more careful, pride visibly taken. +- *Failure mode:* Fine looks like Common with a gold border and glow shader. + +**The unifying test:** could a stranger looking at these assets, with no context, guess what kind of game this is and want to know more? Pipeline-correctness with vibe = the game ships. Pipeline-correctness without vibe = competent screensaver. + +## Mechanical checks (these matter, but they're table stakes) + +These are below the vibe eval, not in place of it — they need to pass but won't determine the verdict on their own: + +1. **Cross-asset coherence.** All three feel like they belong in the same game? Same palette density, same dither character? +2. **Composition cleanliness.** Item layers compose without floating bits or misaligned anchors? Backdrop has a real "place to stand"? +3. **Tier readability (stretch).** Common → Fine difference visible at a glance without reading labels? +4. **Production tractability.** *How long did each asset take?* If each is 8 hours of hand-cleanup, the envelope doesn't close even with great vibe. If it's 30 minutes of generate-and-curate, the production plan stands. + +## Verdict format + +One of three: + +- **"This will ship."** — Pipeline holds, output supports the claims, no major blockers. Specific praise + minor refinements. +- **"Close, but..."** — Promising direction with a specific gap (dither too dense / not dense enough, tone slips, anchors don't read). Concrete pivots. +- **"Stick with digital twins."** — Honest evaluation that the pipeline can't sustain the ambition. Specific reasons why, and whether a scope/style pivot would unlock it. + +Evaluation will be honest, not generous. That's what makes the smoke test useful. + +## Why this exercise gates the roadmap + +The bones-first roadmap (sim + data + game code first, art last) assumes the visual pipeline can produce the assets the design needs, in the volume and quality required, at a production cost that closes within solo + AI augmentation. That's a load-bearing assumption. + +The visual-progression north star *can't be validated by simulation*. It's a felt design claim. The only way to know whether the pipeline supports it is to render a tier-1 and a tier-3 asset and see if the difference produces the "I want that for my character" pull. + +If the smoke test ships green, the rest of the roadmap proceeds. If it ships red, we pivot — possibly to a different art direction, possibly to a different scope, possibly to a different style discipline. Better to find out now than at month 4. diff --git a/docs/99-open-questions.md b/docs/99-open-questions.md new file mode 100644 index 0000000..bdddb6c --- /dev/null +++ b/docs/99-open-questions.md @@ -0,0 +1,71 @@ +# Open Questions + +Parking lot for things to come back to. Not blockers, just decisions to make eventually. + +## Identity & flavor + +- Working title — `tgame` as placeholder, real title deferred until the game has more shape. When implementing: route the name through a single config constant, never hardcode `tgame` anywhere. + +## Art style detail (palette + 640×360 + late-90s era + first-person backdrops + 4 fps animation decided) + +- Pixel font choice and fallback rules +- Pixel rule exceptions for special moments (cinematic Legendary HD splashes)? +- Inventory grid: uniform 1-cell cards vs. Diablo-style multi-cell items? + +## UX / UI + +- Time-of-day cycling for Guild Hall backdrop: real time vs. game time vs. fixed sequence? +- Richness of "alive hall" minion overlays — do equipped weapons show, do they animate? +- Push notifications for AFK expedition completion — opt-in granularity? +- Accessibility: color-blind palettes for quality bands and effect auras. +- How "discoverable" is the scene navigation — do players figure out the forge corner is tappable, or do we add subtle UI hints? + +## Visual composition + +- Where does the composition QA step live in the asset pipeline? +- Do non-card UI uses (inventory icons, list views) re-render at low detail or use a baked thumbnail cache? +- Expose composition recipes to players (layer breakdown panel) or stay opaque? +- Color-clash policy: gameplay-prevent dissonant combos, or embrace them as feedback? +- Shader budget on mid-tier mobile — how many simultaneous focused cards with full shader stack? +- Atmosphere layers: ever animated (scrolling UVs) or static + shader animation only? + +## Materials & crafting depth + +- Scrap / salvage mechanic — break a finished card for partial refund? +- Quality progression curve — does the Crude floor rise with zone tier? +- Special material properties beyond quality (moonpetal is fundamentally magical regardless of band)? +- Pocket gating — are gnomish/necromantic materials zone-locked or do they crosscontaminate? +- Total material entry count for v1 (~30 raw / ~25 refined / ~20 components target). + +## Game systems + +- Mechanical depth of minion relationships (pure flavor vs. real meta-game). +- How recipe book is surfaced without becoming a spreadsheet. +- How aggressive experimentation penalty is for wasted rare ingredients. +- Quality cascade rules — can a great engineer rescue a Crude component? +- Destination granularity for expeditions — region/zone/encounter or just region/zone. +- Real-time progress bars vs. silent timers vs. push notifications for expeditions. +- Chained expeditions (24h follow-ups)? +- Hire pool: daily refresh? Cost to reroll? Special "fated" hires? +- Workshop parallelism — how many concurrent crafts allowed at each Guild Rank? + +## Tech + +- Engine: Unity vs. Flutter vs. Godot vs. native. +- Save format and signing. +- Cloud save provider (Firebase, Supabase, custom). +- How the future bazaar would be hosted (self-host vs. managed). + +## Scope + +- Minimum viable content for v1 launch. +- Asset budget per category. +- Style consistency across AI-generated assets. +- Original score vs. licensed audio. + +## Future + +- Bazaar / auction house — when + how. +- Leaderboards — what's measured (reputation, masterworks, rare discoveries)? +- Seasonal content — desirable, or live-ops trap? +- Mod / content tools so the catalog can grow community-side eventually? diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md new file mode 100644 index 0000000..a2f11d8 --- /dev/null +++ b/docs/GLOSSARY.md @@ -0,0 +1,562 @@ +# Concept Glossary + +Scannable index of every concept across the design docs. One-paragraph blurbs, source-linked. Categorize / prioritize / cull in later sessions. + +Format: **Concept** — short blurb. *(source)* + +--- + +## 0. Pinned Principles + +**North Star.** You start as an apprentice with rough tools and rough work. You grow into a guildmaster whose named legends bear your maker's mark across the realm. Every session, the visible world is a little richer — and that richness *is* the reward. *(20-north-star)* + +**Visual progression tenet.** Every meaningful progression beat has a visual expression. Stat increases without visual change are not events; visual changes are. *(20-north-star)* + +**Discovery not demonstration.** The peak is never shown upfront. Players discover the climb as they make it. Aspirations expand outward as the player progresses, never the whole ladder revealed at once. *(20-north-star)* + +**Morning-after test.** Would a player who put 30 minutes in last night wake up feeling fine? Not addicted, not wrung out. Mechanics that only work by failing this test are out. *(17-foldins)* + +**Always something shiny.** Every interaction — completed craft, returned expedition, new applicant, level-up, discovery — produces a moment worth a tap. The game pulses. *(00-concept, 05-economy-progression)* + +**Crafting is the engine.** Every other system exists to feed crafting better inputs or give crafted output a destination. *(00-concept)* + +**No grindy skill-ups.** Progression comes from unlocks (recipes, stations, regions, hires) and quality bands, not from repetition counters. *(00-concept)* + +**Breadth over depth-per-skill.** Many trades, broad recipe catalog, multiple paths to chase. *(00-concept)* + +**Pre-rendered, fully offline runtime.** AI tooling lives in production, not in the shipped game. No network calls except cloud save. *(00-concept)* + +--- + +## 1. Strategic / Production + +**Steam-first.** Platform primary is Steam (PC), not mobile. Mobile deferred or dropped. Existing docs that say "mobile" need revision. *(17-foldins)* + +**Premium upfront monetization.** ~$10–15 on Steam. No live service, no IAP, no FOMO, no energy timers. Demo + full purchase via Steam Next Fest is the marketing path. *(17-foldins)* + +**Modest earnings target.** Realistic envelope $5k–$30k for "modest indie success" tier. Not designed for blockbuster. *(17-foldins)* + +**Niche positioning.** "A crafting-guild idle with Wartales-style provisioning, CK3-style event streams, and open-ended expedition sessions you recall at will. Pixel-art, single-screen, Steam premium." *(17-foldins)* + +**Solo + AI-augmented production.** ~6 month project. AI batching covers procedural content (names, events, illustrations, prose). User owns the visual asset pipeline (ComfyUI + scripts). *(17-foldins)* + +**Stack candidates.** TypeScript + Phaser + Tauri (top), LÖVE + Lua (runner-up), pygame-ce (backup). Weekend spike in top two before committing. *(17-foldins)* + +**Production feasibility profile.** Not asset-heavy. No bespoke animation pipeline. No combat to simulate. No twitch mechanics. Young-player accessible. Retention engine is care, not pressure. *(17-foldins)* + +**Worldbuilding stance.** Deep lore, shallow world. No walking around. Lore lives in item descriptions, event text, character barks, Library entries. *(17-foldins)* + +**Working title is provisional.** `tgame` is a placeholder. Route the name through a single config constant. Real title deferred until the game has shape. *(99-open-questions)* + +--- + +## 2. Target Player & Engagement Profile + +**The Savvy Professional (primary target).** Programmers, designers, technical professionals with disposable income looking for an alt-tab break between focused work sessions. Wants cerebral engagement without MMO overhead. Premium price acceptable; quality over volume. *(brainstorm-2026-05-13)* + +**Alt-tab compatibility.** Game pauses and resumes cleanly. No real-time pressure that punishes leaving the window. Session state survives the player tabbing back to their IDE for 20 minutes and returning to find the world exactly as they left it. *(brainstorm-2026-05-13)* + +**Cerebral but accessible.** Mechanical depth rewards the curious; surface play works without it. Master's Touch is opt-in. The latent party matrix is invisible. Multi-tier supply chains are discoverable, not tutorialized. The game has hidden depth; it doesn't force-feed it. *(brainstorm-2026-05-13)* + +**Non-hand-holding discipline.** Treat the player as an adult after onboarding closes. Contextual one-line hints on first encounter, never multi-step popups. No nagging UI, no "are you sure?" friction, no condescending tooltips. *(brainstorm-2026-05-13, 12-onboarding)* + +**Four valid play modes.** Play by accident (low engagement, ambient companion). Vibe in a background tab (passive enjoyment, no pressure). Figure out and optimize (mid-engagement, deliberate). Min-max (deep mastery, all systems engaged). All four produce coherent experiences; the game serves whichever the player picks per session, and per session-segment. *(brainstorm-2026-05-13)* + +**Adjacent audiences served by accessibility.** Young-player accessible (no twitch, no reading-speed pressure). Color-blind palettes for quality bands. Independent audio bus controls. Larger Master's Touch green-zone option. The game targets the Savvy Professional but design discipline keeps the door open for adjacent demographics. *(brainstorm-2026-05-13, 17-foldins)* + +**Disposable-income permission.** Target audience justifies Steam premium pricing ($10–15). No need for IAP, ads, FOMO, or live service. The economic model and the audience match — premium price for premium time. *(brainstorm-2026-05-13, 17-foldins)* + +**Cerebral pacing.** The Savvy Professional brain comes off a complex codebase. The game should feel like a *different kind of thinking*, not the same kind less. Crafting decisions, party-build puzzles, expedition routing — all reward thought, but the thinking is *playful*, not productive. Recovery-shaped engagement, not work-shaped. *(brainstorm-2026-05-13)* + +--- + +## 3. Player Identity & Engagement + +**Omnipresent observer.** Player has no avatar, no name, no in-fiction position. They watch the cast and occasionally intervene. Closest reference is Black & White's spatial framing — without the deity-role implications. *(19-concepts-player-and-ui)* + +**Player as character volition.** When the player makes a decision for a character, they *are* that character in that moment. No override-friction, no compliance dialogue, no resentment. *(19-concepts-player-and-ui)* + +**Three valid engagement levels.** Lean-in (read every bark, weigh every fork). Check-in (drop in periodically). Walk-away (launch and read the report later). All produce coherent runs; player picks per session. *(19-concepts-player-and-ui)* + +**In-character play rewarded by access, not bonus.** Decisions route which content chains fire. No hidden coherence score. Out-of-character runs feel thinner, not punished. *(19-concepts-player-and-ui)* + +--- + +## 4. Core Loop & Pacing + +**The loop.** Gather → Refine+Craft → Equip/Sell/Fulfill Patrons → Hire+Upgrade → Send better-equipped teams to richer zones → better materials. No dead ends; every step pulls into the next. *(01-core-loop)* + +**Hybrid active + idle.** Active when sitting down (deciding, dragging, planning). Background while away (long crafts, expedition timers). *(01-core-loop)* + +**Session-based pacing.** Expedition durations resolve in in-session minutes, not real-world hours. Loop Hero / FTL shape. The "AFK" is *within* the session, not while the game is closed. *(17-foldins)* + +**Expedition as session spine.** A 30–90 minute Steam session has an arc — launch → orchestrate → recall → wind down. The expedition is the spine; everything else happens around and during it. *(18-expedition-engagement)* + +**Pacing curve.** Apprentice (0–2h tutorial ramp) → Journeyman (2–15h discovery) → Master (15–30h mastery) → Grandmaster (30–50h plateau & effort) → Legend (50+h endgame questline). *(20-north-star)* + +--- + +## 5. Roster & Characters + +**Named characters with persistent identity.** Portraits, traits, backstory. Loseable in the worst case. You grow attached — that's the point. *(02-roster)* + +**Roster cap 10–30.** Scales with Guild Rank. *(02-roster)* + +**Classes.** Gatherer, Soldier, Engineer, Merchant, Scholar/Cartographer, Beastmaster. Fixed at hire; subspecs branch later. *(02-roster)* + +**Traits.** Rolled at hire. Modify outcomes. Examples: Greedy, Brave, Lucky, Devout, Ill-tempered, Drunk. Trait pool grows; some traits gained/lost via events. *(02-roster)* + +**Paper-doll portraits.** Layered sprite composition. Base pose + gear overlays + face/hair/costume layers combined combinatorially. *(02-roster)* + +**Relationships (Nemesis-style).** Bonds, Rivalries, Mentorships, Grudges. Emerge from shared expeditions. Depth-or-flavor TBD. *(02-roster)* + +**Hire pool.** Daily refreshed applicant pool. Pool quality scales with Guild Rank. Combinatorial portraits + backstories. *(02-roster)* + +**Hire-pool constraint forces exploration.** Players can't hand-pick the ideal party; they work with who applied. That constraint is where combo surprises live. *(18-expedition-engagement)* + +**Character lifecycle.** Generic role → named identity → signature crafts/feats → arc evolution → legacy. Unified across patrons, engineers, adventurers, specialists. *(17-foldins)* + +**Naming triggers.** Crit on signature craft / survival of high-tier expedition / milestone count / rare encounter / discovery moment / time-in-roster + activity. Trigger flavor shapes the identity. *(17-foldins)* + +**Procedural naming + signature items.** AI-batched at crystallization: name with backstory + signature variant of craft + flavor blurb for Library. *(17-foldins)* + +**Three patron origins.** Encountered (met in field), Groomed-from-roster (your master leaves and becomes a patron), Reputation-unlocked (notice you at a Guild Rank). All variations on one system. *(17-foldins)* + +**Titles (LotRO-style).** Each named character earns a pool of titles via deeds; player picks one to display. Whimsy + Serious pair per trigger ("The Harebrained" / "Keeper of Hares"). *(17-foldins)* + +**Lost characters become legacy.** On death/retire, `is_locked` flips: display freezes, item attributions become permanent. "It's never *not Dora's bear*." *(17-foldins)* + +**Item attribution permanence.** Items remember their maker as the maker *was* at craft time. Legacy items carry identity even after the maker dies. *(17-foldins)* + +--- + +## 6. Expeditions + +**Sealed-run principle.** Once an expedition launches, the player cannot reach into it. No mid-flight gear swap, courier, or resupply. Engagement lives in book-ends and the event stream. *(18-expedition-engagement)* + +**Three engagement surfaces.** Brief (pre-flight planning) / Stream (in-flight events) / Report (post-flight debrief). Each is a real verb, not a checkbox. *(18-expedition-engagement)* + +**The Brief.** Routing within zone, declared goal, risk dial, provisioning as commitment, party-comp synergies that read. Pre-flight is a puzzle. *(18-expedition-engagement)* + +**The Stream.** In-flight events as the only interactivity. Flavor pings ~70%, light decisions ~20%, capability-puzzle events ~5%, chain events ~3%, NPC encounters ~2%. *(18-expedition-engagement)* + +**The Report.** Triage sort, story compile, trait evolution moment, patron payoff. Debrief is a verb. *(18-expedition-engagement)* + +**Optional legs.** Expedition has discrete phases (Approach → Subzone A → optionally Subzone B → Return). Between legs the party radios in; player decides next leg. FTL-map shape inside one expedition. *(18-expedition-engagement)* + +**Player-controlled recall (Pattern C).** Adventurer lives in field generating events and loot until the player recalls them. Closest analog: Stardew daytime + CK3 events. *(17-foldins)* + +**Forcing functions for return.** Fatal injury, out of rations, captured, patron deadline pressure. *(17-foldins)* + +**5-tier risk model.** Tier 1 (Moo-Moo Meadows, time-only) → Tier 5 (Inverted Spire, party wipe, story consequences). Tier 1–2 frequent and chill; Tier 4–5 are *campaigns*. *(17-foldins)* + +**Telegraphed visible math.** Before sending: *"Dora vs. Ravenwood: 60% severe injury, 25% death."* Telegraphed deaths are story; surprise deaths are punishment. *(17-foldins)* + +**Death/loss mixed roll.** When things go wrong: permadeath, captured/ransomed, long-term wounded, or lost gear only. Permadeath stays on the table for severe mismatches. *(17-foldins)* + +**Auto-resolve via character traits.** If the player ignores an event, the party defaults to a trait-driven auto-choice. *The auto-choice IS the character.* *(17-foldins)* + +**Interactive event stream (CK3 layer).** Events surface as a queue (sidebar feed), not modal interrupts. Player works them at their own pace. *(17-foldins)* + +**Carry capacity.** Slots-with-weight-tiers. N normal slots; heavy items take 2 slots. Bag/saddlebag/cart capacity is a crafted-item axis. *(17-foldins)* + +**Consumables as expedition envelope.** Rations (duration), carry (haul), survival kits (zone access), combat consumables (encounters). Prepped party = 2–4× net multiplier vs. unprepped. *(17-foldins)* + +**Procedural event log.** No runtime LLM. Templated text snippets with slot fills, selected by zone + risk + composition + trait rolls. *(04-expeditions)* + +--- + +## 7. Latent Party Matrix + +**Four-axis latent model (MBTI-adjacent).** Engagement (Bold ↔ Withdrawn), Lens (Concrete ↔ Curious), Disposition (Pragmatic ↔ Sentimental), Tether (Disciplined ↔ Wandering). Never surfaced to player. *(18-expedition-engagement)* + +**Character latent vector.** 4-tuple computed from heritage + traits + class. Clamped [-1, +1] per axis. *(18-expedition-engagement)* + +**Party aggregation.** Per-axis mean. If members agree on sign → tilted; if they disagree → "conflicted on that axis" flag set. Conflicted axes are *spice*, not wash. *(18-expedition-engagement)* + +**Event weighting.** Each event has axis affinities (required = hard gate, preferred = soft weight, conflict-affinity = fires when axis is conflicted). Sampler weights toward party's vector. *(18-expedition-engagement)* + +**Folk-knowledge target.** Players notice a pairing's chemistry within 3–5 runs. Tilted axes produce >75/25 outcome bias. Signature finds are latent-gated. *(18-expedition-engagement)* + +**Token-budget party model.** Each party has shared budgets: Reach, Stamina, Carry, Insight, Standing. Build = budget shape. Small World–inspired. *(18-expedition-engagement)* + +**Builds as a real noun.** Emergent shapes players name: The Foothold, The Wedge, The Plunder Run, The Quiet Path, The Wraith Detail, The Mentor Run. System produces them; players christen them. *(18-expedition-engagement)* + +--- + +## 8. Auto-Quests & Content + +**Auto-quests with loot tables.** The expedition system reduces to a quest catalog with conditional triggers and weighted loot tables. Each quest = small state machine of nodes. Bounded, simulatable, AI-batchable. *(19-concepts-player-and-ui)* + +**Quest catalog target.** ~200–500 auto-quests for v1, ~5 nodes each, 2–3 branches per fork. Tagged with axis affinities, capability gates, zone+leg constraints. *(19-concepts-player-and-ui)* + +**Bark catalog target.** ~50–100 lines per named character, latent-vector-shaped, context-tagged (route start, encounter, decision-pending, ration-low, wounded). *(19-concepts-player-and-ui)* + +**Illustration target.** ~1000 quest-node images AI-batched. Plus character expression sets, zone backdrops. *(19-concepts-player-and-ui)* + +**Capability-puzzle events.** Some events gated on party composition. "Strong clears it; Lettered reads the inscription; Lucky finds the cache." Comp retroactively matters. *(18-expedition-engagement)* + +**Chain events.** Multi-stage events that span the run. Event 3 plants a clue; event 7 calls back; event 11 closes the thread. *(18-expedition-engagement)* + +**NPC encounters in the field.** Recurring named strangers across runs. Build relationships that pay off in future expeditions or patron emergence. *(18-expedition-engagement)* + +--- + +## 9. Crafting + +**Stations.** Forge, Alchemy Table, Loom, Enchanting Circle, Kitchen, Glassworks, Jeweler's Bench, Tannery, Carpenter's Shop. *(03-crafting)* + +**Station tiers I–V.** Upgrade with materials + a master Engineer. Higher tiers unlock more slots, higher-quality recipes, faster crafts. *(03-crafting)* + +**Drag-to-station mechanic.** Drag ingredients into station slots (3–6), hit craft. Multi-tier supply chains feed inputs from upstream crafts. *(03-crafting)* + +**Quality bands.** Crude → Common → Fine → Masterwork → Legendary. Output is a function of ingredient quality, station tier, engineer skill, traits, and luck. *(03-crafting)* + +**Critical success.** Promotes one band. Can be earned via lucky engineer rolls OR perfect Master's Touch timing. Same dopamine moment, different earning paths. *(03-crafting, 13-reveal-choreography)* + +**Three discovery paths.** Library research (Scholars convert time + reagents), Patron/expedition rewards (recipes drop as loot), Experimentation (drag off-recipe and see what happens). *(03-crafting)* + +**Recipe catalog.** ~500–1000 catalog entries shipped. Players don't know all; experimentation reveals which combos map to which entries. *(03-crafting)* + +**Master's Touch.** Brief opt-in skill-timing per craft. Two meters (Quality, Critical) sequential — tap to lock in the green zone. Difficulty scales with recipe baseline, target quality, engineer skill. Ignorable; no penalty. *(16-engagement-layers)* + +**Themed Master's Touch skinning.** Universal input mechanic, station-specific visual (hammer-strike rhythm at the Forge, stir-and-pour at Alchemy, shuttle-pass at Loom, etc.). *(16-engagement-layers)* + +**Trait integration in Master's Touch.** Lucky widens green zones; Steady slows meters; Hasty narrows zones; Drunk wobbles erratically. Traits become *felt* during play. *(16-engagement-layers)* + +**Juice (engagement Layer 1).** Drag-snap, particles, audio per placement, idle station animation that intensifies on hover, ambient SFX layer during craft. The bubble-wrap layer. *(16-engagement-layers)* + +**Adjacent-station synergy (engagement Layer 3).** Shared-warmth (parallel crafts sharing ingredient type), chained refining, engineer cross-assist, discipline pair. Thoughtful parallel-craft scheduling pays off. *(16-engagement-layers)* + +**Veteran auto-craft.** Toggle to skip Master's Touch meters by default for queued bulk crafts. The mini-game is for items that matter, not sale queues. *(16-engagement-layers)* + +--- + +## 10. Materials + +**Categories.** Raw / Refined / Components / Consumables & Catalysts / Trophies & Curiosities. *(14-materials)* + +**Supply chain depth.** Raw → Refined → Component → Final Item (3-step pipeline). Some items skip a step; legendaries add sub-sub-assemblies. *(14-materials)* + +**Quality at every stage.** Every tier supports the same five quality bands. Crude Iron Ingot stacks separately from Fine Iron Ingot. *(14-materials)* + +**Material sources.** Expedition drops (primary), patron rewards, scholar research, beast taming, future bazaar. *(14-materials)* + +**v1 envelope.** ~30 raw, ~25 refined, ~20 components for a playable starting set. *(14-materials)* + +**Material provenance.** Same material name behaves differently by source. *Burned Hills moonsilver smelts hotter than Mire moonsilver.* Set on drop. *(18-expedition-engagement)* + +**Material state.** Fresh / aged / cured / cursed-by-storage. Time-evolves. Some materials improve with age; some decay. *(18-expedition-engagement)* + +**Material property discovery.** Properties surface through use, not on first drop. *"You notice moonpetal strengthens in moonlit recipes."* Library populates. Resource collection becomes investigation. *(18-expedition-engagement)* + +**Axis-tagged drop tables.** Drop tables are tagged with axis affinities; sampler weights drops by party shape. Same zone, different haul shape depending on who you sent. *(18-expedition-engagement)* + +**Material as expression of party choice.** Whimsical parties bring back whimsy-tagged materials → whimsy recipes → whimsy items. Tonal character of a save emerges from pairings. *(18-expedition-engagement)* + +--- + +## 11. Economy & Patrons + +**NPC merchants.** Always-on, instant sell, base prices. Merchants in your roster boost prices and unlock distant markets. *(05-economy-progression)* + +**Patron orders.** Specific finished items requested by named NPCs. Quality requirements, sometimes time-limited. Premium rewards: gold, reputation, recipes, relics. *(05-economy-progression)* + +**Patrons with personality.** Named NPCs with factions and grudges. Filling one's order may anger another faction. Patron tier raises with Guild Rank. *(05-economy-progression)* + +**Patron board.** Main "directed objectives" surface. Players who want a quest will look here. *(05-economy-progression)* + +**Future bazaar.** Player-to-player auction house — architecturally stubbed, not v1. Stable IDs, event-sourced state, signed saves. *(05-economy-progression)* + +--- + +## 12. Progression + +**Guild Rank.** Meta-progression spine. Earned from completed orders, discoveries, masterworks, expeditions, achievements. Unlocks roster size, hire-pool quality, station tier cap, region access, patron tier, workshop slots. *(05-economy-progression)* + +**Multiple visible progression surfaces.** Guild Rank, Recipe Library (% discovered), Material Catalog (Found), Patron Favor (per patron), Engineer Career Arc (Apprentice → Master), Quality Records (best per recipe), Region Map (% explored). Session opening shows multiple "almost there" hooks. *(17-foldins)* + +**Capability stack.** A craft attempt's success = sum of engineer career stage + traits + station tier + tools + materials + target quality band. Effective capability vs. recipe demand → outcome. *(17-foldins)* + +**Attempt risk gradient.** Mild over-capability = result drops one band. Moderate = chance of total failure. Severe = engineer fatigue/injury, occasional cursed outcomes. Long-shot = small chance of against-the-odds Masterwork. *(17-foldins)* + +**Tier transitions as celebration scenes.** Backdrop swap, banner unfurl, narrator beat, new anchors filling in. Not a stat popup — a moment. *(20-north-star)* + +**Visible-but-locked aspirations.** Drip-fed at the edges of the player's reach. Patrons whose orders you can't yet fulfill (tier-gate visible). Zones greyed on the map. Station-tier silhouettes. Heritages you've heard about but haven't seen. *(20-north-star)* + +**The Lamborghini.** The legendary-tier visual peak. Animated holo + ornate paperdoll + bespoke art + named-and-titled cast. Fully revealed only on arrival. *(20-north-star)* + +**Endgame questline.** Legend tier (50+ hours) is the equivalent of MMO raid content. Bounded epic questline with prestige rewards. Content volume can be modest; what matters is that it *exists* and is *worthy*. *(20-north-star)* + +**Cosmetic-only customization stays earned.** Visual style is achieved, not picked. No free-form transmog. Title choice and gear-within-tier are fine; tier-aesthetic itself is climbed to. *(20-north-star)* + +--- + +## 13. UI & Navigation + +**Context-switched screens.** Each screen is a complete composition (hall, workshop, world map, expedition view, library). No always-on persistent HUD; UI belongs to the screens it serves. *(19-concepts-player-and-ui)* + +**Guild Hall (home screen).** First-person view of the great room. Scene-as-navigation — tap zones (forge corner, alchemy nook, roster wall, patron board, library doorway, strongroom, front door) to enter subviews. *(08-ux-ui)* + +**World Map.** Parchment-style fantasy map. Top-down — the one perspective exception. Regions are illustrated nodes; tap to zoom to zones. *(08-ux-ui)* + +**Persistent bottom tab bar.** Always-available shortcuts (Hall · Roster · Workshops · Map · Patrons · Library). Speed; scene navigation is atmosphere. *(08-ux-ui)* + +**Inventory tiers.** Stackable raw (list rows), Stackable refined (rows by quality), Unique instances (full cards). If two items are interchangeable, they stack; if they have identity, they get a card. *(08-ux-ui)* + +**The Vault.** Three tabs: Equipment (uniform grid of card thumbnails), Stockpile (list rows + filters), Special (recipes, relics, tokens, trophies). *(08-ux-ui)* + +**Card view modes.** Compact grid (small thumbnails, fast scroll) vs. Showcase view (full card, lingering). *(08-ux-ui)* + +**Wall of Masterworks.** A Library room displaying the player's best-ever crafts as a permanent wall. Pure cosmetic, deeply motivating. *(08-ux-ui)* + +**"Alive hall" minion overlays.** Minions render at named backdrop anchor points; subtle work-loop animations. Empty anchor when minion isn't assigned. The hall populates as the guild grows. *(08-ux-ui)* + +**Notification surface.** Glowing badges on scene elements signal ripe things (completed craft → workshop, returned expedition → front door, new applicant → recruiting desk, patron deadline → board, rank-up → altar). *(08-ux-ui)* + +**Eye-of-the-Beholder portrait bar.** Persistent UI element *within the expedition view*. 4–6 framed portraits, status overlays, expression shifts, speech banners. *(19-concepts-player-and-ui)* + +**Journey graph (Oregon Trail × FTL).** Expedition view's central artifact. Branching node graph; party-marker advances stepwise. Branches visible — decisions are geographically committing. *(19-concepts-player-and-ui)* + +**Not a card game.** Cards-the-genre signifier is overloaded. Game uses illustrated artifacts (portraits, journal pages, dispatches, item cards in inventory) but never "cards in hand" or "decks." *(19-concepts-player-and-ui)* + +**Mixed-resolution UI vocabulary.** Pixel art world + HD vector chrome (UI frames, buttons, dialogs, tooltips). Shaders on pixel art respect the pixel grid when visible. *(09-art-style)* + +**UI chrome aesthetic.** Burnished brass with riveted iron — something a craftsman would actually make. Substantial, weighty. Serif text with weight. *(10-tone)* + +--- + +## 14. Art Style + +**Late-90s pixel art era.** Diablo II / Infinity Engine / Fallout 1-2. Detailed, atmospheric, painterly — not iconic-pixel. *(09-art-style)* + +**640×360 native canvas.** Pixel-native. Cards integer-scaled from ~256×384. Backdrops at 640×360 or fractional multiples. *(09-art-style)* + +**256-color palette.** Kmeans-derived from a library of diffusion-model art. Calibrated and locked. *(09-art-style)* + +**Floyd-Steinberg dither pipeline.** Diffusion-model generation → downsample → Floyd-Steinberg dither against the locked palette. The dither pass is what erases the "AI look." *(09-art-style)* + +**Asset production pipeline.** Generate at high-res → downsample → dither → optional hand-clean → commit. It's a script. *(09-art-style)* + +**First-person POV discipline.** Backdrops are from the guildmaster's vantage. Workshops, hall, library, patron court, regions — all first-person. World Map is the parchment exception. *(08-ux-ui, 09-art-style)* + +**Per-category silhouette scale.** Tiny (rings, gems) ~50%, small (daggers) ~70%, standard (swords) ~90%, large (polearms) rotated diagonally to fit. Card canvas is fixed. *(09-art-style)* + +**Anchor-point depth scale.** Backdrops define named anchors with depth-scale values (1.0 close, 0.5–0.7 deep). Sprites render at anchor depth automatically — no giant-figure-at-back-of-room moments. *(09-art-style)* + +**4 fps animation.** Era-correct for late-90s reference. Validated by the user's production pipeline. *(09-art-style)* + +**Atmospheric foreground animation.** Drifting smoke, bubbling liquid, embers, rain, fog. Looping particle layers + shader effects on top of static backdrops. *(08-ux-ui)* + +--- + +## 15. Item Cards (Composition) + +**Layered sprite composition.** Items composed at runtime from layers: frame → background → base silhouette → material tint → component overlays → effect aura → quality flourish → maker's mark. *(07-item-cards)* + +**Anchor points for components.** Base sprites define pommel/blade/stopper/etc. anchors; components are authored to land on them. The gem inhabits the pommel rather than floating beside it. *(07-item-cards)* + +**Combinatorial asset count.** ~30 silhouettes × ~20 material tints × ~30 component overlays × ~15 effect auras × 5 frames = variety from a small authored library. *(07-item-cards)* + +**Visible crafting choices.** Every craft decision has visible consequence — the strongest feedback loop possible. Two players who craft the same recipe with different components see visibly different items. *(07-item-cards)* + +**Composed procgen names.** `[quality adjective] [material] [base] of [effect noun]` gives Diablo-style names from the layer stack itself. *(07-item-cards)* + +**Effect shaders (zero-asset effects).** Outer glow, holo foil, foil shimmer, heat haze, frost crackle, cursed corruption, holy radiance, first-reveal sweep, faded/locked. Implemented as shaders, not PNGs. *(07-item-cards)* + +**Quality bands shader-driven.** Crude/Common = no shader. Fine = subtle outer glow. Masterwork = animated foil + drifting particles. Legendary = holographic + animated frame glow + bespoke art. *(07-item-cards)* + +**Bespoke Legendary art.** When the player discovers a truly unique recipe, that one gets full hand-finished treatment. Composition for 99%, bespoke for 1%. *(07-item-cards)* + +**Pass model.** Pass 1: layer composite. Pass 2: post-process shader stack. Pass 3: UI compositing. *(07-item-cards)* + +**Composition data model.** Every item instance stores a recipe `{base, materials, components, effects, quality, maker}`, not a baked image. Save data is tiny; renderer reconstructs on demand. *(07-item-cards)* + +--- + +## 16. Reveal Choreography + +**Length scales with magnitude.** Buildup is the signal, not manufactured suspense. Players learn the visual/audio language quickly. *(13-reveal-choreography)* + +**Anti-slot-machine.** Common items get quick honest reveals — the reveal *is* the result, not a teaser. No fake-outs. *(13-reveal-choreography)* + +**Five band tiers.** Crude (~0.5s soft thump) → Common (~0.8s crunch) → Fine (~1.5s ring) → Masterwork (~2.5s clang + choir) → Legendary (~4–5s rumble + slow-mo + crack-of-light). *(13-reveal-choreography)* + +**Critical success break.** Choreography starts at expected band, then mid-flip upgrades. "Wait — no" beat. Player thought Common, got Fine. Best feeling in the game after Legendary itself. *(13-reveal-choreography)* + +**New Discovery overlay.** Stacks on top of quality reveal — parchment whoosh + book shut sound + ribbon. Runs concurrent on a separate channel. *(13-reveal-choreography)* + +**Time-slow reserved for Legendary.** Rarest cue for the rarest moment. Don't dilute. *(13-reveal-choreography)* + +**Skippable after first.** Long-press skips after ~0.5s. First-of-tier never skippable; subsequent skippable. Veteran time matters. *(13-reveal-choreography)* + +**Reveal framework extends.** Same toolkit, different presets for expedition haul / new applicant / patron payment / rank up. *(13-reveal-choreography)* + +--- + +## 17. Voice & Character Expression + +**Character voice as personality channel.** The latent matrix expresses through *how each character speaks*. Bark library + journal voice + decision phrasing all flow from the character's profile. Players develop favorites by mouthfeel. *(19-concepts-player-and-ui)* + +**Mixed addressing dynamic.** Characters chatter among themselves, narrate their own observations, occasionally address the player during decisions. Loose, not rigid. *(19-concepts-player-and-ui)* + +**Chronicler is a party role.** A character with the right traits (Scholar, Lettered, Cartographer) chronicles the run. No chronicler = sparse, garbled updates. Knowledge is a capability gate. *(19-concepts-player-and-ui)* + +**Writing voice (middle register).** Atmospheric, occasionally dry, never quippy. Not juvenile, not edgy, not purple. *"Stuff happened, here's what happened, here's what it cost."* *(10-tone)* + +--- + +## 18. Tone & Setting + +**Confident fantasy stylization with muted weight.** Substantial enough for adults, accessible enough for anyone. Never juvenile or edgy. *(10-tone)* + +**Tone triangulation.** WoW (stylized exaggeration, weighty silhouettes) × Quake (muted earthen palette, weathered materials) × Machinarium (atmospheric environmental storytelling). *(10-tone)* + +**Tonal anchor: darker WoW × Shrek.** Confident fantasy with whimsy as texture. *"We know this is silly, and also this matters."* *(17-foldins)* + +**Muted palette weighting.** Poison = olive (not neon-green). Fire = ember-amber (not arcade orange). Holy = dusty gold (not pure white). Curse = bruised wine. Cold = foggy slate-blue. Arcane = faded lapis. *(10-tone)* + +**Tools of voice.** Play on words (Lumbass Bread, Plaguebringer's potpourri). Pop-culture jabs in moderation. Anachronisms welcome (rhinestones, propeller hats, teddy bears, the absurd-weight onyx). Earnest emotional beats when they come. *(17-foldins)* + +**Don't get carried away.** World is mostly serious; whimsy is texture on top. If everything's a joke, nothing lands. If the joke surface is too thin, whimsy becomes a tic. *(17-foldins)* + +**Optimization creates absurd outcomes — lean in.** Crafted gear identity overrides character aesthetic. Necromancer in propeller hat because it's BiS. No transmog. Comedy emerges from the system, not from authored jokes. *(17-foldins)* + +**Generic medieval fantasy setting.** Swords, dungeons, cauldrons, hooded figures. Lean on the player's existing fantasy vocabulary; no original world-building. *(11-setting)* + +**Three flavor pockets.** Mainline (standard medieval). Gnomish steampunk (brass, gears, clockwork). Dark elf necromancy (obsidian, bone, shadow). Variety without lore burden. *(11-setting)* + +**Naming conventions.** Human → Latin/Germanic/Celtic (Theodric, Mira). Dwarven → Norse-hard (Brokk, Durin). Elven → Latin-flowing (Aelandir, Sylvana). Dark elven → sibilant (Vae'shar). Gnomish → alliterative-quirky (Tinkin Tappet, Glia Greaseworth). *(11-setting)* + +**Texture in one sentence.** *"Grobb Plaguebringer just returned from the depths of Ravenwood Crypt with essence of nightshade to put the final touches on his spring potpourri mastercrafted skill-up."* If we ship 200 sentences with this texture, we have a game. *(17-foldins)* + +--- + +## 19. Audio + +**Kelethin-style mellow fantasy ambient.** Slow, modal, woodwind-forward with string accompaniment. Long compositions, breathing room. References: Everquest, Diablo II Tristram, Machinarium, Bastion. *(15-audio)* + +**MIDI generation pipeline.** AI-generated MIDI → curate → MuseScore cleanup → soundfont render via FluidSynth → OGG export. Tiny working files, procedurally controllable. *(15-audio)* + +**Anti-repetition strategies.** Long compositions (3+ min loops). Multiple variants per location, crossfaded randomly. Time-of-day mixes. Silence is allowed. Same key signature across related themes. *(15-audio)* + +**SFX from sample packs + layering.** Sonniss GDC bundles as foundation. Layer simple sounds for complexity. Pitch/tempo shift for variants. *(15-audio)* + +**Anti-Wilhelm discipline.** Frequently-played UI sounds have 4–6 variants in rotation, never repeat consecutively. *(15-audio)* + +**Reveal audio signature per band.** Crude soft thump → Common hammer crunch → Fine hammer + chime → Masterwork hum→rising chime→clang→choir → Legendary rumble→swell→crack→organ. *(13-reveal-choreography, 15-audio)* + +**Accessibility audio.** Independent volume sliders per bus (Music/Ambient/SFX/UI). "Reduce ambient loops" setting. Music-off mode. Visual feedback for all important audio cues. *(15-audio)* + +--- + +## 20. Onboarding + +**Five beats in 5 minutes.** Drop-in → Returning expedition → Patron board → First crafts → Equip and send → Release. *(12-onboarding)* + +**Caewin the Steady.** Starter minion, authored character. Stays a real minion after the tutorial. *(12-onboarding)* + +**Skip the wait.** Pre-completed first expedition so the player doesn't hit a 30-min timer in beat 1. *(12-onboarding)* + +**Forced critical success.** Designed wow-moment on the player's first Lantern craft. Two slow wide-green meters; both lock; Masterwork ribbon; particles; the hook is set. *(12-onboarding)* + +**Hidden tutorial crit.** Result panel shows plausible math (*"Caewin's steady hand + Lucky trait + perfect timing"*). Player attributes the win to themselves. Never told it's tutorial-rigged. *(12-onboarding)* + +**Soft, not modal.** Badges glow in priority order. Contextual one-liners on first-open of each screen. Player can tap around freely. *(12-onboarding)* + +**Authored, not procgen.** Caewin, the foreman, the starter haul, the recipes — hand-tuned. Procgen kicks in for the *next* of everything. *(12-onboarding)* + +**No second tutorial.** Contextual one-line hints only after the door closes. Treat the player as an adult. *(12-onboarding)* + +**First tier transition.** Apprentice → Journeyman is the tutorial graduation. First independent expedition concludes in a promotion ceremony — backdrop shift, banner, named acknowledgement. *(20-north-star)* + +--- + +## 21. AI & Data Pipeline + +**TOML + Pydantic data sources.** Source format is TOML per domain (`data/materials/`, `data/recipes/`, `data/patrons/`). Git-versioned, text-editable. Validation at the tooling layer. *(17-foldins)* + +**CSV bulk-import escape hatch.** For AI-generated or spreadsheet-brainstormed batches; converted to TOML once imported. *(17-foldins)* + +**Procedural expansion.** Templates × materials × quality bands × affixes → 10k+ permutations. *(17-foldins)* + +**SQLite runtime artifact.** Same engine for content and save state. *(17-foldins)* + +**Python sim first.** Sim + recipe scope locked first; *then* game code. Lock the 30–60 hour content envelope by simulation before touching the runtime. *(17-foldins)* + +**Sim-tractable expedition shape.** Quest state machine + decision routing + loot rolling + character state evolution. Monte Carlo 10k runs per zone-tier per party policy to measure content variety, loot balance, outcome gaps. *(19-concepts-player-and-ui)* + +**AI authoring loop for events.** Prompt = "30 events for biome X targeting party reading [latent vector]." Output tagged with axis affinities. Sampler weights at runtime. Per-axis authoring, not per-pair. *(18-expedition-engagement)* + +**AI authoring loop for voice.** Prompt = "bark library for character [latent + heritage + traits + contexts]." Output is coherent voice corpus. Generated at crystallization. *(19-concepts-player-and-ui)* + +**Signature event gating.** Rare character-naming events are latent-gated. *Found the 90lb onyx* only fires for high-Curious + Wandering parties. Player gets *their* characters' stories. *(18-expedition-engagement)* + +**Asset pipeline (user-owned).** ComfyUI + Python scripts. Out of scope for design tooling discussions. *(17-foldins, user-feedback memory)* + +--- + +## 22. Open Threads & Parking Lot + +**Replayability shape.** Steam expects 8–30 hr. NG+ with kept signature heirlooms? Open sandbox post-arc? Both? Single-arc-and-done? *(17-foldins, 99-open-questions)* + +**Per-discipline capability vs. single engineer rank.** Master Smith AND Common Loom-worker, or one rank-per-engineer? UI/state complexity vs. breadth pillar. *(17-foldins)* + +**Per-recipe memory.** Does the guild remember masterworking a specific recipe? Diminishing returns on familiar recipes vs. fresh thrill of new? *(17-foldins)* + +**Multiple expeditions in parallel.** Tabs? One screen with multiple journey-graphs? Strict serial (one at a time as v1 simplification)? *(19-concepts-player-and-ui)* + +**Pacing of marker advancement on the journey graph.** Real-time tick? Player-step? Hybrid auto-step that pauses on decisions? *(19-concepts-player-and-ui)* + +**Axis selection prototyping.** Latent matrix axes (Engagement/Lens/Disposition/Tether) are load-bearing. Prototype with placeholders, verify events slot in naturally before locking. *(18-expedition-engagement)* + +**Combination math weighting.** Per-axis mean + conflicted flag is the working sketch. May need weighting by trait strength. Sim-tuneable. *(18-expedition-engagement)* + +**Folk-knowledge surfacing aids.** Library notes patterns observed, never underlying axes. Music stings, narrator-tone shifts, journal voice as latent cues — explicit or invisible? *(18-expedition-engagement)* + +**Stable-pairing pull.** Folk knowledge requires repeated pairings. Bond-via-shared-runs is the natural lever; may need other nudges. *(18-expedition-engagement)* + +**Material property authoring.** How many distinct properties per category? Procedural vs. hand-authored? *(18-expedition-engagement)* + +**Patron interaction shape.** Patrons appear everywhere as motivation but their *interaction model* isn't designed. Do they have voice? Are they latent-matrix tagged too? *(handoff-from-brainstorm)* + +**Economy friction.** Loop is designed; scarcity model isn't. What prevents trivial repetition once the player has a working forge and a tier-2 party? *(handoff-from-brainstorm)* + +**08-ux-ui language revision.** Reframe "guildmaster you" / "your space" → "the observer" / "the guild" to match the omnipresent-observer identity. *(19-concepts-player-and-ui)* + +**Push notification opt-in.** When asked? Granularity? *(99-open-questions, 08-ux-ui)* + +**Quality cascade rules.** Can a great engineer rescue a Crude component, or does quality fully cascade from components? *(03-crafting, 99-open-questions)* + +**Experimentation penalty.** How aggressive — wasting rare ingredients should sting but not feel cruel. *(03-crafting)* + +**Recipe book surfacing.** How without becoming a spreadsheet? By-station view, by-discipline view, "in progress" filter? *(03-crafting)* + +**Scrap/salvage mechanic.** Break finished cards for partial refund? *(99-open-questions, 14-materials)* + +**Special material properties beyond quality.** Is moonpetal *fundamentally* magical regardless of band, or is everything type+quality? *(14-materials)* + +**Pocket gating.** Are gnomish/necromantic materials zone-locked or do they crosscontaminate? *(14-materials)* + +**Color-clash policy.** Lapis blue + ruby red on one sword can look muddy. Gameplay-prevent dissonant combos, or embrace as feedback? *(07-item-cards, 99-open-questions)* + +**Inventory grid model.** Uniform 1-cell cards vs. Diablo-style multi-cell? *(99-open-questions)* + +**Onboarding skip threshold.** Beat 1 feels right, but worth testing. *(12-onboarding)* + +**Time-of-day cycling for hall backdrop.** Real time, game time, or fixed sequence? *(08-ux-ui, 99-open-questions)* + +**Diegesis discipline for in-flight journal/graph.** Does the journey graph exist *in fiction* or is it pure UI metaphor? *(19-concepts-player-and-ui)* + +--- + +## Notes on the glossary + +Each section is roughly topic-coherent but cross-references are common — concepts overlap. Source links point to the canonical doc but most concepts touch multiple docs. Sorting / prioritizing into must-have / nice-to-have / parking-lot is the next session's work. + +Status of the doc set after this glossary: +- 00–16 are the original topic docs (verbose, but the substantive design substrate) +- 17–18 are session fold-ins that significantly extend 04/05 and add new structural pieces +- 19 introduced the glossary blurb format +- 20 pinned the north star +- This file is the unified index — concept-first rather than doc-first diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..21b7f98 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,24 @@ +# Brainstorming Docs + +Loose notes on a mobile crafting game. Early phase — these are working ideas, not decisions. Refine freely. + +- [00-concept.md](00-concept.md) — pitch, design pillars, references +- [01-core-loop.md](01-core-loop.md) — the gather→craft→equip→hire engine +- [02-roster.md](02-roster.md) — minions, classes, traits, paper-doll portraits, relationships +- [03-crafting.md](03-crafting.md) — stations, multi-tier supply chains, quality bands, discovery +- [04-expeditions.md](04-expeditions.md) — AFK timer-resolved, procedural events +- [05-economy-progression.md](05-economy-progression.md) — market, patrons, Guild Rank, dopamine sources +- [06-asset-pipeline.md](06-asset-pipeline.md) — AI in production, pre-rendered runtime, bundle strategy +- [07-item-cards.md](07-item-cards.md) — layered sprite composition, item cards, visible crafting choices +- [08-ux-ui.md](08-ux-ui.md) — inventory tiers, scene-based navigation, backdrops, notification surface +- [09-art-style.md](09-art-style.md) — pixel art, Floyd-Steinberg dithering, palette-as-art-direction, pixel/HD coherence rules +- [10-tone.md](10-tone.md) — confident fantasy stylization with muted weight (WoW × Quake × Machinarium), writing voice, audio direction +- [11-setting.md](11-setting.md) — generic medieval fantasy with gnomish-steampunk and dark-elf-necromancy flavor pockets +- [12-onboarding.md](12-onboarding.md) — five-beat first-five-minutes walkthrough, forced-crit hook, soft-not-modal tutorial discipline +- [13-reveal-choreography.md](13-reveal-choreography.md) — card-flip choreography per quality band, length-scales-with-magnitude principle, critical/discovery special cases +- [14-materials.md](14-materials.md) — materials taxonomy (raw / refined / components / consumables / trophies), supply chain depth, quality at every stage +- [15-audio.md](15-audio.md) — Kelethin-style mellow ambient direction, MIDI-source pipeline, sample-pack SFX strategy, mobile audio engineering +- [16-engagement-layers.md](16-engagement-layers.md) — three layers of crafting feel: juice, Master's Touch (Sherlock-style two-meter), adjacent-station synergy +- [17-foldins-2026-05-12.md](17-foldins-2026-05-12.md) — session fold-ins: Steam-first, session pacing, capability/risk model, interactive expeditions, consumables-as-economy-driver, named-character emergence + LotRO-style titles +- [99-open-questions.md](99-open-questions.md) — parking lot +- [samples/](samples/) — reference assets demonstrating the production pipeline