Utils: trail

Trail (historic position) utilities.

Provides functions to manage and query the historic trails of entities within the grid universe, allowing systems to track prior positions for purposes such as implementing trail-based mechanics.

add_trail_position(ctx, entity_id, new_pos)

Return new StepContext with entity_id recorded as having entered new_pos.

Idempotent for (entity, position) within an action: repeated additions of the same (entity, tile) pair are harmless due to set semantics.

get_augmented_trail(state, ctx, entity_ids)

Return merged mapping of positions to entity sets (current + historic).

Parameters:

Name	Type	Description	Default
state	State	Current immutable world state containing both live entity positions and the accumulated historic trail mapping of prior positions.	required
entity_ids	PSet[EntityID]	Entity ids whose current position should be merged into the historic trail. Entities absent from state.position are ignored.	required

Returns:

Type	Description
PMap[Position, PSet[EntityID]]	PMap[Position, PSet[EntityID]]: Mapping from grid positions to the persistent set of entity ids that have either previously occupied (historic) or currently occupy that position among the provided tracked entities.