diff --git a/docs/reference/TRANSFERABLE_STRUCTURE_LESSONS.md b/docs/reference/TRANSFERABLE_STRUCTURE_LESSONS.md index 82ff405e..126a0b29 100644 --- a/docs/reference/TRANSFERABLE_STRUCTURE_LESSONS.md +++ b/docs/reference/TRANSFERABLE_STRUCTURE_LESSONS.md @@ -10,7 +10,8 @@ visual composition, art, animation, music, sound effects or source code. Reference counts remain evidence about a captured build, not targets for this project. Aetherbound Guild's scope comes exclusively from the [frozen product -contract][PRODUCT], while factual support comes from the [runtime census][CENSUS]. +specification][PRODUCT] and [current game contract][GAME], while factual support +comes from the [runtime census][CENSUS]. ## Evidence-To-Lesson Trace @@ -20,7 +21,7 @@ contract][PRODUCT], while factual support comes from the [runtime census][CENSUS | C-08 and C-09 | Enemy readability benefits from role-level telegraphing before commitment | Copying enemy identities, silhouettes, attacks or encounter compositions | | C-10 through C-13 | Equipment and milestone rewards can change party behavior and contingency planning | Copying item or artifact identities, effects, rarity rules, prices or tooltip prose | | C-14 and C-15 | Party order is a meaningful preparation decision | Copying a formation layout, slot count or exact battlefield mapping | -| C-16 through C-19 | Environment production and run progression need separate accounting | Treating asset families, victories, chapters and waves as interchangeable units | +| C-16 through C-19 | Environment production and run progression need separate accounting | Treating asset families, victories, progress markers and waves as interchangeable units | | C-20 through C-23 | Collection, achievement and mode scope must be authored explicitly because the reference totals are unknown | Filling gaps with guesses from menu labels, scripts or assets | | A-01 through A-08 | Layered presentation has a large and multi-category production footprint | Treating files, frames, types or component instances as gameplay content | @@ -28,47 +29,50 @@ contract][PRODUCT], while factual support comes from the [runtime census][CENSUS Aetherbound Guild should use the following independently authored loop: -`guild forecast -> roster and job plan -> equipment and formation -> route commitment -> readable auto-battle with bounded intervention -> causal result -> recovery or reward -> guild progression` +`contract forecast -> provisional Recruit selection or Market planning -> equip and order the Party line -> battle-offer commitment -> readable automatic battle -> causal result -> recovery or reward -> next Market or Guild progression` The transferable lesson is the separation of player questions, not the reference screen sequence: | Boundary | Player question | Required state change | Required handoff | |---|---|---|---| -| Guild forecast | What pressure is approaching, and what can I prepare for? | Threat and opportunity information becomes actionable | Opens roster, job, equipment and route planning without hiding constraints | -| Roster and job plan | Which people and capabilities form the expedition thesis? | Recruits receive explicit jobs and responsibilities | Formation and equipment previews expose consequences | -| Equipment and formation | What behavior, timing and position will each choice change? | Loadout and order create a testable battle plan | Route commitment summarizes the plan's known strengths and risks | -| Route commitment | Which uncertainty is worth accepting now? | Resources and risk are committed | Battle starts from a reviewable snapshot | -| Battle | Is the prepared plan working, and why? | The simulation resolves with sparse, legible intervention windows | Result view preserves the causal record | -| Result | What succeeded, where did the first failure begin, and what changed? | Rewards, injuries, losses and discoveries are explained | Recovery and progression actions are offered in context | -| Recovery or reward | How should the guild adapt rather than merely restore numbers? | The next plan gains a new option, constraint or tradeoff | Returns to forecast with a meaningfully changed decision space | +| Contract forecast | What pressure is approaching, and what can I prepare for? | Enemy families, boss rules, difficulty and reward breadth become actionable | Opens provisional Recruit selection or the stable Market without hiding constraints | +| Recruit and Market plan | Which generated offers add the needed capability under current Coin, capacity and recovery pressure? | Selection or hire commits a generated Recruit with a fixed Profession, one Trait and visible tradeoffs | Equipment and Party-line previews expose consequences | +| Equipment and Party line | What behavior, timing and order will each choice change? | Loadout and front-to-rear order create a testable battle plan | Battle-offer commitment summarizes known strengths, risks and failure exposure | +| Battle-offer commitment | Which disclosed risk is worth accepting now? | One seeded offer and its resources are committed | Battle starts from a reviewable snapshot | +| Battle | Is the prepared plan working, and why? | The deterministic simulation resolves without manual skill activation or in-battle reordering | Result view preserves the causal record | +| Result | What succeeded, where did the first failure begin, and what changed? | Rewards, Fallen Recruits, returned equipment and discoveries are explained | Recovery and progression actions are offered in context | +| Recovery or reward | How should the Company adapt rather than merely restore numbers? | The next plan gains a new option, constraint or tradeoff | Returns to the next Market or Guild with a meaningfully changed decision space | This loop preserves anticipation, observation and diagnosis while giving the -original game its own guild-management framing, route logic and intervention -rules. +original game its own Company-management framing, Market economy and fully +automatic battle rules. ## Decision Timing ### Opening -The first interactive state should ask for a real build commitment using a -small, understandable option set. Onboarding may stage information, but it -should not make the opening plan on the player's behalf. The choice must expose -what changes in role, resource pressure or formation behavior. +The first interactive state should ask the player to select two of four +provisional generated Recruits before Run creation. Selection remains revisable +until commit, and the comparison must expose Profession responsibility, Trait +benefit and cost, rolled attributes, and Party-line implications. Onboarding +may stage information, but it must not make the opening plan for the player. ### Before Battle -Route, equipment, job and formation choices should converge in a plan review. -The review must show projected responsibilities and known threats without -pretending to predict the exact simulation. Reversible edits stay reversible -until commitment; destructive or costly changes require explicit confirmation. +Market, equipment, Profession, Party-line and battle-offer choices should +converge in a plan review. The review must show projected responsibilities, +known threats and exact failure exposure without pretending to predict every +simulation event. Reversible edits stay reversible until commitment; +destructive or costly changes require explicit confirmation. ### During Battle -Automatic execution is valuable only when cause remains inspectable. Each -bounded intervention should answer a distinct tactical question and preserve -the value of preparation. Slow playback, pause where platform rules allow, and -event inspection are diagnostic controls; they are not separate game modes. +Automatic execution is valuable only when cause remains inspectable. Battle +provides start, pause, speed, inspect and retreat controls, but no repeated +manual skill activation and no in-battle equipment or Party-line editing. +Playback and event inspection are diagnostic controls; presentation speed must +not change the deterministic result. ### After Battle @@ -79,35 +83,36 @@ the next choice responds to what the player just learned. ### After Failure -Recovery must create a new viable plan without erasing consequence. Replacement -availability, injury handling, debt, route retreat and guild support should be -authored as economy rules. A platform-funded revival cannot be the balancing -assumption. +Recovery must create a new viable plan without erasing consequence. Fallen +Recruits remain removed for the Run, their equipment returns, death creates +Replacement Credit, and the next Market protects an affordable base-Profession +offer under the current product rules. Recovery must remain an authored economy +contract; platform-funded revival cannot be its balancing assumption. ### Persistent Progression -Persistent rewards should open new planning grammar: information, formation -options, profession transformations, route tools, recovery policies or -resource conversions. Flat universal bonuses may support progression, but -cannot carry it alone because they do not create a new decision. +Persistent rewards should open breadth: information, Profession sidegrades, +previews, challenges, catalog access and optional rule changes. They must not +grant permanent universal damage, health, Coin income or starting-capacity +advantages that replace Run decisions. ## Content Grammar -Every content row should declare its player-facing job before art production. +Every content row should declare its player-facing function before art production. The following schemas are original planning requirements, not reconstructions of reference data. | Content family | Required differentiators | Filler rejection test | |---|---|---| -| Recruit | Personal constraint, decision preference, formation responsibility, profession affinities, recovery consequence and relationship hook | Reject when swapping the name and portrait leaves every decision unchanged | +| Generated Recruit | Generated identity seed, modular appearance, fixed Profession, equal-budget rolled attribute distribution, exactly one Trait, equipment, level, price and offer provenance, survival history and recovery consequence | Reject any rule that treats a name or appearance combination as another gameplay identity or requires authored personal or social content | | Base profession | Battlefield responsibility, resource verb, preferred position, readable cadence, failure mode and counterplay | Reject when it is only a stat package or element label | -| Advanced profession | A transformation of targeting, timing, position, resource flow or risk ownership | Reject when it is only a stronger version of the base profession | -| Enemy identity | Pre-commitment signal, threat rule, target pressure, counter, ally interaction, escalation state and result explanation | Reject when color or health is the only meaningful difference | -| Equipment or item | Eligible users, changed verb, trigger, tradeoff, positioning consequence, comparison rule and visible feedback | Reject when only a scalar value or rarity changes | -| Milestone relic | Build-level contingency, route-valuation change, conflict with other plans and a visible trigger | Reject when it is merely a larger generic bonus | -| Chapter | New route pressure, enemy grammar, economy stress, environmental rule, recovery question, boss synthesis and lasting guild consequence | Reject when it is only a visual reskin with larger numbers | -| Achievement | Explicit behavior worth recognizing, progress visibility, completion condition and non-distorting reward | Reject when it rewards passive repetition without teaching or celebrating mastery | -| Collection entry | Discoverability rule, readable unknown state, provenance, completion semantics and accessibility text | Reject when it exposes spoilers or exists only to inflate completion time | +| Regular advanced or hidden hybrid Profession | A transformation of targeting, timing, position, resource flow or risk ownership with declared prerequisites | Reject when it is only a stronger version of an existing Profession | +| Trait | One visible mechanical benefit and one cost that change offer, equipment or Party-line valuation | Reject when it is biography, flavor-only text or an unbounded extra rules bundle | +| Equipment | Eligible users, changed verb, trigger, tradeoff, order consequence, comparison rule and visible feedback | Reject when only a scalar value, rarity or presentation variant changes | +| Artifact | Run-wide contingency, Market or battle-offer valuation change, conflict with other plans and a visible trigger | Reject when it attaches as ordinary unit equipment or is merely a larger generic bonus | +| Ordinary or elite enemy | Pre-commitment signal, threat rule, target pressure, counter, ally interaction, escalation state and result explanation | Reject when color or health is the only meaningful difference | +| Boss | Contract-rule synthesis, phase and timeout logic, summon or displacement pressure, previewed counters and causal result needs | Reject when it is an ordinary enemy with only larger numbers | +| Region | New composition or Market pressure, formation-order valuation, environmental rule, recovery question and two-Contract escalation | Reject when it is only a visual reskin with larger numbers | The matrices should distinguish an **identity** from its **presentation variants**. Rarity, level, portrait expression, equipment overlay, animation @@ -121,14 +126,14 @@ the underlying data model. | Moment | Primary information | Secondary information | Deferred detail | |---|---|---|---| -| Forecast | Route pressure, known threat, opportunity and deadline | Guild capacity and recovery exposure | Full historical statistics | -| Recruit or job choice | Responsibility gained, constraint accepted and team interaction | Growth path and equipment eligibility | Complete progression tree | +| Contract forecast | Region pressure, enemy families, boss rule, difficulty and reward breadth | Guild unlocks and recovery exposure | Full historical statistics | +| Provisional Recruit or Market offer | Profession responsibility, Trait benefit and cost, rolled attributes and Coin price | Party-line fit, equipment eligibility and offer provenance | Generated-name and appearance detail | | Equipment | Changed behavior, eligible target, replacement result and resource cost | Synergies and comparison detail | Collection lore | -| Formation | Order, targeting exposure, protection relationship and movement implication | Alternate saved plans | Cosmetic presentation | -| Route commitment | Expected risk, reward class, uncertainty and irreversible cost | Relevant counters and recovery reserve | Unrelated collection progress | -| Battle | Current objective, dangerous cause, intervention availability and speed state | Aggregate team state | Long-form build explanation | -| Result | First collapse, decisive interaction, injuries/losses and earned choices | Contribution detail and event log | Meta collection celebration | -| Progression | New decisions unlocked and prerequisites | Long-term path preview and reset consequence | Unrelated branch detail | +| Party line | Front-to-rear order, target exposure, protection, reach and movement implication | Reserve options and predicted first interactions | Cosmetic presentation | +| Battle-offer commitment | Enemy order, risk tier, reward, retreat result and irreversible cost | Relevant counters and recovery reserve | Unrelated collection progress | +| Battle | Current objective, dangerous cause, pause/speed/inspect/retreat state | Aggregate Company state | Long-form build explanation | +| Result | First collapse, decisive interaction, Fallen Recruits, returned equipment and earned choices | Contribution detail and event log | Meta collection celebration | +| Meta progression | New breadth, information and challenge rules | Long-term catalog and mastery prerequisites | Unrelated history detail | Tooltips must explain changed behavior in the same vocabulary used by battle and results. Empty, locked, unaffordable, incompatible, full-capacity and @@ -137,22 +142,29 @@ must carry meaning without relying on color, animation speed or audio alone. ## Approved Original Scope -These are direct, exact product-specification commitments, not observed or -inferred reference totals. Their authority is the [frozen product contract][PRODUCT]. +These are direct product commitments, not observed or inferred reference +totals. Their authority is the [frozen product specification][PRODUCT] and +[current game contract][GAME]; stable identity namespaces are recorded in the +[content matrix authority][CONTENT]. | Original content family | Approved count | Evidence class and exactness | Planning consequence | |---|---:|---|---| -| Named recruitable characters | 30 | Direct specification; exact | Each row needs a distinct personal constraint and build role. Shared rigs may support production, but identities cannot be palette variants. | +| Generated Recruits | Dynamic; no preset identity total or cumulative-hire cap | Direct specification; structural | Each Recruit is a compositional Run participant. Generated name and modular appearance do not create additional gameplay identities. | | Base professions | 12 | Direct specification; exact | The base set must cover genuinely different responsibilities and resource verbs. | -| Advanced professions | 24 | Direct specification; exact | Each base profession receives authored transformations whose decision impact survives comparison. | -| Enemy combat identities | 100 | Direct specification; exact | Encounter design must compose rule interactions, not multiply visual variants. | -| Chapters | 8 | Direct specification; exact | Each chapter adds a decision grammar and culminates in a synthesis encounter. | -| Equipment and items | 320 | Direct specification; exact | Production should use coherent families while keeping each gameplay record traceable. | -| Behavior-changing equipment and items | At least 120 | Direct specification; lower-bound acceptance threshold | Validators must flag rows that change behavior, targeting, timing, positioning, resources or job identity and reject unsupported claims. | +| Regular advanced Professions | 24 | Direct specification; exact | Each base Profession has exactly two regular descendants whose decision impact survives comparison. | +| Hidden hybrid Professions | 6 | Direct specification; exact | Hybrid prerequisites and behavior must be discoverable and mechanically distinct; the full Profession catalog totals 42. | +| Mechanical Traits | 36 | Direct specification; exact | Every Recruit has exactly one lightweight benefit-and-cost modifier. | +| Equipment | 320 | Direct specification; exact | Production should use coherent families while keeping each behavior record traceable. | +| Artifacts | 60 | Direct specification; exact | Each identity changes shared Run valuation and remains distinct from unit equipment. | +| Ordinary and elite enemies | 100 | Direct specification; exact | Encounter design must compose rule interactions, not multiply visual variants. | +| Bosses | 16 | Direct specification; exact | Each boss synthesizes its Contract and exposes its distinctive rules before commitment. | +| Regions | 8 | Direct specification; exact | Each Region contains two ordered Contracts and two bosses and introduces a distinct pressure or valuation question. | The reference census neither proves nor justifies these targets. It demonstrates -why gameplay rows and presentation assets need separate budgets. The original -contract remains the sole authority for scope. +why gameplay rows and presentation assets need separate budgets. The frozen +specification and current game contract remain the sole authorities for scope; +the content matrix records their stable IDs and currently requires at least 160 +of the 320 equipment rows to change behavior rather than only a scalar. ## Production-Scope Implications @@ -196,10 +208,10 @@ prove the workflow is designed. ### Budget Diagnostic Feedback Auto-battle production scope includes more than attacks. It needs pre-commit -telegraphs, impact readability, misses and mitigation, status changes, death or -withdrawal, intervention readiness, speed-safe feedback and result causality. -Animation, VFX and audio budgets should map to these event roles before bulk -asset creation. +telegraphs, cast and impact readability, misses and mitigation, target changes, +projectile collisions, displacement, summons, status changes, casualties, +retreat, speed-safe feedback and result causality. Animation, VFX and audio +budgets should map to these event roles before bulk asset creation. ## Adopt, Adapt, Reject @@ -207,9 +219,9 @@ asset creation. |---|---|---| | Adopt | Make pre-battle choices visibly affect automated outcomes and make results diagnostic | Author new rules, vocabulary and presentation for every state | | Adopt | Use recovery to keep failure consequential but playable | Balance from the original economy, without platform-funded rescue assumptions | -| Adopt | Let persistent progression expand the planning space | Build an original graph, prerequisites, branch meanings and reset policy | +| Adopt | Let persistent progression expand the planning space | Open original breadth, information and challenge rules without permanent universal power | | Adapt | Combine related preparation questions where it reduces navigation | Use an original information architecture; do not reproduce the reference arrangement | -| Adapt | Use milestone rewards as build pivots | Create original identities, triggers, conflicts and visual language | +| Adapt | Use Artifacts and fixed rewards as build pivots | Create original identities, triggers, conflicts and visual language | | Adapt | Use modular asset production to control scope | Define original silhouettes, rigs, layers and animation grammar | | Reject | File counts as evidence of gameplay breadth | Validate content matrices and asset inventories separately | | Reject | Speed settings, tutorials or UI states counted as content modes | Define mode boundaries by rules, progression and failure contract | @@ -220,8 +232,8 @@ asset creation. The census should change downstream work in concrete ways: -- **Systems specifications:** define the full loop handoffs, intervention - boundary, failure recovery, persistence and save semantics. +- **Systems specifications:** define the full loop handoffs, automatic-battle + control boundary, failure recovery, persistence and save semantics. - **Content matrices:** assign stable original IDs and the differentiator fields above; maintain separate variant and asset references. - **Screen/state map:** show decision-specific hierarchy, reversible and @@ -251,7 +263,7 @@ answer yes to all of the following: states? - Are names, prose, formulas, values, layouts, trees, art and audio independently authored? -- Does the result add a distinct job, counterfactual or information need rather +- Does the result add a distinct decision, counterfactual or information need rather than a cosmetic variant? Failure of any answer is an originality or completeness blocker during the @@ -259,3 +271,5 @@ design-only stage. [CENSUS]: REFERENCE_RUNTIME_CENSUS.md [PRODUCT]: ../../.agent-taskgraph/spec.md +[GAME]: ../product/GAME_PRODUCT_CONTRACT.md +[CONTENT]: ../content/CONTENT_INDEX.md