Grid Representation: Entity

BaseEntity(entity_id=new_entity_id()) dataclass

Minimal base for mutable grid state entities.

iter_components()

Yield (store_name, component) for non-None ECS/effect components present on this object.

iter_nested_objects()

Yield (store_name, list[BaseEntity]) for non-empty nested lists.

iter_reference_fields()

Yield (store_name, ref) for non-None cross-entity references.

Entity(entity_id=new_entity_id(), agent=None, appearance=None, blocking=None, collectible=None, collidable=None, cost=None, damage=None, exit=None, health=None, inventory=None, key=None, lethal_damage=None, locked=None, moving=None, pathfinding=None, portal=None, pushable=None, requirable=None, rewardable=None, status=None, immunity=None, phasing=None, speed=None, time_limit=None, usage_limit=None, inventory_list=_empty_objs(), status_list=_empty_objs(), pathfind_target_ref=None, pathfinding_type=None, portal_pair_ref=None) dataclass

Bases: BaseEntity

Generic mutable entity with optional components, nested objects, and references.

Games may subclass BaseEntity directly for tighter types, while this generic Entity remains a flexible builder-friendly shape.

copy_entity_components(src, dst, include_nested=True, include_refs=True, preserve_entity_id=False)

Copy present fields from src to dst:

• Components/effects: all keys in FIELD_TO_COMPONENT are copied when present on both src and dst.
• Nested lists: fields in NESTED_FIELDS (shallow copies) when include_nested=True and present.
• References: fields in REFERENCE_FIELD_TO_COMPONENT when include_refs=True and present.

Parameters:

Name	Type	Description	Default
src	BaseEntity	Source entity.	required
dst	BaseEntity	Destination entity.	required
include_nested	bool	Whether to copy nested lists.	True
include_refs	bool	Whether to copy reference fields.	True
preserve_entity_id	bool	Whether to copy the entity_id from src to dst.	False

Returns:

Type	Description
BaseEntity	dst (for chaining).

validate_entity(obj)

Validate component, nested-list, and reference field types.