From codec.py:25-38.Example snapshot: SNAP PLAYER X5 Y5 DIR_R LEN1 FOOD X8 Y6 SCORE V0This is 11 tokens encoding:
Player position (X5, Y5)
Player direction (DIR_R)
Snake length (LEN1)
Food position (X8, Y6)
Current score (V0)
Snapshots don’t include the full body — only head position and length. This is a design choice to reduce token count. The body can be reconstructed by tracking deltas.
def encode_tick_events(self, events: list[Event]) -> list[int]: filtered = [e for e in events if e.salience >= self.salience_threshold] if not filtered: return [] tokens = [VOCAB["TICK"]] for event in filtered: tokens.extend(self.encode_event(event)) return tokens
From codec.py:71-78.All events with the same tick are encoded after a single TICK token:
def encode_episode( self, events_by_tick: dict[int, list[Event]], states_by_tick: dict[int, SnakeState],) -> list[int]: tokens = [VOCAB["BOS"]] max_tick = max(states_by_tick.keys()) if states_by_tick else 0 for tick in range(max_tick + 1): # Snapshot at tick 0, every snapshot_interval, or on rule-effect events need_snapshot = ( tick == 0 or (tick % self.snapshot_interval == 0) or any( e.salience >= Salience.RULE_EFFECT for e in events_by_tick.get(tick, []) ) ) if need_snapshot and tick in states_by_tick: tokens.extend(self.encode_snapshot(states_by_tick[tick])) if tick in events_by_tick: tick_tokens = self.encode_tick_events(events_by_tick[tick]) tokens.extend(tick_tokens) tokens.append(VOCAB["EOS"]) return tokens
This hybrid approach mirrors video codec design (I-frames + P-frames):
Compression
Delta events are compact. MOVE X7 Y8 is 3 tokens, while a full state snapshot is 11 tokens.Pure delta encoding would be even more compact, but has problems (see next).
Error Recovery
Pure delta encoding accumulates errors. If the model predicts one wrong move, all future positions are offset.Periodic snapshots reset the state, allowing the model to recover from mistakes.
Long-Range Context
Snapshots give the transformer absolute position context. Without them, the model must integrate all deltas from the start of the sequence.With a 64-token context window, the model can only “see” ~4-8 game ticks back. Snapshots provide grounding.
Conditional Rules
Some events trigger snapshots immediately. From codec.py:92-97, any event with salience >= Salience.RULE_EFFECT forces a snapshot.This ensures the model sees the full state after important transitions (eating food, dying, etc.).
Snapshot interval is configurable (snapshot_interval=16 in the current implementation). More snapshots = more context, fewer snapshots = better compression.
def decode(self, tokens: list[int]) -> list[dict]: """Decode token sequence into a list of parsed records for validation.""" names = [ID_TO_TOKEN[t] for t in tokens] records: list[dict] = [] i = 0 while i < len(names): tok = names[i] if tok == "BOS": records.append({"type": "BOS"}) i += 1 elif tok == "SNAP": # Parse 11-token snapshot rec = {"type": "SNAP"} if i + 10 < len(names): rec["player_x"] = names[i + 2] rec["player_y"] = names[i + 3] # ... etc ... records.append(rec) i += 11 elif tok == "MOVE": rec = {"type": "MOVE"} if i + 2 < len(names): rec["x"] = names[i + 1] rec["y"] = names[i + 2] records.append(rec) i += 3 # ... etc ... return records
From codec.py:109-179.The decoder parses multi-token events back into structured records for the validator to check.
