Files
cardgen/references/affinity_system_readable.md

319 lines
6.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.