Events
Event detectors: given a transition, did some notable thing happen?
An event is a thing that occurred during one step - the goal was
reached, a ball hit the player, a door was unlocked. The transition
pipeline records events into state.events (an EventsManager, reset
every step), and the functions here read that record - together with
prev_state/action/state - to answer yes/no questions about the
step. navix.rewards and navix.terminations are thin, dtype-coercing
wrappers around these; this module is where each condition's exact
semantics live.
Every function has the same signature,
fn(prev_state: State, action: Array, state: State) -> Array
returning a boolean scalar bool[]. Not all three arguments are used by
every function - some only need state, a few need prev_state to
detect a change this step (the event record alone can't say whether a
flag just flipped or was already set). Each function's docstring marks
the arguments it ignores.
DONE_ACTION = jnp.asarray(actions.MINIGRID_ACTION_SET.index(actions.done))
module-attribute
The integer that means actions.done in the default action set -
used by detectors like on_target_done that care which action was
taken. Only correct for environments using MINIGRID_ACTION_SET.
DROP_ACTION = jnp.asarray(actions.MINIGRID_ACTION_SET.index(actions.drop))
module-attribute
The integer that means actions.drop in the default action set (see
DONE_ACTION).
TOGGLE_ACTION = jnp.asarray(actions.MINIGRID_ACTION_SET.index(actions.toggle))
module-attribute
The integer that means actions.toggle in the default action set
(see DONE_ACTION).
on_any_target_pickup(prev_state, action, state)
Fetch's termination trigger: MiniGrid's real FetchEnv ends the
episode on any Key/Ball pickup, right or wrong - only the
reward differs (see on_target_fetched). Also reused by PutNear
(below), which additionally places Box - safe for Fetch either
way, since on_box_pickup is always False for an environment that
never constructs any Box entities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar. |
on_ball_hit(prev_state, action, state)
Checks whether the ball has hit something using the ball_hit event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar indicating whether any ball hit the player |
Array
|
this step. |
on_ball_pickup(prev_state, action, state)
Checks whether any ball was picked up using the ball_pickup event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar indicating whether any ball was picked up |
Array
|
this step. |
on_box_pickup(prev_state, action, state)
Checks whether any box was picked up using the box_pickup event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar indicating whether any box was picked up |
Array
|
this step. |
on_door_done(prev_state, action, state)
Checks whether the action done has been called in front of a Door object with the correct colour.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean array indicating whether the action |
on_door_open(prev_state, action, state)
Checks whether any door was opened using the door_opening event -
unlike on_door_done, this doesn't need a state.mission target;
any door opening (unlocking or not) counts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar indicating whether any door was opened |
Array
|
this step. |
on_goal_reached(prev_state, action, state)
Checks whether the goal has been reached using the goal_reached event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar indicating whether the goal has been reached |
Array
|
by any goal instance this step. |
on_key_pickup(prev_state, action, state)
Checks whether any key was picked up using the key_pickup event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar indicating whether any key was picked up |
Array
|
this step. |
on_lava_fall(prev_state, action, state)
Checks whether the lava has fallen using the lava_fall event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar indicating whether the lava has fallen for |
Array
|
any lava instance this step. |
on_memory_failure(prev_state, action, state)
Memory's fail condition: the player has walked onto the cell
adjacent to the wrong object. failure_pos is never stored as
its own mission slot - it's always the mirror image of state.
mission's (success) position across the hallway's centre row
(state.grid.shape[0] // 2, verified against MiniGrid's actual
_gen_grid: both positions sit at height // 2 - 1/height // 2
+ 1), so it's derived here instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar. |
on_memory_success(prev_state, action, state)
Memory's win condition (verified against MiniGrid's actual
MemoryEnv.step): the player has walked onto state.mission's
target position - pure position equality, no done action, no
facing (the target cell is an ordinary walkable floor cell
adjacent to the matching object, not the object's own cell).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar. |
on_ordered_doors_failure(prev_state, action, state)
RedBlueDoors' fail condition: doors[1] (blue) transitions
closed -> open exactly this step, while doors[0] (red) was not
already open - i.e. blue was opened first (or simultaneously).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action. |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar. |
on_ordered_doors_success(prev_state, action, state)
RedBlueDoors' win condition: doors[1] (blue - see
RedBlueDoors._reset's fixed construction order, no colour search
needed) transitions closed -> open exactly this step, while
doors[0] (red) was already open in prev_state. This is why
prev_state is needed here even though most of this module's
functions ignore it - the win condition is about the order two
doors were opened in, which no single state can encode on its own
(events are reset every step, and a Door.open flag alone can't
tell you whether it just changed or has been open for a while).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action. |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar. |
on_put_near_drop_attempted(prev_state, action, state)
PutNear's termination trigger for a drop: MiniGrid's real
PutNearEnv ends the episode on any genuine drop attempt (a drop
action while actually holding something) - success or failure is
determined separately by on_put_near_success.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action. |
required |
action
|
Array
|
The action taken by the player. |
required |
state
|
State
|
The current state of the game (unused). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar. |
on_put_near_success(prev_state, action, state)
PutNear's win condition: a genuine drop attempt (see
on_put_near_drop_attempted) that actually placed the item (the
player's pocket went from holding something to empty - actions.
drop only clears the pocket on a successful drop, see #189) at a
cell within Chebyshev distance 1 of state.mission[1]'s tracked
position (the "object to drop near"). Note: by the time a drop
action is reached without the episode already having ended via
on_put_near_wrong_pickup, the held item is guaranteed to be the
right one (state.mission[0]'s object) - wrong pickups end the
episode immediately, so no separate "is this the right item" check
is needed here.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action. |
required |
action
|
Array
|
The action taken by the player. |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar. |
on_put_near_wrong_pickup(prev_state, action, state)
PutNear's fail-on-pickup condition: a Key/Ball/Box pickup
happened this step, but not at state.mission's tracked position
(the "object to carry") - matches MiniGrid's real PutNearEnv,
which ends the episode immediately if the wrong object is picked up.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar. |
on_target_done(prev_state, action, state)
GoToObject's win condition: the done action was taken while
the player is orthogonally adjacent to the target named by
state.mission - direction/facing is not checked. This is a pure
position test, (row == target_row and |col - target_col| == 1) or
(col == target_col and |row - target_row| == 1), matching
MiniGrid's GoToObjectEnv.step.
state.mission must be non-empty (an AssertionError otherwise).
"The done action" is action == DONE_ACTION, i.e. only meaningful
for an environment using the default action set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
$s_t$ (unused). |
required |
action
|
Array
|
the integer action taken. |
required |
state
|
State
|
$s_{t+1}$ - source of the player and target positions. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
|
on_target_fetched(prev_state, action, state)
Fetch's success signal: a Key/Ball pickup event fired this
step at state.mission's tracked position - Event.position keeps
the picked-up instance's real (pre-discard-pile) position, and
positions are unique per instance, so this alone identifies whether
the specific target object (not just any object) was picked up.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar. |
on_wall_hit(prev_state, action, state)
Checks whether the wall has been hit using the wall_hit event -
either an actual Wall entity, or the grid boundary/a non-walkable
empty cell with no entity there (see navix.states.GRID).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player (unused). |
required |
state
|
State
|
The current state of the game. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar indicating whether a wall was hit this |
Array
|
step. |
on_wrong_toggle(prev_state, action, state)
GoToObject's real fail condition (verified against MiniGrid):
calling toggle at all, regardless of what's in front, immediately
fails the episode.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prev_state
|
State
|
The state before this step's action (unused). |
required |
action
|
Array
|
The action taken by the player. |
required |
state
|
State
|
The current state of the game (unused). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Array |
Array
|
A boolean scalar. |