john/McRogueFace

Fork 0

Entity `step()` callback — Python-side turn handler #299

New issue

Closed

opened 2026-03-15 00:30:45 +00:00 by john · 1 comment

john commented

2026-03-15 00:30:45 +00:00

Owner

Summary

Add a step callback to entities, called by the turn system when a behavior triggers or when using custom behavior. Supports both callback assignment and subclass method override, following existing patterns (on_click, on_key, etc.).

Signature

def step(trigger: mcrfpy.Trigger, data):
    """
    trigger: Trigger.DONE, Trigger.BLOCKED, or Trigger.TARGET
    data: depends on trigger type:
      - DONE: cell arrived at (Vector), or None for sleep/custom
      - BLOCKED: (blocked_cell: Vector, blocking_entity: Entity) tuple
      - TARGET: the spotted Entity
    """

Usage patterns

Callback assignment

def my_step(trigger, data):
    if trigger == mcrfpy.Trigger.TARGET:
        # chase the spotted entity
        pass

entity.step = my_step

Subclass method

class Guard(mcrfpy.Entity):
    def step(self, trigger, data):
        if trigger == mcrfpy.Trigger.TARGET:
            player = data
            self.set_behavior("seek", dijkstra=player_map)
        elif trigger == mcrfpy.Trigger.DONE:
            self.set_behavior("patrol", points=self.patrol_route)

Implementation notes

Must respect Python object cache / subclass identity (#266)
Both entity.step = func and subclass def step() patterns must work
Follow the same C++/Python boundary pattern as on_click, on_key
When step() is called and returns without setting a new behavior, the entity reverts to default_behavior (default: idle)
If no step callback is set and no subclass override exists, the trigger is silently ignored and the entity reverts to default_behavior

entity.default_behavior  # str, default "idle" — revert target after step() completes

Dependencies

#298 (mcrfpy.Trigger enum)
#266 (Python subclass identity preservation)

Files likely affected

src/UIEntity.h/cpp — add step callback storage, default_behavior property
src/UIEntityPyMethods.h — Python getter/setter for step

## Summary Add a `step` callback to entities, called by the turn system when a behavior triggers or when using `custom` behavior. Supports both callback assignment and subclass method override, following existing patterns (`on_click`, `on_key`, etc.). ## Signature ```python def step(trigger: mcrfpy.Trigger, data): """ trigger: Trigger.DONE, Trigger.BLOCKED, or Trigger.TARGET data: depends on trigger type: - DONE: cell arrived at (Vector), or None for sleep/custom - BLOCKED: (blocked_cell: Vector, blocking_entity: Entity) tuple - TARGET: the spotted Entity """ ``` ## Usage patterns ### Callback assignment ```python def my_step(trigger, data): if trigger == mcrfpy.Trigger.TARGET: # chase the spotted entity pass entity.step = my_step ``` ### Subclass method ```python class Guard(mcrfpy.Entity): def step(self, trigger, data): if trigger == mcrfpy.Trigger.TARGET: player = data self.set_behavior("seek", dijkstra=player_map) elif trigger == mcrfpy.Trigger.DONE: self.set_behavior("patrol", points=self.patrol_route) ``` ## Implementation notes - Must respect Python object cache / subclass identity (#266) - Both `entity.step = func` and subclass `def step()` patterns must work - Follow the same C++/Python boundary pattern as `on_click`, `on_key` - When `step()` is called and returns without setting a new behavior, the entity reverts to `default_behavior` (default: `idle`) - If no `step` callback is set and no subclass override exists, the trigger is silently ignored and the entity reverts to `default_behavior` ## Related properties ```python entity.default_behavior # str, default "idle" — revert target after step() completes ``` ## Dependencies - #298 (`mcrfpy.Trigger` enum) - #266 (Python subclass identity preservation) ## Files likely affected - `src/UIEntity.h/cpp` — add `step` callback storage, `default_behavior` property - `src/UIEntityPyMethods.h` — Python getter/setter for `step`

john referenced this issue

2026-03-15 00:31:11 +00:00

Behavior data struct and primitive implementations #300

john referenced this issue

2026-03-15 00:31:43 +00:00

grid.step() — turn manager for entity behaviors #301

john added a new dependency

2026-03-15 00:32:48 +00:00

#298 mcrfpy.Trigger enum — behavior trigger type identifiers

john added a new dependency

2026-03-15 00:32:54 +00:00

#300 Behavior data struct and primitive implementations

john referenced this issue

2026-03-15 20:18:30 +00:00

mcrfpy.Trigger enum — behavior trigger type identifiers #298

john commented

2026-03-15 20:18:33 +00:00

Author

Owner

Roadmap context

Part of the Grid & Entity Overhaul Roadmap (docs/GRID_ENTITY_OVERHAUL_ROADMAP.md), Phase 2 (Entity Data Model Extensions).

Must respect Python subclass identity (#266 pattern). Both entity.step = func and subclass def step(self, trigger, data) patterns must work — follow the existing on_click/on_key callback patterns.

## Roadmap context Part of the Grid & Entity Overhaul Roadmap (`docs/GRID_ENTITY_OVERHAUL_ROADMAP.md`), **Phase 2** (Entity Data Model Extensions). Must respect Python subclass identity (#266 pattern). Both `entity.step = func` and subclass `def step(self, trigger, data)` patterns must work — follow the existing `on_click`/`on_key` callback patterns.

john referenced this issue from a commit

2026-03-16 11:21:02 +00:00

Phase 2: Entity data model extensions for behavior system

john closed this issue

2026-03-16 11:21:02 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks

#300 Behavior data struct and primitive implementations

john/McRogueFace

Depends on

#298 mcrfpy.Trigger enum — behavior trigger type identifiers

john/McRogueFace

Reference

john/McRogueFace#299

No description provided.

Rows
Columns

Entity step() callback — Python-side turn handler #299

Summary

Signature

Usage patterns

Callback assignment

Subclass method

Implementation notes

Related properties

Dependencies

Files likely affected

Roadmap context

Entity `step()` callback — Python-side turn handler #299