Core types and data structures used throughout the Game Grammar system for representing game state, events, and actions.
Action
Enum representing directional actions in the game.
from game_grammar.core import Action
class Action(Enum):
UP = "UP"
DOWN = "DOWN"
LEFT = "LEFT"
RIGHT = "RIGHT"
Values
Move down (value: “DOWN”)
Move left (value: “LEFT”)
Move right (value: “RIGHT”)
Salience
Integer enum defining event priority levels for the game-grammar pipeline.
from game_grammar.core import Salience
class Salience(IntEnum):
TICK = 0
MOVEMENT = 1
COLLISION = 2
RULE_EFFECT = 3
PHASE = 4
Values
Lowest priority - time tick events (value: 0)
Movement events (value: 1)
Collision detection events (value: 2)
Rule application effects (value: 3)
Highest priority - phase transitions (value: 4)
Event
Immutable dataclass representing a game event with metadata.
from game_grammar.core import Event, Salience
@dataclass(frozen=True)
class Event:
type: str
entity: str
payload: dict
tick: int
salience: Salience
Fields
The type identifier for this event (e.g., “MOVE”, “COLLISION”, “SCORE”)
The entity this event is associated with (e.g., “snake”, “food”)
Additional event data as a dictionary
The game tick when this event occurred
Priority level for event processing
Event is frozen (immutable) - instances cannot be modified after creation.
Example
from game_grammar.core import Event, Salience
event = Event(
type="COLLISION",
entity="snake",
payload={"position": (5, 5)},
tick=42,
salience=Salience.COLLISION
)
SnakeState
Mutable dataclass representing the complete state of a Snake game.
from game_grammar.core import SnakeState, Action
@dataclass
class SnakeState:
head: tuple[int, int]
body: list[tuple[int, int]]
direction: Action
food: tuple[int, int]
score: int
alive: bool
tick: int
Fields
Current (x, y) position of the snake’s head
body
list[tuple[int, int]]
required
List of (x, y) positions representing the snake’s body segments
Current movement direction of the snake
Current (x, y) position of the food
Current score (typically number of food items eaten)
Whether the snake is still alive (True) or has collided (False)
Current game tick counter
Example
from game_grammar.core import SnakeState, Action
state = SnakeState(
head=(5, 5),
body=[(4, 5), (3, 5)],
direction=Action.RIGHT,
food=(8, 3),
score=2,
alive=True,
tick=0
)
DIR_DELTA
Mapping from Action enum to coordinate deltas for movement.
from game_grammar.core import DIR_DELTA, Action
DIR_DELTA: dict[Action, tuple[int, int]] = {
Action.UP: ( 0, -1),
Action.DOWN: ( 0, 1),
Action.LEFT: (-1, 0),
Action.RIGHT: ( 1, 0),
}
Usage
(0, -1) - Move up decreases y coordinate
(0, 1) - Move down increases y coordinate
(-1, 0) - Move left decreases x coordinate
(1, 0) - Move right increases x coordinate
Example
from game_grammar.core import DIR_DELTA, Action
# Calculate new position
current_pos = (5, 5)
direction = Action.RIGHT
dx, dy = DIR_DELTA[direction]
new_pos = (current_pos[0] + dx, current_pos[1] + dy) # (6, 5)
OPPOSITE
Mapping from each Action to its opposite direction.
from game_grammar.core import OPPOSITE, Action
OPPOSITE: dict[Action, Action] = {
Action.UP: Action.DOWN,
Action.DOWN: Action.UP,
Action.LEFT: Action.RIGHT,
Action.RIGHT: Action.LEFT,
}
Usage
Action.DOWN - Opposite of up is down
Action.UP - Opposite of down is up
Action.RIGHT - Opposite of left is right
Action.LEFT - Opposite of right is left
Example
from game_grammar.core import OPPOSITE, Action
# Prevent 180-degree turns
current_direction = Action.RIGHT
requested_direction = Action.LEFT
if requested_direction == OPPOSITE[current_direction]:
print("Invalid move: cannot reverse direction")
