what-are-effect-tokens.md

What Are Effect Tokens Actually?

Every state-modifying operation in STS flows through the same system:

 [Card/Potion/Relic/Event]
             │
             ▼
       use() or onX()
             │
             ▼

addToBot(AbstractGameAction)
             │
             ▼
┌─────────────────────────┐
│    GameActionManager    │
│   actions: ArrayList<>  │
│ → processes queue       │
│ → calls action.update() │
│ → mutates game state    │
└─────────────────────────┘

• addToBot: Add to bottom of action queue
• addToTop is for things that need to interrupt/execute before already-queued actions.

Layer	Game Entity	Count	Role
Effect producers	Cards, Potions, Relics, Events	~1100	What we embed as "effect tokens"
Primitive actions	AbstractGameAction subclasses	~280	The actual state mutations
Queue system	GameActionManager	1	Unified execution path

Thus An effect token is the abstraction of game systems into token representations. They can be consumed in order to express it's effect on the observation, applied according to the game's logic.

Notice that a particular action, say playing a card, choosing an event, or ending turn, are all composed of one or many effect tokens with ordered application, with their observed effect being context-dependent state transitions.

Some notes:

  state + effect_token → state_predictor → predicted_state'
                                ↓
                      (compare to actual state')
                                ↓
                      train embedding model

1. Collect trajectories: (s₀, a₀, s₁, a₁, s₂, ...)

2. Compute state deltas: Δᵢ = sᵢ₊₁ - sᵢ (dimensioned observation diff)

3. Learn effect tokens:

• Encoder: Δ → effect_token (learned embedding)
• Each action type gets an effect representation

4. State predictor training:

• Input: (state, effect_token)
• Output: predicted_next_state
• Loss: ||predicted - actual||²

5. Result: effect_token captures "what this card/power/potion/relic/event_choice does"