wushenghua/aetherbound-guild
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define systems economy and save contracts

Browse Source
This commit is contained in:
wushenghua
2026-08-10 19:32:31 +08:00
parent 3cb0c66d8d
commit de607ab03e
4 changed files with 2482 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/product/ECONOMY_AND_BALANCE.md
+444
View File
@@ -0,0 +1,444 @@
# Aetherbound Guild: Economy And Balance Authority
> Authority: resource movement, rewards, item progression, chapter budgets,
> difficulty modifiers, and balance validation.
>
> Revision: design-batch-01 / 2026-08-10
>
> [GAME_PRODUCT_CONTRACT.md](GAME_PRODUCT_CONTRACT.md) owns the player promise,
> cadence, and commercial boundary. [SYSTEMS_AND_BATTLE.md](SYSTEMS_AND_BATTLE.md)
> owns combat execution and profession hooks. [SAVE_AND_FAILURE_CONTRACT.md](SAVE_AND_FAILURE_CONTRACT.md)
> owns transaction and recovery behavior. Content documents own the names and
> instances of the 30 adventurers, 36 professions, 100 enemies, 8 chapters, and
> 320 equipment/items.
## 1. Economy Invariants
1. All gameplay resources are earned in play. There is no premium currency,
paid energy, ad reward, timer, loot box, login streak, or online-only claim.
2. Every source and sink is visible before commitment and is recorded in the
encounter result. A failed or cancelled operation spends nothing.
3. A resource can be scarce enough to create a choice, but never so scarce that
a first-campaign baseline counter requires grinding a random drop.
4. The same item is not universally better than another item in its band. An
upgrade may increase a budget term only when it also declares an interaction,
timing, targeting, route, or risk change.
5. Reward generation is seeded and stream-separated from combat. The save
authority stores the seed and operation IDs, so replay and recovery cannot
duplicate rewards.
6. The first campaign is solvable with the deterministic acquisition paths and
the starting roster. Optional collection and high difficulty may ask for
broader mastery, never mandatory payment or idle time.
## 2. Resource Ledger
These stable resource IDs are the only persistent economy resources. `Supplies`
and `Strain` are expedition state defined by the systems authority; they are
listed here because their conversion affects balance.
| ID | Player name | Type/cap | Sources | Sinks | Failure treatment |
|---|---|---|---|---|---|
| `crown` | Crowns | Spendable, no hard cap; soft reserve target 600 | Conflict, hazards, anchors, salvage, chapter objectives | Recruit, shop refresh/lock, craft fee, upgrades, route tolls | Unsecured Crown rewards follow difficulty; banked Crowns never disappear |
| `fiber` | Loom Fiber | Persistent material, cap 9,999 | Item salvage, hazards, chapter bundles, duplicate protection | Crafting, behavior upgrades, repair blueprints | Banked only; a failed node cannot consume it |
| `shard` | Aether Shard | Persistent meta material, cap 9,999 | Anchor restoration, mastery trials, first-clear objectives | Profession trials, Reweave law unlocks, deterministic tag rerolls | Never lost; grants are idempotent |
| `xp` | Adventurer XP | Per-adventurer progress, level 1-50 campaign / 70 Reweave | Completed encounters and authored objectives | Level thresholds; no currency conversion | Awarded only once per encounter outcome |
| `mastery` | Profession Mastery | Per adventurer/profession/branch; no decay | Using a profession, solving its counter trial, discovery goals | Unlock Adept/Master/branch access; standing orders | Never lost; duplicate award ignored |
| `supplies` | Supplies | Expedition capacity, 6 default, 9 cap | Start-of-expedition allotment, route nodes, anchor bonuses | Recover, secure, scout, reroute, extra profession change | Difficulty-specific amount is shown before commit |
| `strain` | Strain | Per adventurer, 0-3 stacks | Downed/Lost in encounter, failed hazard, hard retreat | Recover at Camp/Anchor or Guild | Never deletes a first-campaign adventurer; 3 stacks blocks deployment |
`Crown` is deliberately singular in text and `Crowns` in UI. Aether Shards are
not the battle `Aether` meter. No item or facility may create a new persistent
currency without an Owner-approved contract revision.
## 3. Crown Flow And Solvency
### 3.1 Encounter Income
For a node at chapter `C` (1-8), route depth `D` (0-6), risk tier `R` (0 safe,
1 pressured, 2 elite), and objective flag `O` (0/1), the base reward is:
```text
base_crowns = round(55 + 18*C + 12*D + 30*R + 35*O)
victory_crowns = floor(base_crowns * difficulty_reward_multiplier)
```
An authored story node may replace `base_crowns` with a declared bundle, but
the bundle must be within 0.75x-1.35x of the formula at the same depth. An elite
may add one reward choice, not an unbounded Crown multiplier. A failed node
does not grant victory Crowns; its failure disposition is in the save contract.
An Anchor grants `40 + 20*C` Crowns for restoring its route, once per campaign
slot. A first-clear objective grants `60 + 25*C` Crowns and `1 + floor(C/3)`
Aether Shards. Replaying a cleared objective grants ordinary node rewards only.
### 3.2 Crown Sinks
| Action | Formula | Tunable bounds and reason |
|---|---|---|
| Recruit a named adventurer | `90 + 12*C + 5*max(0, roster_size-6)` | 102-250 Crowns; story recruits may waive cost |
| Shop refresh at Anchor | `min(60, 10 + 5*refreshes_this_anchor)` | Resets at Anchor; prevents infinite fishing |
| Lock a shop offer | `8 + 2*locked_offers` | 8-16 Crowns, disclosed before lock |
| Shop quality investment | `180 + 60*shop_level` | Levels 0-4; each level changes pool tags, not a flat damage bonus |
| Crafting service fee | `30 + 15*tier` | 30-90 Crowns; material cost remains meaningful |
| Item behavior upgrade fee | `40 + 25*tier + 10*band` | `band` is 0-7; no upgrade exceeds 240 Crowns |
| Route toll | `20 + 10*C + 10*R` | Only on a declared shortcut; never required to reach an Anchor |
| Optional training replay | 0 | No reward and no resource sink; preserves learning |
`refreshes_this_anchor` and `locked_offers` are expedition counters. A player
cannot reset the counters by closing the game or reloading an older snapshot;
the save journal makes the counter increment atomic with the purchase.
### 3.3 Crown Budget Check
The baseline campaign starts with 240 Crowns, two authored adventurers, four
starter items, and six Supplies. A solvency run uses the lowest deterministic
reward in each chapter and buys at least one counter item and one recruit per
chapter. It must satisfy:
```text
banked_crowns_after_chapter(C) >= 80 + 20*C
required_counter_purchase(C) <= 0.45 * expected_chapter_income(C)
```
The player may be Crown-poor after an optional elite, but a safe route and a
deterministic counter reward must restore solvency within the next expedition.
No chapter may require more than three refreshes to expose a legal counter.
### 3.4 Unused Supplies Conversion
After a successful expedition closes at an Anchor, or after a voluntary route
withdrawal, unused Supplies convert once and the expedition Supply balance
becomes zero:
```text
supply_crown_bonus = min(80, 8*unused_supplies + 4*chapter)
```
A defeated expedition receives no conversion bonus. The conversion operation is
atomic with expedition close, so reload or duplicate confirm cannot pay twice.
The 80-Crown cap keeps preserving Supplies valuable without making avoidance of
recovery universally correct.
## 4. Materials, Salvage, And Crafting
### 4.1 Item Budget And Tiers
The 320 catalog entries are divided into eight chapter bands of 40 entries.
Each band contains 16 Focus, 12 Garb, 8 Relic, and 4 Tool entries. Content may
move a row between slots only with a documented replacement row; the total stays
320. Each band has five tier steps (`0` starter through `4` capstone) and at
least 15 behavior-changing rows. Across the catalog, at least 120 rows pass the
behavior test below; the remaining rows may be stat-focused but still need a
counterfactual use case.
An item declares a `budget` from the systems stat vocabulary:
```text
item_budget = 60 + 10*chapter_band + 12*tier
```
The row may spend the budget on Power, HP, Guard, Ward, Tempo, Initiative,
status Potency/Tenacity, or one named behavior hook. A behavior hook consumes
10-28 budget points depending on scope. A single row cannot spend more than 55%
of its budget on generic Power/HP/defense. The remainder is a visible tradeoff.
### 4.2 Behavior-Changing Test
An item is counted among the required 120 only when removing it from a fixed
company changes at least one observable event in two validation encounters:
```text
behavior_change = legal_action OR target_set OR timing_window OR
formation_relation OR resource_conversion OR status_rule OR
route_option OR risk_exposure OR profession_identity
```
The validation record must name the removed hook, before/after event, cost, and
the two encounters. A conditional `+N%` with the same target, timing, and route
is not a behavior change. The catalog may not use rarity, color, or a larger
number as the only difference between two rows.
### 4.3 Salvage
Salvaging an item at the Guild is a single atomic operation. For tier `T`, band
`B`, and item base budget `P`:
```text
fiber_yield = 1 + floor(T/2)
shard_yield = 1 if T >= 3 and the row has a behavior hook, else 0
crown_yield = floor(4 + 6*T + P/50)
```
The UI previews all yields. A locked item, equipped item, or item referenced by
an active loadout cannot be salvaged until the player explicitly unequips or
removes the lock. Batch salvage requires a review of the exact stable IDs.
### 4.4 Crafting And Upgrades
Recipes are deterministic and preview the output stable ID and its possible
behavior branch. A recipe consumes two or three declared source rows, `2 + T`
Loom Fiber, and `1` Aether Shard for tier 3-4 outputs. It may not consume a
random source that has no deterministic fallback.
For a behavior upgrade from tier `T` to `T+1` at band `B`:
```text
crowns = 40 + 25*T + 10*B
fiber = 2 + T
shards = 1 if T >= 2 else 0
```
The upgraded row must exchange or refine a hook, not simply multiply all
coefficients. A row has at most two behavior upgrades in the first campaign.
At tier 4, a player may instead unlock one alternate behavior branch by
spending the same cost and a named mastery trial; both branches remain
reversible at the Guild.
### 4.5 No Hidden Item Tax
There is no durability, repair timer, inventory rent, or item destruction on
defeat. A player may keep all 320 catalog entries in a fixed-capacity archive;
the practical limit is equipped copies, not a storage expansion purchase.
## 5. XP, Mastery, And Profession Investment
### 5.1 XP Curve
For character level `L` (1-49), the XP required to reach `L+1` is:
```text
xp_to_next(L) = floor(95 * L^1.35)
```
Encounter XP is:
```text
encounter_xp = floor((50 + 25*C + 10*D + 35*R + 20*O) * xp_multiplier)
```
Deployed adventurers receive 100% of encounter XP; reserves receive 60% when
the company wins without being deployed. An adventurer who is Downed receives
50% of the award, and one Lost for the encounter receives 25%. There is no XP
for a failed node, but the player keeps any previously banked XP. XP beyond the
level cap is not converted into another resource.
The Guild offers a no-cost catch-up grant to an adventurer more than eight
levels below the chapter band:
```text
catch_up_xp = min(0.35 * xp_to_next(target_level),
xp_to_next(target_level) - current_level_xp)
```
It is available once per Anchor and cannot leapfrog the chapter level cap.
### 5.2 Mastery
Base profession Mastery gains per completed encounter are:
```text
mastery = 2 + min(3, distinct_profession_hooks_used) +
2*(previewed counter tag answered) + 3*(signature used)
```
The per-encounter cap is 12. A branch trial grants 40 Mastery once. A base
reaches `Adept` at 100 and `Master` at 300; advanced branch mastery uses the
same 300 threshold. Repeating a training replay grants no XP, Mastery, or
rewards. Mastery is proof of use, not a mandatory permanent stat tax.
### 5.3 Aether Shard Meta Progression
Aether Shards are earned from first-clear objectives, Anchor restoration, and
behavior-changing item discovery. In the first campaign they unlock authored
profession trials and archive views; they do not add raw combat percentages.
Postgame Reweave law unlocks cost 12-30 Shards each and are finite. A player
can earn every required trial Shard on deterministic routes before the final
campaign confrontation.
### 5.4 Recruitment
All 30 adventurers are authored, unique, and persistent. The campaign begins
with two. Each of the remaining 28 has one authored availability chapter and one
deterministic recruitment objective. A route draft may reveal a recruit early,
but random generation cannot make that recruit permanently unavailable.
Accepting recruitment pays the Crown formula in Section 3.2 and adds the
adventurer once. Deferring adds the candidate to the Guild board. If the
availability chapter is `A`, the fixed deferred cost in later chapter `C` is:
```text
deferred_recruit_cost = ceil(cost_at_availability *
max(0.50, 1 - 0.10*max(0, C-A)))
```
This makes a missed opportunity recoverable without a grind wall. Recruits
cannot be duplicated, sold, sacrificed, or permanently dismissed. A full active
company sends the new recruit to the roster bench without unequipping anyone.
The content package must expose all 12 base professions through available
recruits by the end of Chapter 3 and make all 30 recruits deterministically
available by the final Chapter 8 Anchor. Recruitment never depends on a shop
refresh or a specific random item.
## 6. Loot, Route Rewards, And Bad-Luck Protection
At an Opportunity or Elite node, the player sees three reward cards: one
guaranteed tag-directed card, one deterministic material bundle, and one
seeded choice. The guaranteed card is selected from the requested counter tag
or the chapter's current item band. Declining it is legal and visible.
The reward stream uses `reward` only; it cannot alter `critical` or
`target_tie` streams. Bad-luck protection is deterministic:
```text
if two consecutive eligible drafts omit a requested tag:
the third eligible draft contains that tag
```
The protection resets after the tagged card is offered, not after the player
accepts it. A tag request is chosen at an Anchor and may be changed for free.
It cannot name a specific item until that item has been discovered in the
archive, preventing an early catalog lookup from becoming a guaranteed best
build.
An immediate-secure reward pays 80% of the card's Crown value and banks it;
accepting it into the Unsecured Cache pays 100% but exposes it to the active
difficulty contract. This is a deliberate risk tradeoff, not a hidden fee.
## 7. Difficulty Contracts
Difficulty changes failure meaning and reward exposure, not the availability of
counterplay. The first campaign defaults to `Wayfinder`.
| Contract | Defeat/retreat | Reward multiplier | Supplies | Intended use |
|---|---|---:|---:|---|
| Wayfinder | Lose 25% of Unsecured Cache value, +1 Strain to each Downed/Lost unit (at most two affected units), recover at Anchor if eligible | 1.00x | 6 | Learning and normal campaign |
| Stormbound | Lose 50% of Unsecured Cache value, +1 Strain to every deployed Downed/Lost unit, recover at Anchor if eligible | 1.15x | 6 | Active campaign |
| Iron Oath | Lose all Unsecured Cache, +2 Strain to Downed/Lost units, close route and expedition at Guild | 1.30x | 5 | Adversarial/high-risk campaign |
| Reweave law: Frayed Routes | On defeat one revealed node is reshuffled, no extra loss; route previews remain complete | 1.10x | 7 | Postgame variation |
| Reweave law: Scarce Anchors | Secure costs +1 Supply and withdrawal banks 75% of Cache | 1.25x | 5 | Postgame mastery |
No campaign or Reweave contract defined here permanently deletes or retires an
adventurer. High difficulty increases exposed rewards, route loss, Supplies,
and Strain pressure instead of converting the roster into disposable currency.
Exact Supply consumption, battle retreat, withdrawal, Anchor eligibility, and
failure transaction ordering are owned by the save/failure authority.
`difficulty_reward_multiplier` is applied once to a reward operation and is
rounded down. It never multiplies XP or Mastery, so difficulty cannot become a
mandatory farming route for profession access.
## 8. Chapter Pacing Budget
These budgets are the balance target for a normal profile. Active players may
finish 10% faster through legal automation; adversarial players may take 20%
longer through recovery and optional elites. There are no timers that force
waiting.
| Chapter | Expeditions | New decision pressure | Target minutes | First-clear Shards | Item bands |
|---:|---:|---|---:|---:|---|
| 1 | 6 | protection and first telegraph | 180-195 | 4 | 0 |
| 2 | 7 | displacement and lane exposure | 195-210 | 5 | 0-1 |
| 3 | 7 | status timing and branch access | 205-220 | 6 | 1-2 |
| 4 | 8 | multi-lane objectives | 210-225 | 7 | 2-3 |
| 5 | 8 | resource conversion and barriers | 220-235 | 8 | 3-4 |
| 6 | 8 | cast chains and reserve rotation | 220-240 | 8 | 4-5 |
| 7 | 9 | combined old/new pressure | 230-250 | 9 | 5-6 |
| 8 | 9 | final rupture and counterfactual mastery | 240-270 | 10 | 6-7 |
The chapter midpoint must have a safe Anchor, a deterministic counter item, and
at least one branch trial. A chapter's final confrontation may consume up to
two normal expeditions of time but must present a new choice at each phase.
The sum of the lower bounds is 1,700 minutes (28.3 hours); active mastery and
route familiarity bring the first-campaign target into the frozen 25-35 hour
window without idle income.
### 8.1 Cumulative Completion Budget
| Milestone | Additional authored play after prior milestone | Cumulative target | Required work, never waiting |
|---|---:|---:|---|
| First campaign ending | 25-35 h | 25-35 h | Eight chapters and final confrontation |
| Build completion | 30-40 h | 60-75 h target, 80 h hard budget | Remaining branch trials, counterfactual encounters, profession mastery, build variants |
| Collection/high difficulty | 20-30 h | 85-105 h centered near 100 h | Deterministic catalog gaps, Reweave laws, final challenge fixtures |
The cumulative total is a breadth target, not a retention promise. Repeated
completion of an unchanged encounter may contribute at most 20% of any
milestone's additional hours. The rest must come from new branch comparisons,
route laws, item interactions, enemies, or authored mastery trials.
## 9. Pacing Simulation Profiles
The following assertions are required for a representative 20-minute session
and for a full-campaign budget run. They make the product contract measurable.
| Profile | Preparation behavior | Route behavior | Intervention behavior | Expected resource posture | Required assertions |
|---|---|---|---|---|---|
| Normal | One counter loadout change per 1-2 nodes | Mixes safe and pressured nodes | One manual Directive per battle | Ends an expedition with 1-3 Supplies and 50-150 Crowns | >=6 meaningful decisions/20 min; no gap >150 s |
| Active | Compares two builds and formation lines | Selects a branch after each preview | Uses both charges when legal; pauses at telegraphs | Lower Supplies, higher secured reward | >=10 decisions/20 min; no gap >120 s |
| Efficient | Uses standing orders on mastered routine | Chooses shortest viable path | Manual only on unmastered tags/exception | Retains 2+ Supplies for conversion | >=4 decisions/20 min; no gap >165 s |
| Adversarial | Keeps a fragile synergy for elite rewards | Presses Cache until 2+ Strain or phase risk | Saves a charge for the final phase | Cache variance is high but positive over 3 expeditions | >=8 decisions/20 min; no gap >135 s |
| Returning | Reads a 90-second recap and changes one rule | Resumes at last Anchor or chooses a known route | Replays one diagnostic before commitment | Starts with the same banked resources; no catch-up gift beyond defined grant | >=3 decisions/12 min; no gap >150 s |
For each profile, a balance run records `decision_time`, `decision_kind`,
`state_before`, `available_actions`, `chosen_action`, and `state_after`. A
choice is meaningful only when two legal actions produce different expected
outcomes under the current state. A report that lists only reward claims does
not satisfy this audit.
## 10. Balance Gates And Anti-Dominance Tests
The numeric package is ready for implementation only when these checks pass:
1. **Solvency:** the lowest-reward Wayfinder run reaches every chapter Anchor,
buys at least one deterministic counter item per chapter, and reaches the
final confrontation with 80 + 20*chapter Crowns in reserve.
2. **Frontier:** for each fixed encounter, at least two loadouts have a 60%+
simulated clear rate over the declared reward seed set, and their advantage
switches on a follow-up encounter with a different pressure tag.
3. **Item diversity:** at least 120 catalog rows pass the two-encounter
behavior-changing test; no ten-row sample has more than six rows whose only
useful effect is generic Power/HP/defense.
4. **Route diversity:** across three seeded route graphs, the optimal node
choice differs for at least two of the five pacing profiles.
5. **Failure recovery:** after three consecutive defeats, Wayfinder can return
to a viable counter build within two expeditions without a random drop.
6. **Decision density:** no profile has a gap above its table threshold or a
battle that reaches the 180-second Fracture defeat in more than 5% of normal
seeds.
7. **Inflation:** by Chapter 8, a normal player can afford one upgrade and one
craft every two expeditions while retaining a meaningful refresh decision;
Crowns must not become irrelevant before the final Anchor.
8. **Postgame:** all finite Reweave laws and branch trials are reachable by
roughly 60-80 hours; collection/high-difficulty completion has a visible
terminal state around 100 hours.
Any failed gate is reported with the earliest failing resource or encounter
fixture. Tuning may change constants only within the ranges in this document;
changing a resource's meaning requires a product/spec revision.
## 11. Fixed Economy Test Vectors
| Vector | Inputs | Expected result |
|---|---|---|
| Crown reward | C=3, D=2, R=1, O=1, Wayfinder | `floor(55+54+24+30+35)=198` Crowns |
| Refresh cap | 12 refresh attempts at one Anchor | Costs 10,15,...,60 then remains 60; no negative balance |
| Salvage | T=3, B=4, P=144 | 2 Fiber, 1 Shard, `floor(4+18+2)=24` Crowns |
| Upgrade | T=2, B=5 | 130 Crowns, 4 Fiber, 1 Shard; one behavior branch only |
| XP | C=2, D=3, R=1, O=0, Wayfinder | `50+50+30+35=165` XP per deployed unit |
| Mastery cap | Signature + two distinct hooks + counter | 9 Mastery before the per-encounter cap |
| Cache choice | 100-Crown card, immediate secure | 80 banked Crowns; no Unsecured Cache entry |
| Bad luck | Two eligible drafts omit requested tag | Next eligible draft includes the tag |
| Supplies conversion | 3 unused Supplies at Chapter 4 | `8*3+4*4=40` bonus Crowns, paid once at expedition close |
| Difficulty | 200-Crown Cache, Stormbound defeat | 100-Crown value removed; banked Crowns untouched |
## 12. Authority Checklist
- [ ] Resource IDs, sources, sinks, caps, and failure treatment are explicit.
- [ ] All item tiers and the 120 behavior-changing requirement have a test.
- [ ] Crown, XP, Mastery, crafting, reward, and difficulty formulas are fixed.
- [ ] Eight chapter budgets sum to the 25-35 hour campaign target.
- [ ] Normal, active, efficient, adversarial, and returning profiles have
decision timestamps and maximum no-decision gaps.
- [ ] Solvency, inflation, anti-dominance, recovery, and postgame gates are
defined without a paid or idle progression path.
docs/product/GAME_PRODUCT_CONTRACT.md
+576
View File
@@ -0,0 +1,576 @@
# Aetherbound Guild: Game Product Contract
> Authority: player promise, scope, experience cadence, progression shape, and
> product boundaries for the complete pre-production package.
>
> Revision: design-batch-01 / 2026-08-10
>
> Companion authorities:
> [SYSTEMS_AND_BATTLE.md](SYSTEMS_AND_BATTLE.md),
> [ECONOMY_AND_BALANCE.md](ECONOMY_AND_BALANCE.md), and
> [SAVE_AND_FAILURE_CONTRACT.md](SAVE_AND_FAILURE_CONTRACT.md).
## 1. Authority And Decision Order
This document answers what the game promises and why a system exists. The
systems document owns combat and progression mechanics, the economy document
owns numeric pacing and resource movement, and the save/failure document owns
transaction and recovery behavior. When wording conflicts, use this order:
1. Frozen repository specification and Owner decisions.
2. Save and transaction safety rules.
3. Explicit formulas and boundaries in the systems and economy authorities.
4. This product intent.
5. Content, presentation, and prototype instances.
The design is implementation-ready but is not evidence that the experience is
fun, understood, visually accepted, device-safe, or ready for production.
Those remain later prototype, independent-review, and Owner gates.
## 2. Product Definition
**Aetherbound Guild** is a premium, landscape 2D party-building strategy RPG.
The player leads a magic guild restoring a network of ruptured aether routes.
They recruit persistent adventurers, assign professions and skill loadouts,
equip them, arrange a six-person formation, choose a route, and watch a
deterministic auto-battle execute their preparation. During battle, the player
may spend at most two Command charges on prepared tactical directives.
The product is not an idle game, gacha, live-service treadmill, or action RPG.
Its skill is diagnosis and preparation:
```text
read a visible threat
-> predict the party's first failure point
-> change one or more high-leverage rules
-> watch those rules execute
-> compare prediction with result
-> secure rewards or accept more risk
-> permanently change the guild and the next route
```
### 2.1 Audience
Primary players enjoy party composition, job systems, equipment interactions,
route planning, and the satisfaction of seeing a prepared plan work. They want
meaningful strategy without continuous high-frequency control.
Secondary players include completionists who want to master all 36 professions
and 320 items, and challenge players who want stricter route modifiers after a
finite campaign ending.
The game must remain usable by players who pause often, play in 8-20 minute
segments, use touch only, or return after a long break.
### 2.2 Fixed Commercial And Platform Boundary
| Field | Contract |
|---|---|
| Business model | One-time premium purchase; no ads, loot boxes, paid energy, paid currency, battle pass, daily streak, or pay-to-skip |
| Platforms | Landscape 16:9 target for mobile, PC, and console; current design must support touch, mouse, keyboard, and controller semantics |
| Languages at first release | English and Simplified Chinese, authored from message IDs rather than concatenated strings |
| First campaign | 25-35 hours, eight authored chapters, finite ending |
| Build completion | 60-80 hours for broad profession/build mastery |
| Collection/high difficulty | Approximately 100 hours, with a visible completion state rather than endless obligation |
| Connectivity | Core campaign fully offline; optional platform services may never gate play or save access |
| Formal development | Frozen until complete design, independent review, and explicit Owner approval |
Future paid expansions may add authored chapters after release, but may not
sell power, random rewards, timers, or relief from deliberately created
friction. Such an expansion is outside this design authority.
## 3. Player Fantasy And Emotional Arc
The player is the guild's strategist, not a distant spectator and not a
puppeteer issuing every attack. Adventurers have stable identities and execute
the rules the player prepared. The fantasy progresses through four scales:
| Scale | Player fantasy | Required emotion |
|---|---|---|
| Seconds | Read a clean magical skirmish and see a prepared rule fire | Comprehension, then confirmation |
| Expedition | Guide a company through a risky branch of the ruptured network | Anticipation, tension, adaptation |
| Chapter | Restore a regional anchor and make the guild capable of a new kind of expedition | Competence and transformation |
| Campaign/postgame | Reconnect the world, then deliberately reweave it under harder laws | Ownership, mastery, curiosity |
The expected emotional sequence around failure is: surprise no longer than
three seconds, a legible cause, a credible countermeasure, and an immediate
safe place to try that countermeasure. Failure may cost route opportunity but
must not erase understanding or named-character attachment.
## 4. Experience Pillars
### 4.1 The Battle Honors Preparation
Targeting, timing, formation protection, status resolution, and directive
execution are deterministic from visible inputs and a stored seed. A unit may
fail to follow an order only for a named, inspectable reason. The battle report
must identify that reason.
### 4.2 Every Threat Changes The Best Answer
Encounter previews expose mechanics, lanes, timing, defenses, and reward risk.
At least two rational responses must exist for every required campaign threat.
Their value must vary with current health, roster, supplies, equipment,
unsecured rewards, and route position.
### 4.3 Named Adventurers Become A Guild History
All 30 recruits are authored characters rather than disposable random units.
Their profession mastery, signature interactions, injuries, and chapter
participation persist. No standard campaign rule permanently deletes one.
### 4.4 Randomness Presents Problems, Not Verdicts
Route generation, reward drafts, and seeded combat details can vary, but the
player sees bounded choices, tag-directed acquisition, and bad-luck protection.
Required build pieces always have a deterministic acquisition route.
### 4.5 Completion Changes The Next Cycle
Restoring an anchor changes available routes, guild services, profession
branches, and world rules. Solved routine encounters may gain conditional
automation, but new mechanics remove that automation's certainty. The next
cycle begins with inherited consequences and a different planning question.
## 5. Anti-Pillars And Design Vetoes
Reject a feature or content row if it depends on any of the following:
- watching numbers rise without a new state-dependent decision;
- an auto-battle rule that can silently disregard formation or targeting;
- a higher rarity or power rating that is always the correct item choice;
- random acquisition without a visible deterministic fallback;
- permanent-stat grinding required to make baseline difficulty fair;
- manual repetition after the player has already demonstrated mastery;
- automation that removes the strategic decision along with routine labor;
- hidden recipes, hidden immunity, or surprise targeting exceptions;
- a battle longer than three minutes with no new decision opportunity;
- deleting a named character, save, item, or irreversible choice without a
clear confirmation and recovery boundary;
- daily/weekly obligations, real-time construction waits, or offline income;
- monetization, social comparison, or collection volume used to conceal a
weak core loop;
- copied names, formulas, layouts, prose, progression topology, or expression
from the authorized comparison material.
## 6. Canonical Terms And Content Envelope
These terms are shared keys. Other design documents must not introduce a
synonym for the same state.
| Term | Definition |
|---|---|
| Guild | Persistent player organization, roster, facilities, inventory, and campaign record |
| Adventurer | One of exactly 30 named recruitable characters |
| Company | Up to six deployed adventurers plus up to two expedition reserves |
| Profession | One active combat discipline; exactly 12 base professions and 24 advanced professions |
| Loadout | Profession skills, equipment, tactical directives, and formation position assigned before battle |
| Weave Grid | Three lanes by two ranks; the six legal deployment slots |
| Directive | A prepared, player-triggered tactical intervention that spends one Command charge |
| Encounter | One battle or noncombat decision node with a committed outcome |
| Expedition | One 8-20 minute route segment of four to seven nodes ending at an anchor or withdrawal |
| Chapter | A regional arc of multiple expeditions culminating in a persistent anchor restoration |
| Anchor | A safe route checkpoint that banks unsecured rewards and persists chapter progress |
| Unsecured Cache | Rewards earned since the last anchor and still exposed to defeat consequences |
| Supplies | Bounded expedition capacity spent on recovery, securing, scouting, or rerouting |
| Strain | Temporary adventurer injury, from zero to three stacks, cleared at the Guild |
| Mastery | Non-spend progress proving use of a profession or encounter solution |
| Reweave | Post-campaign cycle that preserves collection while changing route laws and build constraints |
The fixed authored content envelope is:
- exactly 30 named recruitable adventurers;
- exactly 12 base professions, each with exactly two advanced branches, for 24
advanced and 36 total profession identities;
- exactly 100 enemy combat identities across exactly eight chapters;
- exactly 320 equipment/item entries;
- at least 120 item entries whose behavior-change declaration passes the test
in the economy authority.
Content owns names and instances. Product systems own schemas, counts,
validations, and the purpose of every row.
## 7. Readability And Input Cadence
### 7.1 Three-Second Read
Within three seconds of entering an encounter preview or returning attention to
battle at 1x, the player must be able to identify:
1. which three lanes are contested;
2. which allied front slot protects each rear slot;
3. the enemy's next major telegraphed action and countdown;
4. the allied unit at greatest immediate risk;
5. current Command charges and whether a directive is legal;
6. whether rewards are secured or currently at risk.
This is a presentation and usability gate, not a claim that the current design
already passes human comprehension.
### 7.2 One-To-Ten-Second Actions
The common action set must resolve with immediate authoritative feedback:
| Action | Target completion | Immediate result |
|---|---:|---|
| Select a route node | 1-3 s | Threat/reward comparison and projected cache risk update |
| Inspect a telegraph or status | 1-3 s | Plain-language cause, timing, targets, and counter tags |
| Move a unit between legal slots | 2-5 s | Protection lines, reach, and predicted first target update |
| Equip or compare an item | 2-8 s | Stat delta plus behavior/skill timing delta |
| Change one skill or standing order | 2-8 s | Validity check and affected battle events preview |
| Fire a directive | 1-4 s | Simulation pauses for targeting if needed, then confirms cost and effect |
| Secure, recover, scout, or reroute | 2-10 s | Supplies and exposed-reward state update atomically |
No accepted tap, click, key, or controller action may wait for a decorative
animation before committing. Animation follows state and is skippable.
### 7.3 Thirty-To-180-Second Choices
Every 30-180 seconds during active expedition play, the state must ask a real
question such as:
- counter a visible cast or preserve Command for a later phase;
- keep a fragile damage plan or trade output for lane protection;
- spend Supplies to heal, expose the cache and press on, or bank it early;
- take a targetable equipment reward or a higher-value unknown reward;
- rotate in a reserve and accept a weaker profession link;
- use a mastered standing order or manually hold it for an exception;
- pursue the chapter objective or detour for a recruit/mastery objective.
Two consecutive nodes may never have the same optimal answer for all valid
company states. A sequence with no meaningful player decision for more than
180 seconds fails the design, even if effects and rewards occur during it.
## 8. Complete Player Loop
### 8.1 Guild Preparation
```text
read chapter pressure and next anchor objective
-> inspect roster health, mastery, and missing counter tags
-> select six deployed and up to two reserves
-> choose professions, skill loadouts, equipment, grid slots, and directives
-> choose one route entrance with explicit threat/reward information
```
The Guild is safe. Equipment and learned skill respec are free here. The scarce
decision is what the limited company and inventory can cover, not a respec tax.
### 8.2 Expedition
```text
preview two or three reachable nodes
-> choose route
-> prepare against the committed preview
-> resolve encounter
-> diagnose result
-> draft or decline reward
-> update unsecured cache, Strain, Supplies, and route stability
-> press, secure, recover, scout, reroute, or withdraw
-> reach anchor and bank progress
```
Route nodes are face-up once scouted. A selected encounter is not silently
rerolled by leaving its screen. All costs and failure exposure are shown before
commit.
### 8.3 Chapter Transformation
Each chapter follows this required progression:
1. A new rupture rule makes a previously reliable plan incomplete.
2. A safe encounter teaches the rule through visible consequence.
3. A guided route offers two credible counters.
4. Repeated routine handling can be encoded in one standing order.
5. An elite combines the rule with an older pressure and breaks naive
automation.
6. Restoring the regional anchor permanently adds a route, guild service,
profession branch, acquisition method, or formation rule.
7. The next chapter inherits that change and presents a different bottleneck.
A chapter cannot be approved if its only transformation is larger numbers,
another currency, cosmetic scenery, or an enemy rename.
### 8.4 Campaign Completion And Reweave
The first campaign ends after all eight regional anchors are restored and a
final authored confrontation resolves the world's immediate rupture. Credits,
epilogues, collection state, and campaign statistics are visible before any
postgame prompt.
Postgame offers three finite paths:
- **Build Mastery:** unlock and validate both advanced branches of every base
profession through authored trials.
- **Collection Completion:** discover the 320-item catalog and the mechanical
interaction attached to each behavior-changing entry.
- **Reweave:** begin a remixed eight-chapter cycle with persistent roster,
knowledge, and collection, but choose two world laws that alter route and
combat value. Item levels normalize to the cycle band so inherited breadth,
not raw overleveling, drives the new plan.
Reweave is not an infinite content promise. The package defines a final high-
difficulty completion badge and statistics screen around the 100-hour target.
## 9. Portfolio Incremental Chain
The game must prove the complete incremental contract through play:
| Chain step | Aetherbound implementation | Proof required later |
|---|---|---|
| Manual action | Player manually targets a Focus directive and moves a front/rear pairing | Real input causes visible targeting/protection change |
| Immediate result | Target line, cast countdown, damage source, and cache state update in the same interaction | Runtime frame/audio feedback and authoritative state agree |
| Automation | Adventurers execute loadouts and formation rules without attack spam from the player | Deterministic replay matches declared rules |
| Readable bottleneck | Preview/report identifies lane collapse, cast pressure, Strain, Supplies, or missing counter tag | Fresh player can name the bottleneck |
| State-dependent choice | At least two of formation, loadout, directive timing, recovery, securing, and route choice are rational in different states | Counterfactual simulation changes best answer |
| Automate solved labor | A mastered standing order can trigger one routine directive condition | Automation executes only declared condition and reports exceptions |
| Persistent transformation | Anchor restoration changes route/guild/profession/equipment possibility | Save persists transformation and migration preserves it |
| Different next cycle | New rupture or Reweave law invalidates a previously universal routine | Next plan differs for a mechanical reason, not only higher values |
## 10. Onboarding Contract
Tutorial content must follow **safe action -> guided decision -> independent
test**. Tooltips alone do not satisfy a teaching step.
### 10.1 First 20 Minutes
| Target time | Stage | Player action | Failure safety | Understanding check |
|---:|---|---|---|---|
| 0:00-0:30 | Safe action | Tap/click an unstable lane and place the provided frontliner | No cost; invalid slot snaps back with reason | Player can point to front and protected rear |
| 0:30-2:00 | Immediate battle | Start a 25-45 s deterministic training fight | Cannot lose; speed fixed to 1x for first telegraph | Player sees planned protection intercept damage |
| 2:00-4:00 | Guided decision | Choose either a guard item or an interrupt skill against a shown cast | Both win; report explains different cost | Player predicts which event changes |
| 4:00-7:00 | Independent test | Repeat variant without highlighted answer | Free reset; no reward farming | Chosen counter changes first failure point |
| 7:00-10:00 | Route risk | Choose safe anchor or exposed reward detour | Consequence preview remains on commit | Player states what is unsecured |
| 10:00-14:00 | Intervention | Time one prepared directive against a telegraph | Pause-and-target; missed window can be replayed | Player explains why it was or was not legal |
| 14:00-18:00 | Recovery | Spend one Supply on recovery or preserve it and rotate reserve | Either route remains completable | Player identifies opportunity cost |
| 18:00-20:00 | Independent expedition | Select, prepare, and resolve a complete node without prompts | One free training rewind | Player names next objective and one weakness |
### 10.2 Teaching Rules
- Teach no more than one new icon family and one new decision axis per node.
- Suppress a system until it can alter the next decision; never unlock five
menus as a reward dump.
- A tutorial prompt may point at a legal action, but the next encounter must
require recognition without the pointer.
- If the player fails the independent test twice, show the cause chain and let
them enter a no-reward training replay. Do not automatically equip the answer.
- Experienced players may skip dialogue and guided highlights, but must still
pass the independent mechanics test or explicitly open its rule summary.
- Returning players receive a state recap and optional one-node refresher,
never a forced replay of the opening tutorial.
## 11. Session And Campaign Shape
| Scope | Target | End state |
|---|---:|---|
| Battle | 35-120 s; hard systemic cap at 180 s | Cause/result report and immediate next choice |
| Expedition | 8-20 min, four to seven nodes | Anchor bank, voluntary withdrawal, or defeat recovery |
| Typical play session | 20-45 min, one to three expeditions | Safe Guild or anchor save point, explicit next objective |
| Chapter | 2.5-4.25 h, six to nine expeditions plus confrontation | Persistent regional transformation |
| First campaign | 25-35 h across eight chapters | Finite ending and postgame choice |
| Build completion | 60-80 h | All profession branches understood and viable |
| Collection/high difficulty | About 100 h | Catalog and final challenge completion state |
The game may be suspended at any time. A session-ending prompt is never needed
to preserve progress. Short sessions must still end on a meaningful committed
choice, not only an arbitrary stamina or timer boundary.
### 11.1 Pacing Profiles And Decision-Density Contract
These are five observed player-behavior profiles, not difficulty settings. The
same encounter seed, item band, and route rules must support all five without
requiring a different product mode. A profile assertion is measured in
simulation seconds; menu navigation and a confirmation tap do not count as a
decision.
| Profile | Typical behavior | Decisions per 20 min | First meaningful decision | Longest no-decision gap | Completion/session target |
|---|---|---:|---:|---:|---:|
| Normal | Reads previews, changes one or two loadout rules, uses 1x/2x | 6-9 | <= 180 s | <= 150 s | 25-35 h |
| Active | Pauses for telegraphs, spends both Command charges, tests counterfactuals | 10-14 | <= 120 s | <= 120 s | 25-32 h |
| Efficient | Uses mastered standing orders and batch crafting, intervenes on exceptions | 4-7 | <= 180 s at Guild, <= 150 s in an expedition | <= 165 s | 28-35 h |
| Adversarial | Selects elites, presses unsecured Caches, accepts route modifiers | 8-12 | <= 150 s | <= 135 s | 30-35 h including recovery |
| Returning | Reads the recap, makes one deliberate change, then resumes a known route | 3-6 per 12 min | <= 90 s after recap | <= 150 s | 25-35 h in 20-30 min sessions |
The first expedition has a fixed teaching timeline. The timestamps are target
windows, not scripted cutscenes:
| Elapsed time | Required player-facing question | Evidence shown before commit |
|---:|---|---|
| 0:00-0:30 | Which slot protects the exposed rear? | Weave Grid relation and first target line |
| 1:30-3:00 | Which of two counters changes the first major event? | Cast tag, counter tags, predicted event |
| 4:00-6:00 | Is the detour worth unsecured risk? | Reward family, failure disposition, Cache value |
| 7:00-10:00 | Spend a Directive now or preserve it? | Command gain forecast and legal target list |
| 10:00-14:00 | Recover Strain, rotate a reserve, or press? | Supply cost, reserve penalty, next-node pressure |
| 14:00-18:00 | Which learned rule can be automated? | Mastery status and standing-order exception |
| 18:00-20:00 | What is the next bottleneck after the Anchor? | Transformation preview and route counter tags |
During any one expedition, a meaningful choice must occur at least once before
the first battle ends, once after each reward draft, and once before an Anchor
commit. If no state-dependent choice is available for 120 seconds, the route
generator inserts a visible fork, telegraph, recovery trade, or cache decision;
it never inserts a cosmetic prompt. A battle may resolve automatically, but the
result report and next-node preview must expose the next decision within 15
seconds of resolution.
The campaign-hour target is calculated from authored chapter budgets rather than
from forced waiting:
```text
campaign_minutes = sum(chapter_expedition_minutes) +
sum(chapter_confrontation_minutes)
first_campaign_target = 1,500-2,100 minutes (25-35 hours)
```
The economy authority supplies the chapter budgets and reward rates. A balance
run fails if any profile exceeds the 180-second maximum gap, if the first
counter decision occurs after eight minutes, or if a chapter reaches its time
budget only by increasing enemy health or adding unskippable animation.
## 12. Accessibility, Localization, And Input
### 12.1 Accessibility Baseline
Required from the first prototype specification:
- UI scale presets at 100%, 115%, and 130% without clipped functional text;
- safe-area layouts for reference small, standard, and large 16:9 viewports;
- reduced motion, reduced flashes, camera-shake intensity, and hit-stop toggle;
- independent music, ambience, voice, and effects volume plus master mute;
- subtitles/captions for all information-bearing audio with speaker/event tags;
- color-independent lane, rarity, relation, damage, and status encoding;
- high-contrast target and focus outlines;
- hold/toggle alternatives and adjustable long-press timing;
- battle pause and speed controls that never remove event information;
- remappable keyboard/controller actions and a complete touch path;
- screen-reader labels and deterministic focus order for menus; battle events
have a text event log and pauseable inspection path;
- no required rapid taps, simultaneous multi-touch, precision drag, or audio-
only timing cue;
- low-power mode limiting particles and animation sampling without changing
authoritative simulation or decision windows.
### 12.2 Input Semantics
Every platform maps to the same verbs: focus, inspect, compare, move, equip,
confirm, cancel, pause, change speed, select directive, target directive, and
open event log. Dragging is optional convenience; tap-select/tap-destination
must perform every drag action. Destructive or resource-spending actions use a
review state and explicit confirm. Repeating the confirm cannot apply twice.
Touch targets are at least 48x48 logical pixels with 8 logical pixels between
unrelated destructive actions. Hover information has tap/focus equivalents.
Controller focus never enters the battle scene as an invisible cursor.
### 12.3 Localization Rules
- English and Simplified Chinese share semantic message IDs and state tokens.
- No sentence is assembled by concatenating translated fragments.
- Variables use typed placeholders with localized number and plural rules.
- System nouns have one glossary entry; content may not create synonyms for
`Strain`, `Supplies`, `Anchor`, `Directive`, or `Unsecured Cache` casually.
- Layout validation covers English and pseudolocalization at 130% expansion,
and real Simplified Chinese at 130% UI scale.
- Combat abbreviations require expanded accessible names and cannot be the only
way a rule is taught.
- Player-entered names are Unicode-safe, profanity handling is local, and no
generated name is required because all recruits are authored.
## 13. Content Interface And No-Filler Rule
Every content row consumed by this product must declare:
```text
stable_id
localized_name_id
content_type and progression placement
mechanical purpose
state inputs read
authoritative outputs changed
at least two interactions
counter or opportunity cost
presentation silhouette/event requirements
asset, animation, VFX, SFX, and text needs
accessibility communication
validation scenario and expected observable result
```
An item is behavior-changing only if it alters at least one of: legal action,
target selection, timing, formation relationship, resource conversion, status
rule, skill execution, route option, risk exposure, or profession identity. A
conditional percent bonus with no changed decision does not qualify.
An enemy identity must create a distinct preview-to-counter question. A
profession identity must have a distinct target/timing/resource/formation job.
A chapter must combine mechanics in a new way and leave a persistent change.
Rows that differ only by name, art, element color, or scalar fail the package.
## 14. Product Validation Gates
### 14.1 Prototype Comprehension
With at least five uncoached target players:
- at least four state the next objective within three minutes;
- at least four correctly identify a front/rear protection relation;
- at least four explain why one visible threat changes their preparation;
- at least four can state what is lost or retained before committing risk;
- at least three voluntarily begin another expedition or can name a specific
build they want to test.
### 14.2 Decision Quality
- The first meaningful preparation change occurs within three minutes.
- The first visible build interaction occurs within eight minutes.
- The first secure-versus-press decision occurs within twelve minutes.
- A representative 20-minute session contains at least six state-dependent
decisions, excluding confirmations and menu navigation.
- At least two builds clear the same fixed encounter, and each is superior
against a different follow-up threat.
- A single equipment or slot counterfactual changes an observable event in at
least two fixed encounters.
- No profile experiences more than 180 seconds without a meaningful decision.
### 14.3 Battle Trust
- Players can name the earliest lane collapse and its cause after the report.
- Every unexecuted command and invalid directive has one specific logged reason.
- 1x shows every major cast, control, downing, rescue, and directive clearly.
- 4x preserves turning points in the event log and never shortens input windows
in simulation time.
- Replaying from the same state, seed, and command timestamps produces the same
authoritative outcome.
### 14.4 Open Human Gates
All comprehension targets above are requirements for later tests, not machine-
granted acceptance. Human fun, visual quality, listening quality, tactile
quality, willingness to continue, physical-device behavior, packaging, and
release remain open until the appropriate Owner or device evidence exists.
## 15. Design Questions Deliberately Closed
| Question | Decision |
|---|---|
| Is combat fully manual? | No. Loadouts and formation automate actions; at most two directives add timed agency. |
| Can characters permanently die in the first campaign? | No. Defeat causes route loss and temporary Strain, not deletion. |
| Is profession determined by weapon? | No. Profession is learned progression; equipment modifies execution. |
| Can a player buy or grind around a threat? | They can broaden options, but baseline balance assumes no mandatory grind and difficulty never sells power. |
| Does closing the game generate progress? | No. Offline gameplay progression is exactly zero. |
| Is postgame only endless scaling? | No. It has finite mastery, collection, and high-difficulty completion states. |
| Are routine fights always manual? | No. Mastered standing orders may automate declared labor, while new rules retain strategic decisions. |
| Does a stronger item automatically replace a weaker one? | No. Behavior, timing, tags, and formation can make a lower-tier item correct. |
| Can presentation hide exact mechanics for drama? | Never when the mechanic affects a decision or failure. |
## 16. Acceptance Checklist
- [ ] Product fantasy is recognizable without reference-game context.
- [ ] Every system contributes to preparation, diagnosis, risk, transformation,
or a different next cycle.
- [ ] The fixed 30/12/24/100/8/320 envelope remains unchanged.
- [ ] Manual, automated, bottleneck, choice, mastery, and transformation stages
are all represented.
- [ ] First campaign, build completion, and collection targets are simulated.
- [ ] Premium, offline, accessibility, localization, and input boundaries are
represented in screen/prototype specifications.
- [ ] Content rows conform to the no-filler schema.
- [ ] Human and release gates remain explicitly open.
docs/product/SAVE_AND_FAILURE_CONTRACT.md
+532
View File
@@ -0,0 +1,532 @@
# Aetherbound Guild: Save And Failure Contract
> Authority: persistence boundaries, transaction idempotency, interruption,
> backup, migration, corruption handling, duplicate protection, clock behavior,
> defeat consequences, and deterministic recovery.
>
> Revision: design-batch-01 / 2026-08-10
>
> [GAME_PRODUCT_CONTRACT.md](GAME_PRODUCT_CONTRACT.md) owns the player promise.
> [SYSTEMS_AND_BATTLE.md](SYSTEMS_AND_BATTLE.md) owns encounter rules.
> [ECONOMY_AND_BALANCE.md](ECONOMY_AND_BALANCE.md) owns the value and multiplier
> formulas used here. This document has priority whenever a result is ambiguous
> because preserving an authoritative committed state is more important than a
> presentation sequence.
## 1. Persistence Invariants
1. A confirmed action is applied exactly once or not at all. There is no state
in which its cost is applied without its declared result.
2. Closing, suspending, crashing, losing power, changing devices, or retrying a
request cannot duplicate a reward, consume a second resource, reroll a route,
or change a deterministic battle outcome.
3. The latest valid local commit remains playable offline. Cloud and platform
services are optional copies, never gameplay authority.
4. Offline gameplay progress is exactly zero. There are no real-time rewards,
construction clocks, energy recovery, expedition simulation, or daily claims.
5. A first-campaign defeat can lose route opportunity and Unsecured Cache value,
and can add Strain, but cannot delete a named adventurer, a banked item, a
profession unlock, Mastery, Anchor restoration, or the save slot.
6. Migration is copy-first and reversible. A new build never rewrites the only
known-valid save.
7. Recovery is deterministic and inspectable. When data cannot be trusted, the
game restores the newest valid backup and identifies the discarded boundary.
8. Save, delete, overwrite, import, cloud-conflict, and risky recovery actions
are fully operable by touch, mouse, keyboard, and controller and are never
color-only or hold-only.
## 2. Save Topology And Envelope
The product supports three independent campaign slots. Each slot has one active
commit, three rotating safe backups, one latest Anchor checkpoint, one optional
pre-migration copy, and a bounded operation journal.
```text
profile_save
profile_schema_version
settings_revision, language, accessibility, input mappings
slot_index[]
platform_entitlement_cache (non-authoritative)
campaign_slot
slot_id, campaign_id, lineage_id
save_schema_version, ruleset_version, content_revision
commit_id, parent_commit_id, commit_sequence
created_at_wall_clock, last_seen_wall_clock (display only)
deterministic_generation_root_seed
difficulty_contract, selected_reweave_laws
campaign_state, guild_state, roster_state, inventory_state
expedition_state or null
encounter_state or null
operation_journal, achievement_outbox
payload_sha256, envelope_crc32
```
`campaign_id`, `lineage_id`, operation IDs, stable content IDs, and seeds are
128-bit values rendered as lowercase hexadecimal. `commit_sequence` is a local
monotonic unsigned integer. Wall-clock fields are never used to resolve game
rules or conflict winners.
The envelope has two integrity checks: CRC32 catches incomplete media writes;
SHA-256 covers the canonical payload and catches any other unexpected change.
Neither is treated as anti-cheat or security. The game must not refuse an
offline save because it lacks a server signature.
## 3. Versioning And Compatibility
`save_schema_version`, `ruleset_version`, and `content_revision` serve different
purposes:
| Field | Changes when | Compatibility rule |
|---|---|---|
| `save_schema_version` | Field layout or serialization changes | Requires an ordered migration step |
| `ruleset_version` | Formula, targeting, economy, or failure behavior changes | Existing encounters resume under their stored ruleset until a safe boundary |
| `content_revision` | Stable content rows or localized resources change | Stable IDs must resolve or enter legacy recovery |
A battle or encounter transaction always finishes under the stored
`ruleset_version`. A newer ruleset becomes active only at the Guild or after an
Anchor commit, before a new route node is generated. The migration UI states
that the next expedition uses revised rules; it never changes a battle already
in progress.
Supported compatibility is current schema plus the previous three shipped
schemas. Older saves may still be migrated by a tested chain, but lack of such a
chain is a blocking error with an export option, not permission to reset.
## 4. Transaction And Operation Model
### 4.1 Operation Identity
Every state-changing player or system action has a stable `operation_id` scoped
to the campaign:
```text
operation_id = hash(campaign_id, commit_sequence_at_intent,
operation_kind, source_stable_id, local_nonce)
```
The operation journal stores:
```text
operation_id, operation_kind, intent_hash
status: pending | applied | rejected
pre_commit_id, result_commit_id
cost_delta, result_delta, rejection_reason
created_tick or route_sequence
```
The same `operation_id` with the same `intent_hash` returns the stored result.
The same ID with a different intent is rejected as `operation_id_conflict` and
applies nothing. Journal entries remain until two later Anchor checkpoints and
then compact into an immutable applied-ID set. The applied-ID set is retained
for the entire campaign slot.
### 4.2 Atomic Commit Procedure
Every transaction follows this order:
1. Validate the current commit, legal state, cost, target, and intent hash.
2. If the operation is already applied, return its recorded result.
3. Build the complete next payload in memory; do not mutate the active payload.
4. Add the pending operation and all cost/result deltas to that payload.
5. Validate schema, content references, resource non-negativity, item ownership,
roster uniqueness, route ancestry, and encounter hash.
6. Serialize to a new file, write checksum, flush file and containing directory,
then atomically replace the active pointer.
7. Mark the operation applied in the same new commit or an immediate child
commit. On recovery, a `pending` operation with an applied delta is finalized;
one without a complete delta is discarded.
8. Rotate backups only after the new active commit reads back and validates.
An animation, sound, platform achievement, or cloud upload occurs after step 8.
It cannot determine whether the operation succeeded.
### 4.3 Transaction Boundaries
| Action | Commit point | Duplicate response |
|---|---|---|
| Equip/move/change loadout | Confirmed legal state at Guild/Prepare | Return already-equipped result |
| Buy/recruit/craft/upgrade/salvage | Cost and result commit together | Return receipt; do not spend again |
| Reveal/choose route node | Node seed and choice commit before transition | Reopen identical preview/node |
| Start encounter | Initial encounter snapshot and combat seed commit | Resume same countdown |
| Fire Directive | Accepted target and simulation tick commit | One charge and one event only |
| End encounter | Objective outcome and report commit | Reopen same report |
| Claim reward | Chosen stable ID and Cache delta commit | Return same claimed card |
| Secure Cache/Anchor | Cache removal and banked ledger commit together | Return same bank receipt |
| Change difficulty/Reweave law | Guild-only confirmed commit | Reopen selected contract |
## 5. Encounter Lifecycle And Save Points
The encounter state machine is:
```text
preview -> prepared -> committed -> countdown -> resolving
-> outcome_locked -> report -> reward_pending -> reward_applied
-> route_committed
```
- `preview`: leaving changes nothing. The preview seed and visible choices are
already stored, so reopening cannot reroll them.
- `prepared`: loadout edits are saved, but the encounter may still be cancelled.
- `committed`: battle seed, company snapshot, difficulty, and failure exposure
are fixed. No equipment/profession edits are accepted.
- `resolving`: deterministic snapshots and a command journal support resume.
- `outcome_locked`: victory, defeat, or retreat predicate is immutable.
- `report`: presentation may be skipped without changing rewards.
- `reward_pending`: cards are fixed; no reward is owned yet.
- `reward_applied`: the chosen reward exists once in the Unsecured Cache or bank.
- `route_committed`: the next route state owns the result; encounter detail may
be compacted after the next Anchor backup.
Safe save points occur after every confirmed Guild action, route-node reveal,
node commit, accepted Directive, outcome lock, reward claim, Cache operation,
and Anchor restoration. The game also writes a battle resume snapshot every ten
simulation ticks (one simulation second). These snapshots are bounded to the
current encounter and are not exposed as manual save-scumming slots.
`Save and Quit` completes the current batch and writes the same active commit;
it does not create a branch, reroll point, or separate manual-save lineage.
## 6. Battle Interruption And Deterministic Resume
An encounter resume snapshot stores:
```text
encounter_instance_id, ruleset_version, content_revision
root combat seed and per-stream draw indices
simulation_tick, fixed-point unit state, slots, statuses, threat
event queue, cooldowns, readiness, Aether, Command state
objective/phase state, Fracture Clock
accepted command journal through simulation_tick
snapshot_hash, previous_snapshot_hash
```
On normal suspend, the game completes the current 0.1-second batch, writes a
snapshot, then acknowledges suspend. If the process is killed first, recovery
loads the newest valid snapshot and replays accepted commands from the previous
valid snapshot. Replayed commands carry their original ticks and operation IDs.
Recovery never substitutes current wall-clock time. A battle suspended for a
week resumes at the same simulation tick and next event. Display interpolation,
camera, particles, and non-authoritative audio restart from the recovered state.
If the latest snapshot is corrupt:
1. validate snapshots newest to oldest;
2. load the newest valid snapshot with a matching encounter and ruleset;
3. replay journaled commands and deterministic streams to the last committed
tick;
4. compare the reconstructed state hash with the stored checkpoint hash;
5. if it matches, resume and record `snapshot_recovered`;
6. if no snapshot matches, roll back to `committed` and restart the identical
encounter seed with the same loadout, automatically replay every valid
journaled command at its original tick, and resume after the last such tick
with no cost/reward changes.
Restarting from `committed` is a recovery action, not a player-selectable retry.
It is unavailable after an outcome has been locked.
## 7. Duplicate Action And Reward Protection
### 7.1 Input Debounce Is Not Authority
UI debounce may prevent repeated taps, but correctness relies on operation IDs.
Touch double-taps, controller repeat, network retry, OS lifecycle replay, and
cloud reconciliation all return the first committed result.
For a Directive:
```text
accept(command_id, target, tick):
if command_id in applied_ids: return stored_result
if charge < 1 or target illegal: reject without cost
otherwise spend 1 charge and enqueue exactly one command at tick+1
```
For a reward claim:
```text
claim(reward_operation_id, card_id, disposition):
verify card_id belongs to fixed draft
verify operation has no applied result
remove draft, add exactly one Cache/bank entry, append applied ID
commit all fields atomically
```
No inventory repair routine may create a second item to compensate for a
display problem. It first resolves ownership from the operation journal.
### 7.2 Achievement And Platform Outbox
Achievements are derived from committed gameplay facts. When offline, up to 100
idempotent platform events are queued. If the bound is reached, older events are
re-derived from campaign facts later; gameplay never blocks and no reward is
lost. Platform success or failure cannot modify Crowns, items, XP, Mastery,
route state, or completion state.
## 8. Backup, Corruption, And Recovery
### 8.1 Backup Rotation
Each campaign slot keeps:
- `active`: newest fully validated commit;
- `backup_1..3`: three prior safe commits at distinct transaction boundaries;
- `anchor_checkpoint`: latest valid Anchor commit, retained until a newer Anchor;
- `pre_migration`: original file before a schema/ruleset migration;
- `quarantine`: corrupt bytes and a diagnostic manifest, never auto-deleted.
Backups are written only inside the slot's explicit storage directory. A failed
rotation leaves the active file and previous backups untouched. Storage pressure
first removes old diagnostic logs, never the active or latest Anchor backup.
### 8.2 Validation Order
On load, validate in this order:
1. envelope parse and size bounds;
2. CRC32 and SHA-256;
3. schema and required fields;
4. campaign/lineage/parent commit relationships;
5. resource bounds and nonnegative balances;
6. stable content IDs and item ownership uniqueness;
7. roster and profession topology;
8. expedition route ancestry and committed node;
9. encounter snapshot and operation-journal consistency.
A presentation preference error falls back to defaults without touching the
campaign. A gameplay-state error invokes backup recovery. The game never labels
a save corrupt merely because optional cloud or platform services are offline.
### 8.3 Recovery Result
When recovery selects a backup, the player sees:
- which slot was affected;
- the recovered boundary (`Guild`, `Anchor`, `node`, `battle snapshot`, or
`report`);
- the number and kinds of operations after that boundary that could not be
verified;
- options to continue from the recovered state, inspect technical details, or
export a diagnostic copy;
- an explicit statement that the quarantined file was preserved.
The default focus is `Continue recovered save`, not delete or overwrite. A
recovery message may not claim that all progress was preserved unless the
active and reconstructed commit hashes match.
## 9. Migration Contract
Migration runs only at startup or the Guild, never during an expedition or
encounter. The procedure is:
1. Validate and preserve the original as `pre_migration`.
2. Build a migration plan of adjacent version steps; skipping a step is illegal.
3. Resolve stable content-ID mappings and list any legacy rows.
4. Apply each pure migration function to a copy.
5. Validate every invariant and recompute derived values from source fields.
6. Write a new lineage child commit with migration IDs and old/new hashes.
7. Read back, then switch the active pointer. Preserve the old copy until two
valid Anchor commits under the new version.
Migrations never generate random values. If a removed item ID has no direct
replacement, it becomes a `legacy_sealed_item` retaining original stable ID,
band, tier, and salvage value. It cannot be equipped; at the Guild, the player
chooses one of two deterministic same-band replacements or keeps it sealed for
a future migration. There is no silent auto-equip or value loss.
If any step fails, the new copy is discarded, the original remains active under
its last supported ruleset when possible, and the slot is marked
`migration_blocked`. Other slots and settings remain usable.
## 10. Local, Cloud, And Multi-Device Conflict
Cloud is an optional transport of complete validated commits. It does not merge
inventories, rewards, route nodes, or operation journals. A cloud upload carries
`campaign_id`, `lineage_id`, `commit_id`, `parent_commit_id`, and sequence.
| Relationship | Resolution |
|---|---|
| Same commit | No action |
| Local is ancestor of cloud | Offer cloud as newer; retain local backup |
| Cloud is ancestor of local | Keep local; queue upload |
| Different lineage/campaign | Offer to import cloud into an empty/duplicated slot |
| Same lineage, divergent descendants | Never auto-merge; show both boundaries and require keep local, keep cloud, or duplicate one |
Conflict choices use commit boundary, chapter, play duration, Anchor, and last
known objective. Wall-clock `newer` is display context only. The default is
`Cancel and inspect`, and no option deletes the unchosen copy until the selected
copy has been validated and backed up.
## 11. Clock Rollback And Offline Behavior
All gameplay clocks are simulation ticks or monotonic session duration. Wall
clock is used only for human-readable save dates and diagnostics.
On startup:
```text
wall_delta = current_wall_clock - last_seen_wall_clock
if wall_delta < -300 seconds or wall_delta > 180 days:
record clock_anomaly for diagnostics
do not change gameplay state or deny play
```
Changing the device clock cannot grant or remove Crowns, Supplies, shop offers,
route nodes, XP, Mastery, unlocks, or platform achievements. A queued platform
event with a timestamp outside service limits remains derived from committed
facts and is retried without a gameplay reward.
While the game is closed, expedition and encounter time advances by exactly
zero ticks. On return, the player receives a compact recap of the saved state,
not an offline income panel. Optional platform uploads are bounded background
work and stop cleanly without blocking local commits.
## 12. Failure State Model
Failure is classified before consequences are calculated:
| Failure kind | Predicate | Earliest committed boundary | Outcome |
|---|---|---|---|
| Encounter defeat | All deployed units Lost/Downed with no legal rescue, objective fails, or Fracture reaches 180 s | `outcome_locked` | Apply difficulty defeat transaction |
| Voluntary battle retreat | Three-second retreat channel completes after its legal time | `outcome_locked` | Apply retreat transaction |
| Route withdrawal | Player confirms at noncombat node | Route commit | Bank declared fraction, end expedition |
| Hazard failure | Authored visible condition fails | Node result | Apply declared Supply/Strain/Cache delta once |
| Invalid action | State/target/cost precondition fails | No commit | Spend nothing; return one reason |
| Process interruption | App is suspended/killed/crashes | Last valid save point | Resume/reconstruct; not a gameplay failure |
| Save corruption | Active commit fails validation | Last valid backup | Recover/quarantine; not a gameplay failure |
## 13. Defeat, Retreat, Strain, And Cache Consequences
### 13.1 Cache Loss Algorithm
Every Unsecured Cache line stores `cache_line_id`, stable reward ID, quantity,
`risk_value`, and acceptance sequence. Before node commitment, the preview shows
the exact loss set for the active difficulty.
For loss fraction `P`:
```text
loss_target = floor(total_cache_risk_value * P)
order cache lines by acceptance_sequence descending, then cache_line_id
remove/split lines until removed risk value >= loss_target
never remove a banked line or more than the Unsecured Cache owns
```
Crowns and stackable materials may split exactly. An indivisible item that would
overshoot remains in the Cache and the algorithm continues to the next line;
if no line can satisfy the remainder, the actual loss is smaller and is shown.
There is no random loss roll.
### 13.2 Difficulty Transactions
| Contract | Defeat | Battle retreat | Noncombat withdrawal |
|---|---|---|---|
| Wayfinder | Lose 25% Cache, consume up to 1 Supply, +1 Strain to each Downed/Lost unit (at most two affected units) | Lose 15% Cache, consume 1 Supply, +1 Strain to units Lost before channel | Bank 75% Cache, discard remainder, end expedition |
| Stormbound | Lose 50% Cache, consume up to 2 Supplies, +1 Strain to every Downed/Lost deployed unit | Lose 30% Cache, consume 2 Supplies, +1 Strain to Lost units | Bank 50% Cache, discard remainder, end expedition |
| Iron Oath | Lose 100% Cache, consume all Supplies, +2 Strain to Lost units, close current route | Lose 60% Cache, consume all but 1 Supply, +1 Strain to all deployed units | Bank 25% Cache, discard remainder, end expedition |
After the transaction, if at least one Supply remains and at least one deployed
or reserve adventurer has fewer than three Strain, the party returns to the last
Anchor with the revealed graph intact except where Iron Oath closes the current
route. Otherwise the expedition ends at the Guild. Banked state, chapter
restorations, roster, inventory, XP, and Mastery remain intact.
For a noncombat withdrawal, resolve the Cache bank/discard fraction first, then
apply the unused-Supplies Crown conversion from the economy authority in the
same expedition-close operation. Defeat never receives that conversion.
On victory, an adventurer whose Rescue Window expired gains one Strain as stated
in the systems authority. A rescued adventurer gains none from that Downed event.
Strain caps at three; overflow is discarded and logged. At three Strain the
adventurer cannot deploy but can still be inspected, respeced, equipped, and
recovered. One Supply at a Camp/Anchor clears one Strain from one adventurer;
returning to the Guild clears all Strain without cost and ends the expedition.
### 13.3 Recovery Choice
The Recovery state shows:
1. outcome cause and first preventable event;
2. exact Cache lines lost, banked, and retained;
3. each adventurer's Strain before/after;
4. Supplies before/after and route position;
5. three legal next actions: reconfigure at Anchor, train against the same seed
with no reward, or end the expedition at the Guild.
It never offers a paid continue, random reroll, automatic best-loadout button,
or destructive character replacement. The same-seed training replay is not a
rollback: it is a separate no-reward simulation whose result cannot alter the
committed failure.
## 14. Confirmation, Delete, And Reset Boundaries
The following actions require a review state with exact effects, then a separate
confirm input: difficulty increase, Reweave-law activation, route withdrawal,
Cache discard, salvage of an unlocked item, cloud conflict resolution, migration
fallback, campaign-slot overwrite, and campaign-slot delete.
Deleting a campaign slot requires selecting the exact slot name and confirming
again after the summary. The active save moves to a recoverable local trash area
for seven successful launches or until the player explicitly empties it. A
profile-wide reset additionally requires entering a displayed localized phrase;
controller and touch users can select the phrase from a two-step dialog rather
than type it. No cancel/default focus may point at delete.
An accepted confirm receives an operation ID. Repeating the input returns the
first result and cannot delete or spend twice.
## 15. Accessibility, Localization, And Input Requirements
- Save state is communicated by text and icon, never only color or a spinning
indicator. `Saving`, `Saved`, `Recovered`, `Conflict`, and `Blocked` have
distinct accessible labels.
- Closing during `Saving` is legal; the previous active commit remains valid.
- Every recovery/conflict dialog supports 130% UI scale, screen-reader order,
keyboard/controller focus, and a complete tap-select path.
- Technical IDs are hidden by default but available in an inspectable details
panel and copyable/exportable diagnostic manifest.
- Localized messages use semantic IDs and typed values. They never concatenate
amounts, item names, operation kinds, or recovery boundaries into fragments.
- Numeric loss previews use localized formatting and also list affected cache
rows, so a percentage is not the only explanation.
- Haptics and audio may confirm a commit but cannot be the only saved/failed cue.
- A controller disconnect, focus loss, or input-device change pauses target
selection and spends nothing until a new confirm is accepted.
## 16. Required Recovery And Failure Test Matrix
| Test | Interruption/fault point | Expected invariant |
|---|---|---|
| Equip commit | After cost validation, before atomic pointer switch | Old loadout or complete new loadout; never partial |
| Purchase duplicate | Same operation ID delivered twice | One cost and one item |
| Directive duplicate | Same command ID at same tick twice | One charge and one event |
| Battle suspend | During cast at tick 417 | Resume at tick 417 boundary; identical final hash |
| Battle crash | After snapshot write, before pointer update | Use prior valid snapshot and journal; identical final hash |
| Outcome crash | After victory predicate, before report animation | Reopen same victory report and fixed rewards |
| Reward crash | After card choice, before screen transition | Exactly one Cache/bank line; same card on reload |
| Anchor crash | During Cache banking | Entire Cache banked once or still unsecured; no split duplicate |
| Clock rollback | Device clock moves back 24 hours | Diagnostic only; zero gameplay change |
| Seven-day offline | Close mid-expedition and return | Zero tick/resource progress; recap and resume |
| Active save corrupt | Break checksum | Load newest valid backup, quarantine active, show boundary |
| All battle snapshots corrupt | Valid committed start and command journal remain | Restart identical seed/loadout, replay commands at original ticks, no cost/reward change |
| Migration failure | Invalid stable-ID mapping | Original stays active; new copy discarded; export offered |
| Cloud divergence | Local and cloud share parent but differ | No merge/overwrite; keep/duplicate choice |
| Wayfinder defeat | 200 Cache risk value, two Lost units, 4 Supplies | Lose 50 value, spend 1 Supply, each gets 1 Strain |
| Stormbound withdrawal | 200 Cache at noncombat node | Bank 100 value, discard 100, end expedition |
| Iron Oath defeat | Any positive Cache and Supplies | Lose all Cache/Supplies, route closes, roster remains |
## 17. Acceptance Checklist
- [ ] Schema, ruleset, content, lineage, commit, and operation versions are
separated and migration paths are copy-first.
- [ ] Every resource/action/reward transaction is atomic and idempotent.
- [ ] Battle suspension and crash recovery reproduce the authoritative hash.
- [ ] Duplicate input, reward claim, platform retry, and cloud conflict cannot
duplicate or erase gameplay state.
- [ ] Active, backup, Anchor, pre-migration, and quarantine behavior is explicit.
- [ ] Clock rollback and bounded offline behavior create zero gameplay progress.
- [ ] Wayfinder, Stormbound, and Iron Oath failure consequences match the economy
authority and never delete a first-campaign adventurer or banked asset.
- [ ] Recovery, conflict, overwrite, reset, and delete flows meet input,
accessibility, localization, and confirmation requirements.
docs/product/SYSTEMS_AND_BATTLE.md
+930
View File
@@ -0,0 +1,930 @@
# Aetherbound Guild: Systems And Battle Authority
> Authority: canonical gameplay state, expedition flow, formation, auto-battle,
> professions, skills, equipment hooks, tactical intervention, and diagnostic
> behavior.
>
> Revision: design-batch-01 / 2026-08-10
>
> Product intent is defined in
> [GAME_PRODUCT_CONTRACT.md](GAME_PRODUCT_CONTRACT.md). Numeric economy and
> pacing are defined in [ECONOMY_AND_BALANCE.md](ECONOMY_AND_BALANCE.md).
> Commit, interruption, defeat, and recovery semantics are defined in
> [SAVE_AND_FAILURE_CONTRACT.md](SAVE_AND_FAILURE_CONTRACT.md).
## 1. Non-Negotiable System Invariants
1. The active company contains zero to six deployed adventurers on a fixed
three-lane by two-rank Weave Grid. An expedition may carry up to two reserves.
2. Adventurers do not freely wander away from assigned formation anchors.
Movement, displacement, and slot changes are discrete and explainable.
3. The authoritative simulation advances at fixed 0.1-second ticks. Display
speed and frame rate do not alter outcomes.
4. Normal attacks never miss through hidden random evasion. Avoidance is an
explicit status, charge, block, range, or line rule.
5. Every enemy major action is declared in preview and telegraphed in battle.
Immunity and targeting exceptions are visible before commitment.
6. The player prepares two tactical directives and may spend at most two
Command charges in one encounter.
7. The same start state, content revision, seed, and tick-stamped player
commands produce the same authoritative result.
8. Every rejected or unexecuted action has exactly one machine-readable reason.
9. Combat power cannot grant more than 95% total damage reduction, 60% generic
critical chance, 50% max-HP barrier, or permanent hard control.
10. A normal campaign character can be Downed and gain Strain but is not
permanently deleted.
## 2. Authoritative State Model
```text
profile
settings, accessibility, language, input mappings
entitlements and platform-service cache (never gameplay authority)
campaign slot
campaign_id, ruleset_version, difficulty
chapter/anchor/world transformations
guild rank, roster, learned professions, mastery
inventory, currencies, catalog, achievements
deterministic generation root seed
expedition
expedition_id, chapter, route seed and revealed graph
deployed company and reserves
supplies, strain snapshot, unsecured cache
current anchor, committed node, standing order
encounter transaction
encounter_instance_id, phase, combat seed
Weave Grid, units, stats, cooldowns, statuses, threat
event queue, tick, directives, Command state
outcome and idempotent reward operation IDs
presentation only
camera, animation interpolation, particles, selected panel,
expanded tooltip, pointer position, non-authoritative sound state
```
Presentation may interpolate but may never author damage, movement, targeting,
reward, timing, or save state. All numeric combat calculations use integer
fixed-point values at 1/100 precision and round only at the boundaries stated
below.
## 3. Weave Grid Geometry
### 3.1 Slots
All standard encounters use six allied and six enemy anchors:
```text
ALLIED ENEMY
R1 ---- F1 <lane 1> EF1 ---- ER1
R2 ---- F2 <lane 2> EF2 ---- ER2
R3 ---- F3 <lane 3> EF3 ---- ER3
R = rear rank, F = front rank
```
The screen may render depth and hand-drawn motion, but these slot IDs remain
authoritative. Slot adjacency is orthogonal:
- same-rank neighboring lanes: `F1-F2`, `F2-F3`, `R1-R2`, `R2-R3`;
- same-lane front/rear links: `F1-R1`, `F2-R2`, `F3-R3`;
- diagonals are not adjacent unless a skill explicitly declares diagonal reach;
- lane distance is `abs(source_lane - target_lane)`;
- rank distance is zero within a rank and one across ranks.
Large enemies may occupy two declared adjacent enemy slots. They have one unit
ID, one health pool, and a primary slot for tie-breaking. A large unit must
declare which occupied lanes it threatens. No content may visually occupy
multiple slots while mechanically using only an undisclosed one.
### 3.2 Front Protection
A living, non-Downed front unit protects the rear unit in the same lane unless
the protector has `Broken`, is displaced out of the link, or the incoming skill
has `bypass_front`. Protection has three effects:
1. standard melee cannot target the protected rear unit;
2. standard ranged attacks against that rear unit receive `-120` Target Score;
3. `interceptable` attacks transfer 50% of post-mitigation damage to the front
protector before barrier absorption; the attack preview shows this split.
The transfer percentage can be modified only by an explicit skill or item and
is clamped to 0%-80%. Transfer cannot recursively trigger another intercept.
If no rear unit exists, the front unit still holds the lane but gains no hidden
bonus.
### 3.3 Displacement And Slot Changes
Movement is a transaction between slots, not free pathfinding:
- `shift`: move to an empty orthogonally adjacent allied slot;
- `swap`: exchange two living allied units in adjacent slots;
- `push`: move target one rank away from source, then one lane away according
to the skill's declared direction if rank movement is impossible;
- `pull`: reverse of push;
- `invade`: an enemy-only declared move into an empty allied front slot;
- `return`: move an invader to its stored enemy anchor when the effect ends.
If a forced destination is occupied or outside the grid, movement fails and
the target takes `Stagger = 10 + 0.10 * source Physical Power` before defense.
Forced movement cannot chain more than once per tick. `Anchored` rejects forced
movement but not voluntary swap. Every rejection logs `ANCHORED`, `OCCUPIED`,
`OUT_OF_GRID`, `DOWNED`, `ROOTED`, or `CAST_LOCK`.
## 4. Encounter Lifecycle
| Phase | Legal player/system actions | Commit boundary |
|---|---|---|
| Preview | Inspect threats, rewards, objective, Fracture Clock, enemy slots | No cost; generated preview is stable |
| Prepare | Deploy, equip, set skills/AI priorities, select two directives | Confirm creates immutable pre-battle snapshot |
| Countdown | Three simulation seconds; inspect and pause allowed | Formation changes locked |
| Resolve | Auto actions and up to two directives | Tick-stamped events journaled |
| Outcome locked | Victory, defeat, retreat, or scripted objective result | Combat state cannot be changed |
| Diagnose | Compare predicted/actual targets, causes, contribution | No reward applied by viewing/skipping |
| Reward review | Choose reward and cache disposition | Choice has one operation ID |
| Finalized | Apply result once and return to route/recovery | Encounter transaction archived |
Leaving the preview never rerolls it. Leaving preparation after confirmation
returns to the same immutable snapshot and requires explicit cancel to abandon
the committed node. Save rules for each phase are in the save authority.
## 5. Unit Statistics
### 5.1 Primary Attributes
Every adventurer has five nonnegative integer attributes. Enemy data may define
equivalent derived values directly.
| Attribute | Primary role | Does not do |
|---|---|---|
| Might | Physical Power, physical Guard contribution | Determine profession or hidden carry weight |
| Finesse | Tempo, critical precision, initiative | Grant passive random dodge |
| Insight | Arcane Power, status Potency | Bypass visible Ward rules |
| Vigor | Max HP, Guard, stagger resistance | Create automatic regeneration |
| Resolve | Ward, healing contribution, status Tenacity | Make a unit silently control-immune |
Character bases, level growth, profession modifiers, and equipment bonuses are
summed before derived calculations. A primary attribute is clamped to 0-250 in
the first campaign and 0-400 in Reweave. Values outside the cap are shown as
overflow and do not affect combat.
### 5.2 Derived Statistics
For level `L` (1-50 first campaign; postgame cap 70), use:
```text
PhysicalPower = WeaponPower + 2.00*Might + 0.60*Finesse
ArcanePower = FocusPower + 2.00*Insight + 0.60*Resolve
HealingPower = FocusPower + 1.30*Insight + 1.30*Resolve
MaxHP = JobBaseHP + 12*L + 10*Vigor
Guard = ArmorGuard + 1.25*Vigor + 0.75*Might
Ward = ArmorWard + 1.25*Resolve + 0.75*Insight
Potency = Insight + 0.50*Finesse + flat_potency
Tenacity = Resolve + 0.50*Vigor + flat_tenacity
Tempo = clamp(JobBaseTempo * (1 + Finesse/(Finesse+250))
+ flat_tempo, 20, 100)
Initiative = clamp(JobBaseInitiative + 0.25*Finesse
+ flat_initiative, 0, 95)
```
`WeaponPower`, `FocusPower`, `ArmorGuard`, and `ArmorWard` are generic budget
terms; an item may supply more than one. Jobs define `JobBaseHP` in 180-420,
`JobBaseTempo` in 25-50, and `JobBaseInitiative` in 0-50. Content outside these
ranges needs a documented system exception and a fixed validation encounter.
Derived values are calculated at battle start and on explicit stat changes.
Max HP changes preserve current HP percentage, rounded down, unless an effect
states that it heals. No equipment swap is legal during Resolve.
## 6. Deterministic Time, Events, And Randomness
### 6.1 Fixed Tick
The simulation tick is exactly 100 milliseconds. Display frames sample the
latest completed state. At each tick, event priorities are:
1. lifecycle commands (pause/resume/retreat) and accepted player directives;
2. status expiry, periodic effects, and resource drains;
3. cast/channel completions;
4. ready automatic actions;
5. movement and displacement;
6. simultaneous damage/heal/barrier application within each priority batch;
7. Downed, objective, phase-transition, and Command-gain checks;
8. readiness, cooldown, duration, and telegraph clocks advance.
Events at the same priority read the same pre-batch state and apply their
numeric outputs together. A unit alive at the start of a simultaneous batch
completes its already-scheduled event even if that batch Downs it. Ties use
stable unit ID only for nonnumeric presentation order and conflicting movement;
combat totals do not gain an ID-order advantage.
### 6.2 Seeded Random Streams
Each encounter stores a 128-bit root seed and separate labeled streams:
```text
target_tie, critical, status_apply, reward, route_event
```
Adding a reward draw must not shift combat draws. Draws include stream name,
event sequence, and content stable ID in the journal. There is no damage
variance. Random outcomes are limited to declared critical checks, declared
status application below 100%, equal-score target ties, and generated content
choices. Preview shows the bounded chance or deterministic outcome.
## 7. Readiness, Skills, And Action Timing
Each unit has Readiness from 0-99.99. At battle start it equals Initiative.
Each tick:
```text
Readiness += Tempo * 0.1
```
At `Readiness >= 100`, AI selects one legal action. The selected action reserves
its target, subtracts 100 Readiness, and begins its wind-up/cast. Any overflow
is retained, capped at 50. If no action is legal, the unit waits one tick and
does not spend Readiness.
| Timing field | Boundary |
|---|---|
| Wind-up | 0.1-1.5 s; interruptible only if tagged |
| Cast/channel | 0.5-4.0 s; major casts require telegraph contract |
| Recovery | 0-2.0 s during which Readiness can fill but no action starts |
| Cooldown | 0-30 s, advanced every simulation tick |
| Global lock | At most 0.3 s and only for preventing duplicate starts |
Auto AI evaluates actions in the player-authored four-row priority list, then
uses the fixed basic action. Each priority row contains `skill`, `condition`,
and `target policy`. Conditions may read only currently visible authoritative
state: HP bands, barrier, status, lane, protected/exposed, ally count, enemy
count, cast tag, phase, Aether, and cooldown. They may not inspect future RNG.
## 8. Targeting, Threat, And Aggro
### 8.1 Candidate Filter
An action first constructs legal candidates from its row data:
- side: ally, enemy, self, slot, or all;
- reach: same lane, adjacent lane, any lane, front, rear, or occupied slots;
- protection: obey front, ranged penalty, bypass front, or interceptable;
- state: living, Downed, damaged, cast-active, status-present, and exclusions;
- maximum targets and deterministic area shape.
If the reserved target becomes illegal before completion, the skill follows its
declared `retarget`, `fizzle`, or `ground_resolve` policy. This policy appears in
the tooltip. A fizzle refunds 50% of cooldown and all unspent profession
resource unless content explicitly declares a visible nonrefundable wager.
### 8.2 Threat Meter
Each unit has Threat `T`, initialized to the profession's `BaseThreat` in
0-100. It changes after effective outcomes:
```text
damage threat = 40 * effective_damage / target_MaxHP
support threat = 25 * (effective_heal + effective_barrier) / ally_MaxHP
control threat = 12 * effective_control_seconds
```
Threat gains are summed per tick, capped at +60 per tick, and decay 5 per
simulation second toward BaseThreat. Overkill, overheal, and wasted barrier add
zero. An effect may add taunt threat explicitly, capped at +300.
### 8.3 Target Score
For each legal candidate, standard hostile AI computes:
```text
TargetScore = T
+ lane_affinity
+ state_priority
+ vulnerability_priority
+ focus_priority
- protection_penalty
```
Default terms:
| Term | Score |
|---|---:|
| Same lane | +120 |
| Adjacent lane | +40 |
| Other lane | +0 |
| Target below 30% HP, if action has `finish` | +100 |
| Target currently casting, if action has `disrupt` | +120 |
| Target has required setup tag | +160 |
| Focus Order mark | +1000 |
| Protected rear against ranged | -120 |
| Explicit untargetable/invalid | removed, not a large negative |
The highest score wins; exact ties use the `target_tie` stream. A forced target
must still be legal and reachable. If a Focus target cannot be selected, the
log names the filter that rejected it rather than silently choosing another.
Player-facing prediction shows the first expected target before battle and
updates after formation/loadout changes.
## 9. Damage, Healing, Barrier, And Criticals
### 9.1 Damage
Skills declare `Base`, `Coefficient`, `PowerSource`, damage type, pierce, and
tags. Calculate:
```text
Raw = Base + Coefficient * selected_power
EffectiveDefense = clamp(relevant_defense - pierce, -75, 500)
if EffectiveDefense >= 0:
DefenseMultiplier = 100 / (100 + EffectiveDefense)
else:
DefenseMultiplier = 2 - 100 / (100 - EffectiveDefense)
CritChance = clamp(skill_base_crit
+ 0.002*(source_Finesse - 0.5*target_Resolve)
+ explicit_crit_bonus,
0, 0.60)
FinalDamage = floor(max(1,
Raw * DefenseMultiplier * CritMultiplier
* outgoing_group * incoming_group * encounter_group))
```
`relevant_defense` is Guard for physical, Ward for arcane, and zero for true
damage. True damage cannot crit and may not exceed 20% of target Max HP from a
single non-boss event. Base CritMultiplier is 1.50 and is clamped to 1.00-2.25.
Within each modifier group, bonuses add before the group is multiplied. Each
group is clamped to 0.25-3.00; final outgoing x incoming x encounter is clamped
to 0.10-5.00. Total reduction from all sources cannot reduce a positive hit
below 5% of its pre-defense Raw unless a visible block, immunity, or barrier
absorbs it.
### 9.2 Healing
```text
RawHeal = Base + Coefficient * HealingPower
FinalHeal = floor(max(0,
RawHeal * outgoing_heal_group * received_heal_group
* encounter_heal_group))
EffectiveHeal = min(FinalHeal, MaxHP - current_HP)
```
Healing cannot crit unless a skill declares `healing_crit`; its chance uses the
same cap and must be visible. Overheal is discarded unless an explicit effect
converts it. Conversion is capped at 50% of overheal and respects the barrier
cap.
### 9.3 Barrier And Block
Barrier absorbs damage after interception and mitigation. Generic barrier on a
unit is capped at 50% Max HP. New barrier adds to the existing amount up to the
cap; oldest timed barrier expires first. Barrier does not increase Threat from
wasted amount.
`Block` is an explicit charge that negates one eligible hit after interception
but before barrier. Area, true, or `unblockable` damage is ineligible and shown
as such. A unit may hold at most three generic Block charges.
## 10. Status Effects And Control
### 10.1 Common Status Schema
Every status row declares:
```text
stable_id, category, source_id, target_id
base_apply_chance, potency_source, resist_stat
duration, tick_interval, max_stacks
stack_rule (add/refresh/replace/independent)
dispel_tags, immunity_tags, control_group
on_apply, on_tick, on_expire, presentation events
```
Apply chance for a resistible status is:
```text
ApplyChance = clamp(BaseChance + 0.005*(Potency - Tenacity), 0.10, 0.95)
```
`guaranteed` effects bypass the probability roll but not declared immunity.
`unresistable` is reserved for encounter rules, never ordinary item procs.
Stack count, duration, next tick, source, and immunity are inspectable.
### 10.2 Categories
| Category | Contract |
|---|---|
| Affliction | Periodic damage or healing reduction; snapshots declared stats at application unless tagged dynamic |
| Impairment | Non-hard debuff to Tempo, power, defense, targeting, or movement |
| Control | Interrupt, Root, Silence, Stun, Sleep, or Fear; subject to control resistance and immunity windows |
| Mark | Enables targeting, setup, or resource interaction; no hidden numeric payload |
| Boon | Positive stat/rule modifier with visible duration |
| Barrier/Block | Damage prevention governed by Section 9.3 |
| Injury | Expedition-persistent Strain only; never dispelled in battle |
### 10.3 Hard-Control Boundary
For Stun, Sleep, and Fear:
```text
EffectiveDuration = clamp(BaseDuration * 100/(100 + Tenacity), 0.25, 4.0)
```
Boss/elite data may further cap one application to 1.5/2.5 seconds, but must
show that cap in preview. After hard control ends, the target gains `Control
Guard` for `2 + EffectiveDuration` seconds. During Control Guard, new hard
control duration is reduced 70%; a second consecutive application grants
immunity for four seconds. No unit can be unable to act for more than 50% of
any rolling ten-second window.
Interrupt is not hard control: it cancels an interruptible cast and applies
the cast's declared recovery. Silence blocks tagged spells but not movement,
basic action, directives, or passive effects.
## 11. Profession Resources And Skill Loadout
Every profession uses the shared `Aether` meter from 0-100 for its Signature.
Basic actions gain 8 Aether, techniques gain or spend their declared amount in
-40 to +30, taking effective damage gains at most 10 per tick, and passive gain
is capped at 5 per second. A Signature requires 100 and spends all 100 unless
its row declares a partial-cost advanced rule. No Signature fires automatically
without a player-visible AI condition.
An active loadout contains exactly:
- one fixed profession trait;
- one fixed basic action;
- two selected techniques;
- two selected passives;
- one selected Signature;
- a four-row automatic priority list plus basic fallback.
Each base profession provides one trait, one basic, three techniques, three
passives, and one Signature. Each advanced profession is a branch of exactly
one base and adds one trait transformation, two techniques, two passives, and
one alternate Signature. Advanced loadouts choose from the combined base and
branch pool; they do not gain additional slots.
This cap prevents advanced professions from being pure action-count upgrades.
Every branch must exchange at least one target, timing, formation, resource, or
risk rule for another; a branch consisting only of larger coefficients fails.
## 12. The 12 Base And 24 Advanced Profession Contract
Content names the professions. The system requires this exact topology:
```text
12 base professions
each base -> branch A + branch B
total advanced professions = 24
```
### 12.1 Required Base Distribution
Across the 12 bases, primary functions must be distributed exactly:
| Primary function | Count | Required distinct question |
|---|---:|---|
| Hold/protect | 3 | Which lane or damage window deserves protection? |
| Pressure/finish | 3 | Which target or timing converts setup into defeat? |
| Restore/enable | 3 | Which ally/resource/timing preserves the plan? |
| Control/reposition | 3 | Which enemy action or slot relation must change? |
Each base also declares one secondary function from a different row. No two
bases may share all of: preferred rank, target policy, Aether loop, damage type,
primary counter tag, and timing profile.
### 12.2 Branch Pair Rule
The two branches of one base must answer opposed planning goals. Allowed axes
include single-lane versus cross-lane, prevention versus recovery, burst versus
sustain, setup versus payoff, self-risk versus ally-risk, or fixed formation
versus repositioning. Both must retain the base's recognizable trait.
For every branch pair, content supplies two fixed counterfactual encounters:
1. one in which branch A is rationally superior;
2. one in which branch B is rationally superior.
The losing branch must remain capable of winning with a different company; the
test proves state dependence, not a hard key/lock gate.
### 12.3 Character Access And Advancement
- Every recruit begins with one authored base profession.
- Every recruit declares two additional learnable base professions; the three
must include at least two primary-function groups.
- A recruit can learn all three eventually, but has one active profession.
- A base reaches `Adept` at 100 Mastery and `Master` at 300 Mastery.
- Its advanced branches become learnable only after Adept, the branch's
chapter transformation, and one authored mastery trial.
- Both branches can be learned by the same recruit. Only one is active.
- Advanced mastery is tracked per branch; it does not erase base mastery.
- Level is character-wide. Profession mastery unlocks options, not mandatory
permanent stat percentages.
The content package must distribute access so all 12 bases are available in
the roster by the end of Chapter 3 and all 24 branches by the end of Chapter 8.
### 12.4 Respec And Switching
At the Guild, all learned profession switches, skill selections, AI priorities,
and attribute-growth choices are free and reversible. Equipment is never
destroyed by unequipping.
During an expedition:
- formation, equipment, skills, and priority rows can change during Prepare;
- active profession/advanced branch can change only at an Anchor;
- the first one-character profession change at each Anchor is free;
- each additional changed character before leaving that Anchor costs one
Supply, disclosed before commit;
- no respec or item swap is legal after battle confirmation.
Refunding an unlocked skill returns all spendable skill points atomically.
Mastery and story unlocks cannot be refunded because they are non-spend
progress records.
## 13. Equipment And Item System Hooks
Each adventurer has four equipment slots:
| Slot | Baseline role | Boundary |
|---|---|---|
| Focus | Primary attack/cast expression and Power budget | Does not determine profession |
| Garb | HP, Guard, Ward, and protection behavior | Cannot grant more than 25% generic reduction alone |
| Relic | Status, resource, timing, or rule interaction | Must expose trigger and cooldown |
| Tool | Route utility or narrow battle action modifier | Cannot silently consume persistent resources in battle |
Items may be legal in multiple slots only if the catalog row declares each
budget profile. A unit cannot equip duplicate stable item IDs. Company-wide
unique effects use `unique_group`; a second copy may be equipped for its local
stats but its unique effect is visibly dormant.
### 13.1 Behavior Hook Vocabulary
Content can change only named hooks unless this authority is revised:
```text
before_target, after_target
before_cast, on_cast_complete, on_interrupt
before_damage, after_damage, on_critical
before_heal, after_heal, on_overheal
on_barrier_break, on_block
on_status_apply, on_status_expire
on_shift, on_forced_move, on_lane_exposed
on_aether_gain, on_signature
on_down, on_rescue
route_preview, reward_draft, secure_cache, recover, reroute
```
Every proc declares its condition, cooldown (minimum 0.5 s unless a fixed test
proves no loop), maximum triggers per action, and whether derived effects can
retrigger it. Default is `derived effects cannot retrigger`.
### 13.2 Item Comparison
Comparison shows:
- primary and derived stat deltas;
- changed skill timing, target candidates, status chance, and resource flow;
- lost and gained interaction tags;
- effect on predicted first target and lane protection;
- chapter item-band difference, without labeling one item universally better.
The 320-row catalog, acquisition, tiers, upgrades, salvage, and the at-least-120
behavior-changing test are owned by the economy authority and content catalog.
## 14. Tactical Directives
### 14.1 Command Charges
The company starts each standard encounter with one Command charge, holds at
most two, and can spend at most two total. The second is earned when the Command
meter reaches 100. It starts at zero and gains from nonrepeatable tactical
events:
| Event | Gain | Per-encounter cap |
|---|---:|---:|
| Interrupt a declared major cast | 20 | 40 |
| Break an enemy Barrier or Block sequence | 15 | 30 |
| Exploit a previewed weakness/setup tag | 10 | 30 |
| First allied Downed event | 20 | 20 |
| Boss phase transition | 25 | 50 |
Repeated hits from one action count once. Meter gain beyond 100 is discarded
after awarding the second charge. Items may redistribute gains but cannot grant
a third use.
### 14.2 Core Directives
The onboarding unlocks three universal directives. The player prepares exactly
two before an expedition and may change them at an Anchor.
| Directive | Target/effect | Illegal reason examples |
|---|---|---|
| Focus Order | Mark one reachable enemy for 6 s; +1000 Target Score for actions that can legally target it; exposes its next action in event log | Target dead, untargetable, no legal allied action |
| Brace Order | One allied lane gains barrier equal to 12% of each unit's Max HP and `Anchored` for 4 s | Lane empty, both units Downed |
| Shift Order | Swap two orthogonally adjacent living allies; each gains 50% damage reduction for the 0.5 s transition | Not adjacent, Rooted, Downed, uninterruptible cast, destination reserved |
Using a directive pauses simulation during legal target selection by default.
Confirm stamps it to the next tick and spends the charge atomically. Cancel
spends nothing. Repeating confirm with the same action ID cannot spend twice.
Content may add directives only by exchanging targeting, timing, or risk. It
may not add raw damage/healing directives that are optimal whenever charged.
### 14.3 Standing Orders: Bounded Automation
After the player earns Mastery for an encounter mechanic, they may configure
one standing order:
```text
visible condition -> one prepared directive -> legal target policy
```
Examples of legal conditions are `major cast with tag begins`, `front lane
becomes exposed`, or `two allies below 40% HP`. The order consumes a real
Command charge and produces the same log as manual use. It is active only in
encounters whose relevant threat tags are mastered. First-seen enemy identities,
elites, bosses, and new chapter rupture rules require manual confirmation.
The player can disable or override the order. If its condition occurs but the
directive is illegal, no charge is spent and the exact reason is logged. This
automates solved timing labor without choosing route, build, risk, or novel
counterplay.
## 15. Enemy AI And Telegraph Contract
Every enemy row declares:
```text
preferred slots and legal displacement
target candidate filter and score modifiers
basic action and major action(s)
first-major-action horizon
telegraph duration and interrupt/control response
counter tags and at least two rational responses
phase triggers and changed rules
failure contribution shown in report
```
### 15.1 Preview
Before commitment, the encounter shows:
- exact enemy slot occupancy and any hidden arrival slots as silhouettes;
- damage/pressure families, target rules, and bypass/intercept tags;
- earliest possible major action in a bounded window;
- hard-control, displacement, summon, heal, barrier, or execution capability;
- resistances and immunities as rules, not unexplained percentages;
- objective, retreat rule, 180-second Fracture Clock, and rewards;
- a comparison against the current company identifying exposure, not a
guaranteed win percentage.
Unknown story identity may hide name/art, but never a mechanic needed to make a
fair preparation decision.
### 15.2 In-Battle Telegraph
- A directive-relevant major action has at least 2.0 simulation seconds of
telegraph; bosses have at least 3.0 on first use.
- Telegraph shows caster, legal targets or area, completion tick, effect tags,
and interrupt/control response.
- At 2x/4x, the first occurrence of an unmastered major action invokes a
`Decision Hold`: slow to 1x and maintain at least two real seconds before
completion. The player may disable automatic hold only after passing its
tutorial; pause and event-log inspection remain available.
- A changed target updates the line and reason. A hidden retarget is forbidden.
- Fake telegraphs are allowed only when the encounter preview explicitly names
deception as the mechanic and supplies a readable tell.
## 16. Battle Speed, Pause, And Fracture Clock
Available speeds are pause, 1x, 2x, and 4x. Speed multiplies how quickly fixed
ticks are presented, not cooldowns, chances, command timestamps, or rewards.
The player may pause during all single-player battles, target directives while
paused, inspect status/event history, and change future AI priorities only
after the encounter, never while paused.
Standard battles target 35-120 simulation seconds. At 150 seconds, visible
`Fracture Pressure` begins:
- all damage dealt increases 25% per ten seconds;
- all healing and new barrier strength decrease 20% per ten seconds;
- damage increase caps at +100%; healing/barrier reduction caps at -80%.
At 180 seconds the route rupture completes and the encounter is a defeat unless
its declared objective was already satisfied. The preview and battle clock
state this. Content must still pass simulation without relying on the final
collapse as its normal resolution.
## 17. Downed, Rescue, Retreat, And Victory
At zero HP, a normal adventurer becomes `Downed`:
- leaves target candidacy except for rescue/execution actions;
- no longer protects a rear slot or contributes passive company effects unless
the passive explicitly declares a Downed behavior;
- retains statuses whose rows declare persistence;
- starts an eight-second Rescue Window.
A legal rescue returns the unit at 25% Max HP, clears hard control, grants one
second untargetable recovery, and can occur once per adventurer per encounter.
After the window expires the unit is `Lost for encounter`, not deleted. Winning
with a Lost unit adds one Strain after battle.
Retreat becomes legal ten seconds after battle start unless the preview declares
a shorter/longer objective-specific boundary in 5-30 seconds. It channels for
three seconds, can be interrupted by a declared effect, and returns through the
failure transaction appropriate to difficulty. The UI previews exact cache,
Supply, and Strain consequences before channeling.
Victory occurs only when the declared objective predicate is true, such as all
required enemies Downed, a channel protected, or a rescue completed. Killing
unrequired summons does not silently satisfy an objective. Outcome is checked
after simultaneous event application.
## 18. Battle Diagnosis
The result report is an explanation system, not a damage leaderboard. It stores
and presents:
1. the player's pre-battle predicted first target and exposed lane;
2. actual first target, first major telegraph, and first plan divergence;
3. earliest lane protection loss with cause;
4. first preventable major hit, control, or failed command;
5. every Downed event and its preceding five seconds of causal events;
6. effective damage, prevention, healing, control, setup, and resource value;
7. wasted overheal/barrier, unreachable casts, fizzles, and dormant unique effects;
8. the top three counterfactual categories, framed as evidence rather than an
auto-equip recommendation;
9. reward and failure transaction IDs for support/debug views.
Contribution score is never used for rewards and is not collapsed into one
rank. The player can compare two attempts on the same encounter seed. A
training replay may apply one changed loadout/slot without rewards to validate
the counterfactual.
## 19. Expedition Route System
### 19.1 Route Graph
An expedition contains four to seven nodes from these mechanical categories:
| Node | Decision purpose |
|---|---|
| Conflict | Test formation/build against visible enemy pressure |
| Hazard | Trade Supplies, Strain, or a loadout tag against route risk |
| Opportunity | Choose one of multiple reward/acquisition directions |
| Camp | Recover, reconfigure, or secure at opportunity cost |
| Story | Authored character/world choice with declared mechanical consequence |
| Elite | Combine at least two pressures for a higher-value secured reward |
| Anchor | Bank cache, save route progress, transform/reveal network |
At each decision, two or three reachable nodes are visible. At least one route
must be viable without the newest random item. Scouting can reveal one extra
node or hidden parameter but cannot be mandatory to avoid an untelegraphed
counter.
### 19.2 Supplies
Supplies are expedition capacity, start at six by default, and cap at nine.
Baseline actions:
| Action | Supply cost | Result |
|---|---:|---|
| Recover | 1 | Clear one Strain from one adventurer or heal company to full at Camp/Anchor |
| Secure early | 2 | Bank current Unsecured Cache without ending expedition |
| Deep scout | 1 | Reveal one extra branch and exact reward family |
| Reroute | 1 | Return to prior fork without rerolling revealed nodes |
| Extra profession change | 1 | Change one additional active profession at an Anchor |
Chapter and difficulty may alter starting amount by at most +/-2. Supplies are
never sold for premium currency and do not regenerate with real time. Unused
Supplies convert to a modest end-expedition Crown bonus defined in the economy
authority, so preserving them is valuable but not always dominant.
### 19.3 Unsecured Cache And Anchors
Encounter rewards enter the Unsecured Cache unless marked immediately secured.
An Anchor atomically:
- banks the cache into persistent inventory/currencies;
- updates chapter route and transformation state;
- clears the encounter journal and creates a recovery checkpoint;
- grants the anchor's one free profession change;
- exposes the next route choice and exact withdrawal result.
The player may voluntarily withdraw at any noncombat node. Withdrawal banks or
forfeits cache according to difficulty, shown before confirm. Failure behavior
is specified in the save/failure authority.
## 20. Guild Systems
The Guild provides persistent functions without timers:
- roster and company assembly;
- profession learning, mastery trials, and free respec;
- equipment inventory, deterministic crafting, upgrades, and salvage;
- chapter/route selection and threat archive;
- training replays with no rewards;
- catalog, achievements, accessibility, localization, and settings;
- postgame Reweave laws and completion records.
Facilities unlock new actions or acquisition paths. Facility levels may not be
pure percentage multipliers or require waiting in real time. A solved repetitive
action may become a batch operation only after the single-item result and costs
are understood.
## 21. Content Schemas
### 21.1 Profession Row
```text
profession_id, base_or_advanced, parent_base_id
primary_function, secondary_function, preferred_rank
base_stats and growth vector
trait, basic, techniques[], passives[], signature
default priority rows and legal target policies
aether loop, counter tags, vulnerability
branch opposition statement
unlock/mastery trial and chapter placement
two counterfactual validation encounters
presentation and accessibility events
```
### 21.2 Skill Row
```text
skill_id, owner_profession, tags
candidate filter, target score modifiers, retarget policy
Base, Coefficient, PowerSource, damage/heal/control type
windup, cast, recovery, cooldown, aether delta
status rows and proc hooks
AI condition vocabulary and telegraph
illegal/fizzle reasons
animation, VFX, SFX, caption, reduced-motion alternative
fixed validation input and expected event outputs
```
### 21.3 Enemy Row
Uses the telegraph contract in Section 15 and must add progression placement,
reward family, distinct mechanic statement, two counter-responses, interaction
with at least two older mechanics, and failure-report language. A palette/stat
variant without a new preview-to-counter question is not an identity.
### 21.4 Encounter Row
```text
encounter_id, chapter, route tags, objective
enemy identities/slots/levels, seed rules
preview fields and hidden-but-nonstrategic story fields
Fracture Clock, retreat rule, reward budget
expected battle duration and decision timestamps
normal/active/efficient/adversarial/returning profile assertions
victory, defeat, recovery, and training-replay result
```
## 22. Static Balance And Validation Gates
Before a systems implementation may claim automated verification:
- all 12 base professions have exactly two branches;
- all loadouts satisfy fixed slot counts;
- all skills use declared hooks, target filters, and timing bounds;
- all enemy major actions have preview and telegraph records;
- no content exceeds defense, critical, barrier, control, or directive caps;
- every item proc has a cooldown/trigger cap and recursion declaration;
- target prediction matches first simulated target for deterministic fixtures;
- replay hash matches for identical seed and command timeline;
- each branch pair passes both opposed counterfactual fixtures;
- every encounter has at least two rational response tags and one no-random-
acquisition completion path;
- standard battles resolve before 180 seconds in all five pacing profiles;
- invalid commands return one enumerated reason and spend no resource;
- no report recommends a specific item as a universal answer.
## 23. Required Fixed Test Vectors
| Vector | Setup | Expected boundary |
|---|---|---|
| Front protection | F2 and R2 versus standard melee | R2 is not a candidate until F2 is Downed/Broken |
| Ranged protection | Same setup versus ranged | R2 remains legal with -120 score; preview shows it |
| Focus legality | Focus marked protected rear against melee-only party | No illegal forced target; reason logged |
| Simultaneous down | Two units complete lethal actions same tick | Both actions apply; both units Downed |
| Barrier cap | Repeated barrier grants over 50% Max HP | Excess discarded and reported as waste |
| Control chain | Three stuns inside ten seconds | duration reduction then immunity; action window preserved |
| Directive duplicate | Same confirm action ID submitted twice | one charge spent, one event applied |
| Speed parity | Same commands at 1x and 4x ticks | identical outcome hash |
| Save parity | Suspend during cast and resume | same next event and final hash |
| Proc recursion | Derived damage owns same hook as source | no retrigger unless row explicitly permits within cap |
| Long battle | Objective incomplete at 150/180 s | pressure escalates, then declared defeat at 180 |
| Branch counterfactual | Fixed base with branch A/B encounters | each branch leads one fixture without universal dominance |