Skip to content

Grid Representation: GridState

Mutable grid-based state representation.

The grid_universe.grid.gridstate.GridState dataclass is a first-class, mutable representation for building and editing game states. It provides a simple grid editing API (add/remove/move) and stores the configuration needed for simulation.

GridState and the immutable grid_universe.state.State are complementary representations optimized for different use cases:

  • GridState: Mutable, grid-centric, ideal for authoring and editing
  • State: Immutable, ECS-based, optimized for simulation and stepping

Use grid_universe.grid.factories to create grid_universe.grid.entity.BaseEntity objects conveniently, and grid_universe.grid.convert to convert between representations as needed.

GridState(width, height, movement, objective, seed=None, turn=0, score=0, win=False, lose=False, message=None, turn_limit=None) dataclass

Mutable, grid-centric state representation.

GridState is a first-class representation for building, editing, and reasoning about game states in a spatial, grid-based manner. It stores entities in a 2D grid structure alongside game configuration and metadata.

  • grid[x][y] is a list of grid_universe.grid.entity.BaseEntity instances at that cell.
  • Stores configuration such as movement, objective, seed, and metadata (turn/score/win/lose/etc.).
  • Convert to/from the immutable ECS grid_universe.state.State using grid_universe.grid.convert.to_state / grid_universe.grid.convert.from_state when needed for simulation.

add(pos, obj)

Place an grid_universe.grid.entity.BaseEntity into the cell at pos (x, y).

add_many(items)

Place multiple entities. Each entry is (pos, obj).

clear_cell(pos)

Remove all objects from the cell at pos. Returns the number of removed objects.

move_obj(from_pos, obj, to_pos)

Move a specific entity (by identity) from one cell to another. Returns True if moved (i.e., it was found in the source cell), False otherwise.

objects_at(pos)

Return a shallow copy of the list of objects at pos.

remove(pos, obj)

Remove a specific entity (by identity) from the cell at pos. Returns True if the object was found and removed, False otherwise.

remove_if(pos, predicate)

Remove all objects in the cell at pos for which predicate(obj) is True. Returns the number of removed objects.