From a7225217df83d689311907e6b295c04ba5594271 Mon Sep 17 00:00:00 2001 From: Prime Date: Thu, 26 Mar 2026 13:06:36 +0000 Subject: [PATCH] Add readable SOR systems reference docs --- ability_system_detailed_readable.md | 804 ++++++++++++++++++++++++++++ affinity_system_readable.md | 318 +++++++++++ game_mechanics_readable.md | 476 ++++++++++++++++ 3 files changed, 1598 insertions(+) create mode 100644 ability_system_detailed_readable.md create mode 100644 affinity_system_readable.md create mode 100644 game_mechanics_readable.md diff --git a/ability_system_detailed_readable.md b/ability_system_detailed_readable.md new file mode 100644 index 0000000..00642e4 --- /dev/null +++ b/ability_system_detailed_readable.md @@ -0,0 +1,804 @@ +# SOR Ability System — Detailed Readable Guide + +This document explains how the current ability system works in practice, based on: + +- `SOR/Server/src/SOR.Game/Abilities/AbilitySystem.cs` +- `SOR/Server/src/SOR.Admin/Components/Pages/Cards/AbilityBuilder.razor` + +The goal is to bridge three viewpoints at once: + +1. **designers** who want to understand what kinds of abilities are possible +2. **implementers** who want to know how the engine actually resolves them +3. **content authors** using the admin Ability Builder + +--- + +## 1. High-level model + +The ability system is data-driven. + +Abilities are stored as JSON and parsed into engine models. The engine then: +- validates whether an ability can fire +- resolves targets +- pays costs if necessary +- executes one or more actions +- each action applies one or more effects +- durations are tracked so temporary effects can expire or reverse later + +That means abilities are not hardcoded one-by-one. They are built from a structured rules language. + +--- + +## 2. The four ability types + +The admin builder exposes four top-level ability types, and the engine recognizes them. + +## 2.1 Active +An Active ability is manually activated by the player. + +Typical properties: +- range +- uses per turn +- costs +- activation conditions +- actions/effects +- optional duration override + +The engine enforces: +- source unit must exist +- source unit must not be exhausted +- source unit must be allowed to use abilities +- ability index must be valid +- ability type must be `Active` +- named ability must not be disabled +- uses per turn must not be exhausted +- activation conditions must pass +- costs must be payable + +Then the actions resolve. + +--- + +## 2.2 Passive +Passive abilities are always-on while the source unit is on the battlefield. + +The engine applies passive abilities by: +- finding passive definitions on a source unit +- executing their actions +- tracking them with `WhileSourceOnBattlefield` by default if no explicit duration is given + +When the source leaves play, passive effects from that source are revoked. + +Important consequence: +- passive buffs are not “just descriptive text” +- they are actual tracked applied effects that can be reversed + +--- + +## 2.3 Aura +Auras are continuous-range relationships. + +An Aura ability defines an `AuraRange`, and the engine watches: +- when units enter aura range +- when units leave aura range +- when a unit with an aura enters play +- when a unit with an aura moves +- when a target unit moves +- when a unit with an aura leaves play + +So auras are not resolved once; they are part of an event system. + +--- + +## 2.4 Triggered +Triggered abilities fire automatically when a matching event occurs. + +Examples: +- turn start +- card drawn +- unit death +- unit enters battlefield +- SP gained/spent +- ruin activation +- entering aura range +- etc. + +The engine scans battlefield units for triggered abilities and fires any that match the trigger occurrence and pass activation conditions. + +--- + +## 3. Abilities vs EffectsJson card effects + +There are two relevant ways non-unit cards can do things. + +## 3.1 EffectsJson +Cards like Repentance / Instinct / Ruin can carry a flat action list in `EffectsJson`. +The engine parses that and executes it immediately on play. + +## 3.2 AbilitiesJson on cards +The engine also supports Active-style ability definitions on non-unit cards, especially for targeted Repentance / Instinct behavior. + +There is even a compatibility fallback: +- if `AbilitiesJson` has no active entries +- the engine may try parsing active abilities out of `EffectsJson` + +So the engine is tolerant of older or mixed content pipelines. + +--- + +## 4. Core execution pipeline + +At a high level, ability execution looks like this: + +1. parse the ability JSON +2. validate source-side conditions +3. pay costs +4. resolve action targets +5. apply target-side conditions +6. execute effects +7. track reversals / durations if needed + +That same action/effect model is reused across active, passive, triggered, and card-fired effects. + +--- + +## 5. Ability structure + +An ability definition can contain: +- `Type` +- `Name` +- `Description` +- `Range` or `AuraRange` +- `UsesPerTurn` +- `Cost` +- `TriggerEvent` +- `ActivationConditions` +- `Actions` +- `Duration` +- optional animation metadata + +The important thing is that an ability typically contains **one or more Actions**, and each Action contains: +- a target selector +- optional action conditions +- one or more effects + +So the action is the real “resolution block.” + +--- + +## 6. Targeting model + +The target selector has several parts. + +## 6.1 Scope +Scope tells the engine where to search: +- `Battlefield` +- `Hand` +- `Deck` +- `Discard` +- `Player` +- `AnyZone` + +## 6.2 Target type +Examples include: +- `Unit` +- `ArchSpirit` +- `Spirit` +- `SpiritToken` +- `Ruin` +- `Tile` +- `Card` +- `Player` + +## 6.3 Ownership +Ownership narrows the candidate pool: +- `Self` +- `ExactSelf` +- `Owner` +- `Ally` +- `Enemy` +- `Any` +- `Random` +- `Target` + +Important distinctions: +- `Self` means same controller’s entities +- `ExactSelf` means the exact instance using the ability +- `Target` is for chained actions that reuse a previous resolution context + +## 6.4 Count +The selector can choose: +- one target +- N targets +- all targets +- up-to-N targets depending on config + +If required targets are missing, the engine can fail with `INSUFFICIENT_TARGETS`. + +## 6.5 Client-selected vs auto-selected +For actions that require explicit client selection, if the client does not provide targets, the engine may fail. +For self/automatic selectors, the engine can auto-resolve. + +--- + +## 7. Range checking + +Active abilities may define range. +The engine checks: +- min range +- max range +- optional `LinearOnly` +- optional `RequiresLos` + +Current engine details: +- range uses Manhattan distance in this part of the ability system +- linear-only allows same row / column / diagonal line +- LOS uses board line-of-sight helpers + +For tile targets and field-card targets, out-of-range explicit client selections can produce: +- `TARGET_OUT_OF_RANGE` + +--- + +## 8. Conditions + +Conditions can exist at two levels. + +## 8.1 Ability activation conditions +These gate whether the whole ability can activate/fire. + +## 8.2 Action conditions +These gate one specific action. + +There is also a `Subject` distinction: +- `Self` +- `Target` + +Meaning: +- some conditions evaluate the source +- some evaluate each resolved target + +### Examples supported by the engine +Logical: +- `And` +- `Or` +- `Xor` + +Unit-state: +- `HealthBelow` +- `HealthAbove` +- `DefenseIs` +- `HasGenus` +- `HasAbility` +- `IsOnTileWithAffinity` +- `MovementTypeIs` + +Player-state: +- `SPAtLeast` +- `SPAtMost` +- `STAtLeast` +- `STAtMost` +- `HandSizeAtLeast` +- `HandSizeAtMost` +- `DeckSizeAtLeast` +- `DiscardSizeAtLeast` + +Turn-state: +- `IsOwnTurn` +- `IsOpponentTurn` +- `IsAllyTurn` +- `IsActivePlayerTurn` + +Battlefield aggregate: +- `UnitCountOnBattlefield` + +A very important implemented one is: +- `IsOnTileWithAffinityCondition` + +That makes terrain-conditional design first-class. + +--- + +## 9. Costs + +The engine supports these cost types: +- `SpiritPoints` +- `SacrificeTokens` +- `DiscardFromHand` +- `MillTopOfDeck` +- `MillBottomOfDeck` +- `DealDamageToOwnArchSpirit` +- `DealDamageToOwnSpirit` +- `SendSpiritFromBattlefieldToDiscard` + +If a cost cannot be paid, activation fails. + +Examples of failure codes include: +- `INSUFFICIENT_SP` +- `INSUFFICIENT_ST` +- `INSUFFICIENT_CARDS_TO_DISCARD` +- `NO_VALID_SPIRIT_FOR_COST` + +So costs are fully part of resolution legality, not cosmetic metadata. + +--- + +## 10. Trigger system + +Triggered abilities listen for `TriggerOccurrence`s produced by the engine. + +The code currently supports matching triggers such as: +- `OnTurnStart` +- `OnTurnEnd` +- `OnUnitDeath` +- `OnDamageDealt` +- `OnUnitEnterBattlefield` +- `OnUnitLeaveBattlefield` +- `OnSPGained` +- `OnSPSpent` +- `OnSTGained` +- `OnSTSpent` +- `OnCardDrawn` +- `OnUnitMove` +- `OnUnitAttack` +- `OnSpiritSacrificed` +- `OnAscend` +- `OnTransition` +- `OnChanneled` +- `OnEnterAuraRange` +- `OnLeaveAuraRange` +- `OnRuinActivation` +- `OnUnitOccupyRuin` + +The admin UI lists even more trigger templates, some of which may be ahead of fully-matched engine support. +So for content authoring, the safe rule is: + +> the code is the final authority on what actually fires today. + +--- + +## 11. Effects: what abilities can actually do + +This is the meat of the system. + +The engine supports a large effect vocabulary. + +## 11.1 Stat modification +These mutate unit stats: +- `ModifyHealth` +- `ModifyDefense` +- `ModifyDamage` +- `ModifyMP` +- `SetMovementType` +- `SetAttackRange` +- `ModifyCost` +- `SetAffinity` +- `GrantAdditionalAttack` + +Most temporary stat modifications are tracked with reversal effects so they can expire cleanly. + +--- + +## 11.2 Unit flags +These toggle combat/action flags on units: +- `SetCanMove` +- `SetCanAttack` +- `SetCanDefend` +- `SetCanBeAttacked` +- `SetCanBeBlocked` +- `SetCanBeObstructed` +- `SetCanUseAbility` +- `SetCanBeSacrificed` + +This is a huge part of what makes the game feel expressive. + +--- + +## 11.3 Player flags +These toggle player-level permissions: +- `SetCanDrawCards` +- `SetAccumulatesSP` +- `SetCanChannelSpirit` +- `SetCanSacrificeSpirit` +- `SetCanAscendArchSpirit` +- `SetCanTransitionArchSpirit` +- `SetCanChannelRepentance` +- `SetCanChannelInstinct` +- `SetCanChannelRuin` +- `SetCanChannelTerramorphaMono` +- `SetCanChannelTerramorphaDi` +- `SetCanChannelTerramorphaTri` + +So the game supports hard lockouts or permissions at player scope. + +--- + +## 11.4 Ability modification +Abilities themselves can be changed mid-match: +- `AddAbility` +- `RemoveAbility` +- `EnableAbility` +- `DisableAbility` + +That means cards can grant temporary or persistent new abilities, or suppress existing ones. + +--- + +## 11.5 Genus changes +The engine supports: +- `AddGenus` +- `RemoveGenus` + +This matters because many conditions/filters can key off genus tags. + +--- + +## 11.6 Player resource effects +These can modify: +- current SP +- SP accumulation bonus +- current ST +- cards drawn per turn bonus + +Examples: +- `ModifySP` +- `ModifySPAccumulation` +- `ModifyST` +- `ModifyCardsDrawnPerTurn` + +--- + +## 11.7 Tile modification +These are crucial for terrain gameplay: +- `SetBaseAffinity1` +- `SetBaseAffinity2` +- `PushAffinity` +- `PushFinalAffinity` + +### Important distinction +- `PushAffinity` uses the normal shift rule (`Base1 = old Base2; Base2 = new`) +- `PushFinalAffinity` directly overrides the newer slot to force the tile toward a final target identity + +These are some of the most strategically important effect types in the entire game. + +--- + +## 11.8 Zone and card operations +The system supports a rich set of zone moves: +- `DrawCards` +- `DiscardCards` +- `ReturnToHand` +- `ReturnToDeck` +- `ReturnToBattlefield` +- `SendToDiscard` +- `SearchDeck` +- `ShuffleDeck` +- `RevealCards` +- `PlaceOnDeck` + +This means tutors, bounce, recursion, deck manipulation, and graveyard loops are all supported structurally. + +--- + +## 11.9 Damage and healing +Combat-adjacent effects include: +- `DealDamage` +- `Heal` +- `DealDamageToSelf` +- `DOT` +- `HOT` + +Damage normally respects defense first unless the effect says `BypassDefense`. + +DOT/HOT are tracked as turn-ticking active effects. + +--- + +## 11.10 Displacement +Movement-by-effect includes: +- `PushUnit` +- `PullUnit` +- `DisplaceUnit` + +These are distinct from normal movement and can reposition units directly if the destination is valid. + +--- + +## 11.11 Control effects +The engine can do things like: +- `TakeControl` +- `GrantMovementControl` +- `SetFixedSacrificeReturn` + +So temporary stealing or sacrifice rewrites are supported. + +--- + +## 11.12 Token summoning +The engine supports: +- `SummonToken` + +The token is built from JSON, turned into a `SpiritToken`, placed on the battlefield, and then normal enter-battlefield / aura / passive hooks are processed. + +That means tokens are not fake visual markers; they are real battlefield objects. + +--- + +## 11.13 Deferred effects +The engine supports: +- `ApplyOnEvent` + +This stores a pending deferred effect tied to: +- a trigger +- a target reference +- a source +- an owner + +Later, when the trigger occurs, the deferred effect executes. + +That gives the system delayed punishments, marks, future riders, etc. + +--- + +## 12. Filters + +Filters are used to narrow target pools or cost candidates. + +Implemented examples include: +- `GenusContains` +- `CardTypeIs` +- `AffinityMatches` +- `HasFlag` +- `TierIs` +- `IsSelf` +- `IsExactSelf` +- `HealthBelow` +- `HealthAbove` +- `IsAdjacentToSource` +- `WithinRange` + +This is a big part of what makes one generic effect system produce lots of specific card behavior. + +--- + +## 13. Value expressions + +One of the strongest parts of the system is that effect values can be dynamic. + +A value can be: +- fixed +- or a reference expression + +Examples supported by the admin builder / engine: +- `Self.Damage` +- `Self.Health` +- `Self.Defense` +- `Self.MP` +- `Self.SpCost` +- `Self.StCost` +- `Target.Damage` +- `Target.Defense` +- `Target.Health` +- `Target.MP` +- `Target.SpCost` +- `Target.StCost` +- `EventData.Amount` +- `Action0.Target.*` +- `Action1.Target.*` + +That means later actions in an ability can depend on what earlier actions targeted. + +### Example idea +- Action 1: target a Spirit and return it to hand +- Action 2: refund its SP cost to its owner + +That sort of chained design is absolutely supported by the model. + +--- + +## 14. Durations and reversibility + +Temporary effects are tracked in `ActiveEffects` along with duration metadata. + +Supported duration types in code/admin include: +- `Instant` +- `UntilEndOfTurn` +- `UntilStartOfOwnerTurn` +- `UntilStartOfSourceOwnerTurn` +- `ForNTurns` +- `WhileSourceOnBattlefield` +- `WhileCondition` +- `PermanentInMatch` + +The system stores reversal effects for many temporary modifiers. +When the duration expires, the reversal effect is executed. + +This is a very robust design choice. + +### Example +If an ability gives: +- `+2 Damage until end of turn` + +The engine tracks the inverse effect: +- `-2 Damage` + +Then applies that inverse later when the duration expires. + +--- + +## 15. Tick effects + +For ongoing effects like DOT/HOT: +- the engine stores them as active effects with `IsTick = true` +- at turn boundaries, it ticks them +- when duration runs out, the active effect is removed + +So DOT/HOT are not handled as one-off hacks. + +--- + +## 16. Ruin activation + +At the start of each turn, for each friendly occupied Ruin tile: +- the engine checks triggered abilities on the Ruin +- it selects exactly **one eligible `OnRuinActivation` ability at random** +- executes it +- then emits a RuinActivation trigger for observers + +This is an important subtlety: + +> a Ruin can have multiple possible activation abilities, but only one fires each activation. + +That gives Ruins controlled randomness. + +--- + +## 17. Passive application and revocation + +The passive system is more sophisticated than a lot of card engines. + +### When a passive source appears +The engine: +- applies passive effects from that source to valid battlefield targets +- tracks them as `WhileSourceOnBattlefield` + +### When a new unit enters +The engine: +- applies all existing passives from older sources onto the new unit + +### When a passive source leaves +The engine: +- revokes all `WhileSourceOnBattlefield` effects sourced from that unit + +### Conditional passives +The engine can fully re-evaluate conditional passives after state changes. + +This matters for things like: +- “while this is on Marsh…” +- “while you have 3+ Spirits…” +- “while this source remains in play…” + +--- + +## 18. Aura transitions + +Aura-related triggers are evaluated when: +- units move +- units enter battlefield +- units leave battlefield + +The engine checks both directions: +- did the moving unit enter somebody else’s aura? +- did somebody else enter/leave the moving unit’s own aura? + +That means aura triggers are symmetrical and spatially reactive. + +--- + +## 19. Admin Ability Builder: what it’s really doing + +The admin UI is not just a fancy text box. +It is a structured front-end for creating the JSON the engine expects. + +It exposes: +- ability type +- range / aura range +- uses per turn +- costs +- activation conditions +- trigger event selection +- actions +- targets +- effects +- durations +- animation metadata + +It also includes help text for: +- scope +- ownership +- filters +- value expressions +- durations +- conditions +- trigger events + +So it is effectively a content-authoring layer on top of the engine model. + +--- + +## 20. Important implementation realities / caveats + +## 20.1 Code beats builder help +The builder help is useful, but the engine code is final. +If there is a mismatch, trust the server code. + +## 20.2 Some builder options may be ahead of full engine support +The builder lists a broad trigger/effect vocabulary. Some of that is aspirational or broader than what’s fully wired today. +So practical validation is still necessary. + +## 20.3 Passive and aura content should be designed carefully +Because passives and aura transitions can reapply/revoke dynamically, sloppy content can become noisy or expensive. +The system is powerful, but wants disciplined design. + +## 20.4 Range and movement are not identical concepts +Ability range checking in this system is not the same as path-based movement legality. +That matters a lot for designing blink / push / pull / support abilities. + +--- + +## 21. Best mental model + +If you want the shortest useful description: + +> The SOR ability system is a structured action/effect engine where cards define who they can target, when they are allowed to fire, what they do, and how long the result lasts — with enough reversibility and event support to handle passives, auras, triggers, terrain manipulation, tokens, and delayed effects cleanly. + +That’s why it’s such a strong foundation. + +--- + +## 22. Practical authoring advice + +If I were using this system to author real cards, my rules of thumb would be: + +1. **Start simple** + - one action + - one target + - one effect + +2. **Only add cross-action references when they truly add value** + - they’re powerful, but complexity climbs fast + +3. **Use conditions instead of bespoke special-case text whenever possible** + - especially tile-affinity and turn-state conditions + +4. **Respect reversibility** + - temporary buffs/debuffs are safest when expressed in standard reversible effect types + +5. **Test trigger ownership carefully** + - `Owner`, `Enemy`, `Any`, and `ExactSelf` matter a lot + +6. **Be deliberate with terrain conditions** + - terrain-aware content is one of SOR’s best unique strengths + +7. **For Ruins, think in random eligible packages** + - one activation picks one eligible effect, not all of them + +--- + +## 23. Final read + +This is already a pretty serious system. + +It supports: +- active tactical abilities +- passive board shaping +- aura gameplay +- triggered event gameplay +- player-state manipulation +- terrain mutation +- card-zone operations +- token creation +- delayed triggers +- reversible temporary changes + +So from a card-design perspective, there’s a lot of room to make cards feel distinct without needing custom engine code for every idea. diff --git a/affinity_system_readable.md b/affinity_system_readable.md new file mode 100644 index 0000000..859aac6 --- /dev/null +++ b/affinity_system_readable.md @@ -0,0 +1,318 @@ +# SOR Affinity System — Readable Guide + +This is a human-readable explanation of the current affinity system as implemented in: + +- `SOR/Server/src/SOR.Game/Grid/AffinitySystem.cs` + +It is meant to be easier to read than the source while staying faithful to what the code currently does. + +--- + +## 1. Core idea + +Each battlefield tile has **two affinity slots**: + +- `Base1` = the older slot +- `Base2` = the newer slot + +The game resolves those two slots into a single **effective / final tile affinity**. + +So the affinity system is not just “this tile is Forest.” +It is really: + +- what was here before (`Base1`) +- what was pushed most recently (`Base2`) +- what those two combine into when resolved + +That means terrain is **layered and mutable**. + +--- + +## 2. Basic affinities + +The code treats these as the **basic** affinities: + +- `Void` +- `Aether` +- `Lake` +- `Hill` +- `Forest` +- `Field` + +Everything else is a **resolved / non-basic** affinity. + +--- + +## 3. Resolved affinities + +These are produced by combining the two base slots. + +### Void / Aether family +- `PureVoid` +- `UnstableAether` +- `PerfectAether` +- `GatewayLake` +- `GatewayHill` +- `GatewayForest` +- `GatewayField` + +### Natural pair results +- `Ocean` +- `Island` +- `Marsh` +- `Swamp` +- `Mountain` +- `Steppe` +- `Fort` +- `Plains` +- `Grove` +- `Jungle` + +--- + +## 4. Full resolution table + +## 4.1 Void and single-basic tiles + +### `Void + Void` +- `PureVoid` + +### `Void + basic` +When `Base1` is `Void` and `Base2` is a basic affinity, the tile simply reads as that basic affinity: + +- `Void + Lake` → `Lake` +- `Void + Hill` → `Hill` +- `Void + Forest` → `Forest` +- `Void + Field` → `Field` +- `Void + Aether` → `UnstableAether` + +This is how a blank tile becomes a simple one-affinity tile. + +--- + +## 4.2 Gateway affinities + +Gateways are **directional** and only occur when the second slot is `Void`. + +- `Lake + Void` → `GatewayLake` +- `Hill + Void` → `GatewayHill` +- `Forest + Void` → `GatewayForest` +- `Field + Void` → `GatewayField` + +Important: +- this is **not** symmetric +- `Void + Lake` is just `Lake` +- `Lake + Void` is `GatewayLake` + +So slot order matters. + +The source comments also note: +- Gateway affinities are **tile-only** +- they **cannot appear on cards** + +--- + +## 4.3 Aether rules + +- `Aether + Aether` → `PerfectAether` +- `Aether + anything else` → `UnstableAether` +- `anything else + Aether` → `UnstableAether` + +So unless both slots are Aether, Aether becomes unstable. + +--- + +## 4.4 Natural pairing results + +### Lake family +- `Lake + Lake` → `Ocean` +- `Lake + Hill` or `Hill + Lake` → `Island` +- `Lake + Field` or `Field + Lake` → `Marsh` +- `Lake + Forest` or `Forest + Lake` → `Swamp` + +### Hill family +- `Hill + Hill` → `Mountain` +- `Hill + Field` or `Field + Hill` → `Steppe` +- `Hill + Forest` or `Forest + Hill` → `Fort` + +### Field family +- `Field + Field` → `Plains` +- `Field + Forest` or `Forest + Field` → `Grove` + +### Forest family +- `Forest + Forest` → `Jungle` + +--- + +## 5. Push Affinity + +The fundamental terrain mutation operation is: + +```csharp +Base1 = old Base2 +Base2 = newAffinity +``` + +That means pushing affinity does **not** overwrite both slots. +It shifts the current `Base2` into `Base1`, then inserts the new affinity into `Base2`. + +### Example +If a tile is: +- `Base1 = Void` +- `Base2 = Lake` + +then it currently resolves to: +- `Lake` + +If you push `Field`, it becomes: +- `Base1 = Lake` +- `Base2 = Field` + +which resolves to: +- `Marsh` + +This is why Terramorpha and placement pushes can create hybrid terrain instead of only repainting tiles. + +--- + +## 6. ArchSpirit placement push + +When an ArchSpirit is placed, its affinity is pushed to: + +- the placement tile +- all valid adjacent tiles + +The exact neighboring set depends on board geometry and edge position, but the core implementation behavior is: + +- place ArchSpirit +- push its affinity onto the origin tile +- push its affinity onto orthogonally adjacent in-bounds tiles + +This is how the opening board shape starts forming. + +--- + +## 7. How card affinity validation works + +The affinity system also determines whether a card can legally be channeled to a tile. + +## 7.1 Basic affinity cards +If the card has a **basic** affinity, then the card is legal if: + +- `tile.Base1 == cardAffinity` +**or** +- `tile.Base2 == cardAffinity` + +That means a basic-affinity card cares about the tile’s **base slots**, not the final resolved result. + +### Example +A `Lake` Spirit can be channeled to a tile if either slot is Lake, including: +- `Void + Lake` +- `Lake + Field` +- `Lake + Hill` +- `Lake + Void` + +Even if the tile resolves to `Marsh`, `Island`, or `GatewayLake`, a basic Lake card is still legal as long as one slot is Lake. + +--- + +## 7.2 Non-basic affinity cards +If the card has a **non-basic** affinity, then the tile must resolve to that exact final affinity. + +### Example +A `Marsh` Spirit is legal only if the tile resolves exactly to `Marsh`. +That means: +- `Lake + Field` = valid +- `Field + Lake` = valid +- `Void + Field` = not valid +- `Lake + Lake` = not valid + +This is stricter than basic cards. + +--- + +## 8. What cannot be on cards +Per the code comments: + +- `Gateway*` affinities are tile-only +- `UnstableAether` is also tile-only + +So those may exist on the board, but should not be used as card affinities. + +--- + +## 9. Practical design consequences + +## 9.1 Order matters +Because tiles are slot-based, these are not equivalent: + +- `Void + Lake` +- `Lake + Void` + +The first is `Lake`, the second is `GatewayLake`. + +So push order matters a lot. + +## 9.2 Basic cards are easier to channel +Basic affinity cards only need a slot match. +That makes them more flexible than hybrid cards. + +## 9.3 Hybrid cards are more demanding +A non-basic card requires the tile’s final resolved identity to match exactly. +That means hybrid decks often want: +- ArchSpirit placement planning +- Terramorpha support +- tile-fixing effects + +## 9.4 Terramorpha is fundamentally a slot manipulator +Terramorpha is not merely cosmetic “terrain painting.” +It changes the slot state and therefore: +- channel legality +- future tile identity +- future hybrid access +- gateway production + +--- + +## 10. Quick cheat sheet + +### Basics +- Void +- Aether +- Lake +- Hill +- Forest +- Field + +### Same + same +- Lake + Lake = Ocean +- Hill + Hill = Mountain +- Field + Field = Plains +- Forest + Forest = Jungle +- Aether + Aether = PerfectAether +- Void + Void = PureVoid + +### Mixed naturals +- Lake + Hill = Island +- Lake + Field = Marsh +- Lake + Forest = Swamp +- Hill + Field = Steppe +- Hill + Forest = Fort +- Field + Forest = Grove + +### Directional specials +- basic + Void = GatewayBasic +- Void + basic = just that basic + +### Aether special +- Aether + non-Aether = UnstableAether + +--- + +## 11. Best mental model + +If you only remember one thing, remember this: + +> A tile is a two-layer stack, not a single color. + +And the whole system flows from that. diff --git a/game_mechanics_readable.md b/game_mechanics_readable.md new file mode 100644 index 0000000..6924404 --- /dev/null +++ b/game_mechanics_readable.md @@ -0,0 +1,476 @@ +# SOR Game Mechanics — Readable Guide + +This document summarizes the current gameplay model in a readable form, based primarily on: + +- `SOR/Shared/context-files/gameplay.md` + +This is not meant to replace source-of-truth engine rules forever, but it is a much easier reference for design and content work. + +--- + +## 1. Match setup + +Players build decks, then enter either: +- ranked matches +- custom matches + +Each player chooses: +- a deck +- a starting **Tier 1 ArchSpirit** + +Current deck rule notes in the gameplay doc: +- deck size currently has no minimum or maximum +- every deck must include at least one Tier 1 ArchSpirit + +--- + +## 2. Battlefield model + +The game is intended to support: +- `2..N` players +- square grids +- hex grids + +Each player has a defined starting side. +The battlefield size can scale with player count. + +So the long-term model is wider than just 1v1 square maps. + +--- + +## 3. Opening sequence + +## 3.1 ArchSpirit placement +At game start, each player places their selected Tier 1 ArchSpirit on the first row of their side. + +When the ArchSpirit is placed, its affinity is pushed to: +- the placement tile +- all valid adjacent tiles + +That means opening placement is also the first terrain-shaping action in the match. + +## 3.2 Opening draw +By default, each player draws: +- **7 cards** + +The gameplay doc notes this can be overridden by custom settings. + +--- + +## 4. Turn order + +### Free-for-all +Turn order is randomized among all players. + +### Team play +Teams alternate, and player order inside each team slot is randomized. + +Example: +- Team 1 Player A +- Team 2 Player C +- Team 1 Player B +- Team 2 Player D + +--- + +## 5. Resources + +## 5.1 Spirit Points (SP) +SP is your main spendable action/channeling resource. + +Rules currently documented: +- base SP gain per turn comes from game settings +- effects can modify SP gain +- no enforced SP cap yet +- a future cap is expected to be supported + +## 5.2 Sacrifice Tokens (ST) +ST is a separate resource. + +Important differences from SP: +- ST does **not** accumulate automatically each turn +- ST comes from other systems/effects +- ST is used to help pay some card costs + +So SP is your normal tempo currency; ST is more conditional / conversion-based. + +--- + +## 6. Start-of-turn order + +The gameplay doc gives a specific start-of-turn sequence: + +1. replenish movement points on friendly ArchSpirit / Spirit units +2. restore defense to max on friendly ArchSpirit / Spirit units +3. gain SP +4. resolve start-of-turn triggers +5. draw cards for turn +6. resolve draw triggers +7. activate Ruins (one random eligible Ruin ability per occupied Ruin) + +This order matters a lot for ability design. + +--- + +## 7. Hand rules + +Currently: +- there is **no enforced hand size limit** + +--- + +## 8. Turn timing and what can be interleaved + +During your turn, you can channel: +- Spirit +- Ruin +- Terramorpha +- Repentance +- Instinct + +And you may interleave card play with unit actions. + +That means there is **no required action ordering** like: +- “all movement first” +- “then attacks” +- “then card play” + +Instead, the current model is intentionally loose: +- move +- channel +- attack +- ability +- channel again +- sacrifice +- move again with another unit +- etc. + +As long as the action is legal and the costs can be paid, it can slot into the turn. + +--- + +## 9. Interrupts + +Instinct is special. + +Instinct cards may be played: +- during the active player’s turn +- during other players’ turns +- as interrupts / non-play responses + +The current timing note says: +- after each card played +- and after each unit action (move, attack, ability) +- there is a **10-second interrupt window** + +During that window, opponents may play an Instinct. + +Important exception: +- an ability’s internal action sequence resolves fully first +- there is **not** an interrupt window between each sub-action of one ability + +So the interrupt window is between whole actions, not inside a single action list. + +--- + +## 10. Channeling Spirits + +A Spirit can be channeled if: +- it is in the active ArchSpirit’s channel range +- its cost can be paid +- the target tile satisfies affinity legality + +### Channel range +ArchSpirit channel range has: +- minimum +- maximum + +If channel range is `0`, that ArchSpirit cannot channel. + +### Affinity legality +- basic-affinity Spirit: one of the tile base slots must match +- non-basic-affinity Spirit: the tile’s final resolved affinity must match exactly + +This ties Spirit play tightly to the affinity system. + +--- + +## 11. Channeling Terramorpha + +Terramorpha can target any tile on the battlefield. + +Types: +- **Mono** = 1 tile +- **Di-morpha** = first tile, then an adjacent tile +- **Tri-morpha** = first tile, then adjacent, then adjacent again + +The current gameplay doc is still a little high-level here, but the intent is clear: +- Terramorpha shapes battlefield affinity directly +- Di/Tri are connected-tile effects + +--- + +## 12. Unit actions per turn + +Each ArchSpirit / Spirit may generally: +- move until out of MP +- attack once per turn unless modified +- use one activated ability per turn unless modified + +Those limits can be altered by abilities/effects. + +--- + +## 13. Cost model + +Supported cost types currently documented include: +- Spirit Points +- Sacrifice Tokens +- discard from hand +- mill from top of deck +- mill from bottom of deck +- send own Spirit from battlefield to discard +- deal damage to own ArchSpirit +- deal damage to own Spirit + +That is a pretty broad cost vocabulary already. + +--- + +## 14. Transition and Ascend + +## 14.1 Transition +Transition means swapping your current ArchSpirit for a Tier 1 ArchSpirit from hand. + +Rules documented: +- only during your turn +- outgoing ArchSpirit goes to discard +- incoming one enters at full health/defense +- uses incoming ArchSpirit’s channeling cost +- incoming ArchSpirit may still move/attack/use abilities that turn + +So Transition is not “summoning sickness”-style restricted. + +## 14.2 Ascend +Ascend upgrades the current ArchSpirit by exactly one tier in its own line. + +Rules documented: +- only during your turn +- must be direct progression +- cannot skip tiers +- cannot switch to a different ArchSpirit line +- uses incoming higher-tier cost +- higher-tier source zone is not restricted +- new form may still act that turn + +So Ascend is an aggressive tempo upgrade, not just a slow replacement. + +--- + +## 15. Movement rules + +Movement is 1 MP per tile moved. + +A tile can contain at most one: +- Spirit +- ArchSpirit + +Movement can be obstructed depending on movement type and unit flags. + +Supported movement types: +- `Walk` +- `Flight` +- `Jump` +- `Teleport` + +### Walk +- path-based +- can be obstructed by units +- no LOS requirement + +### Flight +- path-based +- can only be obstructed by units with Flight +- no LOS requirement + +### Jump +- not obstructed +- min/max jump range +- costs MP per tile landed, not path traversed +- no LOS requirement + +### Teleport +- not obstructed +- min/max range +- costs MP per tile landed +- **does** require LOS + +### Pathing +- square grids: no diagonal walking pathing +- hex: BFS over adjacent hexes + +This is important because movement legality is more nuanced than just Manhattan range. + +--- + +## 16. Unit properties + +## 16.1 Genus +Genus is a list of tags like: +- Goblin +- Undead +- Warrior + +Effects can match against any genus tag a unit has. + +## 16.2 Health +- if health goes to `0` or below, the unit dies +- dead units normally go to discard unless an effect says otherwise + +## 16.3 Defense +Defense is a replenishing shield layer. + +Rules: +- defense restores to max at start of turn +- incoming damage is absorbed by defense first +- overflow spills to health + +This is not just “armor reduction” — it is a renewable buffer. + +--- + +## 17. Attacks + +Units define: +- attack style +- min attack range +- max attack range +- damage + +The attack system is intended to support: +- single-target attacks +- multi-target attacks +- AOE +- LOS requirements +- dynamic damage modifiers +- linear-only restrictions +- diagonal-only restrictions + +Interesting note: +- friendly units can be targeted by attacks +- but friendly attacks require confirmation + +So the system is flexible enough for friendly-fire, buff-like attack behaviors, or sacrificial mechanics. + +--- + +## 18. Mutable game objects + +The gameplay doc frames the rules around objects that can be modified temporarily or permanently. + +### PlayerState mutable examples +- current SP +- SP accumulation rate +- can draw cards +- can channel Spirit / Ruin / Terramorpha / etc. +- can Ascend / Transition + +### TileState mutable examples +- BaseAffinitySlot1 +- BaseAffinitySlot2 +- PushAffinity +- PushFinalAffinity +- occupancy-sensitive behavior + +### Zone operations +- return to deck +- shuffle +- draw +- mill +- discard +- reveal +- place onto battlefield +- move among hand/deck/discard/battlefield + +The rules are already designed around reversible, duration-based mutation. + +--- + +## 19. Duration model + +Supported duration primitives currently documented: +- `Instant` +- `UntilEndOfTurn` +- `UntilStartOfOwnerTurn` +- `UntilStartOfSourceOwnerTurn` +- `ForNTurns` +- `WhileCondition` +- `PermanentInMatch` + +The big design idea is: + +> temporary changes need enough stored context to be undone correctly later. + +That is a strong systems choice and matters a lot for ability implementation. + +--- + +## 20. Sacrifice + +Sacrifice is currently documented as: +- a free action +- only adjacent Spirits to your ArchSpirit may be sacrificed +- sacrificed Spirit goes to discard + +### Sacrifice value +The base sacrifice value is: + +```text +SpiritSacValue = (CardSTCost * 3) + CardSPCost +``` + +### ST return +The amount of ST returned depends on: +- your current ST +- the sacrificed Spirit’s computed value + +The current function is tiered and intentionally diminishing: +- low current ST + good sacrifice value = better ST return +- high current ST = smaller or zero return + +So sacrifice is a catch-up / conversion mechanic, not infinite scaling. + +--- + +## 21. Win condition + +Current documented win condition: + +- **last ArchSpirit standing wins** + +Simple and direct. + +--- + +## 22. What is still intentionally incomplete + +The gameplay doc explicitly says several areas are not fully locked yet, including: +- full timing windows +- replacement/edge cases for affinity pushing +- elimination timing in team modes +- mulligans +- simultaneous resolution rules +- ranked/custom constants +- full Di/Tri adjacency constraints + +So the game model is already strong, but some details are still designated WIP. + +--- + +## 23. Best mental model + +If you want the shortest useful summary: + +> SOR is a terrain-shaping tactics card game where your ArchSpirit defines your summon geometry, your units spend MP to reposition and attack, card types can be freely interleaved during your turn, and the affinity state of the board is one of the main engines of strategy. + +That is the heart of it.