Add readable SOR systems reference docs

This commit is contained in:
Prime
2026-03-26 13:06:36 +00:00
parent 7b11358573
commit a7225217df
3 changed files with 1598 additions and 0 deletions
+318
View File
@@ -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.