diff --git a/Entity-Management.md b/Entity-Management.md index 8abaf2b..f5699cb 100644 --- a/Entity-Management.md +++ b/Entity-Management.md @@ -21,7 +21,6 @@ Entities are game objects that implement behavior and live on Grids. While Grids **Related Issues:** - [#115](../../issues/115) - SpatialHash for fast queries (Open) - [#117](../../issues/117) - Memory Pool for entities (Open) -- [#16](../../issues/16) - Entity knowledge contents (Open) --- @@ -186,13 +185,69 @@ for state in entity.gridstate: print(f"visible={state.visible}, discovered={state.discovered}") # Access specific cell state -state = entity.at(x, y) +state = entity.at((x, y)) if state.visible: print("Entity can currently see this cell") elif state.discovered: print("Entity has seen this cell before") ``` +### GridPointState.point - Accessing Cell Data (#16) + +The `GridPointState.point` property provides access to the underlying `GridPoint` from an entity's perspective: + +```python +state = entity.at((x, y)) + +# If entity has NOT discovered this cell, point is None +if not state.discovered: + print(state.point) # None - entity doesn't know what's here + +# If entity HAS discovered the cell, point gives access to GridPoint +if state.discovered: + point = state.point # Live reference to GridPoint + print(f"walkable: {point.walkable}") + print(f"transparent: {point.transparent}") + print(f"entities here: {point.entities}") # List of entities at cell +``` + +**Key behaviors:** +- Returns `None` if `discovered=False` (entity has never seen this cell) +- Returns live `GridPoint` reference if `discovered=True` +- Changes to the `GridPoint` are immediately visible through `state.point` +- This is intentionally **not** a cached copy - for historical memory, implement your own system in Python + +**Use case - Entity perspective queries:** + +```python +def can_entity_see_walkable_path(entity, x, y): + """Check if entity knows this cell is walkable.""" + state = entity.at((x, y)) + if state.point is None: + return None # Unknown - entity hasn't discovered it + return state.point.walkable + +def get_known_entities_at(entity, x, y): + """Get entities at cell if entity has discovered it.""" + state = entity.at((x, y)) + if state.point is None: + return [] # Entity doesn't know this cell + return state.point.entities +``` + +**Ground truth access:** + +If you need the actual cell data regardless of entity perspective, access it through the grid directly: + +```python +# Entity perspective (respects discovered state) +state = entity.at((x, y)) +point_or_none = state.point + +# Ground truth (always returns GridPoint) +point = entity.grid.at(x, y) +``` + --- ## EntityCollection @@ -403,6 +458,12 @@ def entities_at(grid, x, y): return [e for e in grid.entities if e.x == x and e.y == y] ``` +**New in v1.0:** Use `GridPoint.entities` for cell-based queries: +```python +# O(n) but more convenient - filters grid.entities by position +entities_here = grid.at(x, y).entities +``` + **Workarounds:** - Keep entity counts reasonable (< 200 for best performance) - Use timer callbacks for AI updates, not per-frame