Rewards

Reward functions: the scalar reward for one transition.

An Environment's reward_fn has the signature shared with navix.terminations and navix.events:

fn(prev_state: State, action: Array, state: State) -> Array

• prev_state is $s_t$, action is $a_t$, state is $s_{t+1}$. Some functions need prev_state to reward a change this step; most only read state.
• The return is a scalar f32[]. Environment.reward_space bounds it ([-1, 1] by default). Positive functions here return 1.0 on the rewarded event and 0.0 otherwise; the *_cost functions return a small negative shaping term every step.

compose reduces several into one (summed by default). DEFAULT_TASK is just on_goal_reached - +1 at the goal, no per-step shaping; add a time_cost yourself if you want to reward faster solutions.

DEFAULT_TASK = on_goal_reached module-attribute

The reward_fn an Environment uses unless overridden: +1.0 on reaching the goal, 0.0 every other step - no per-step shaping. Compose time_cost in yourself if you want to reward faster solutions.

action_cost(prev_state, action, new_state, cost=0.01)

Deprecated alias of time_cost.

It used to exempt the action at index 6 (done in MINIGRID_ACTION_SET), but a reward function has no way to know which action set an environment uses, so the exemption was action-set-dependent and wrong for any non-default set. Every action now costs cost - identical to time_cost - so use that instead.

Parameters:

Name	Type	Description	Default
prev_state	State	$s_t$ (unused).	required
action	Array	the integer action taken (unused).	required
new_state	State	$s_{t+1}$ (unused).	required
cost	float	the per-step penalty magnitude. Default 0.01.	0.01

Returns:

Name	Type	Description
Array	Array	f32[], always -cost.

compose(*reward_functions, operator=jnp.sum)

Combines several reward functions into one.

Parameters:

Name	Type	Description	Default
*reward_functions	Callable	reward functions to combine, each (prev_state, action, state) -> f32[].	()
operator	Callable	reduces the stacked f32[len(reward_functions)] results to a scalar f32[]. Default jnp.sum - the rewards add up, e.g. compose(on_goal_reached, time_cost) for +1 at the goal minus a small per-step cost.	sum

Returns:

Name	Type	Description
Callable	Callable	a single (prev_state, action, state) -> f32[]
	Callable	function.

free(prev_state, action, state)

Always 0.0 - the reward-free setting, for unsupervised or exploration-driven training where only the transition dynamics matter.

Returns:

Name	Type	Description
Array	Array	f32[], always 0.0.

on_box_pickup(prev_state, action, state)

A reward function that returns 1 when any box is picked up this step, and 0 otherwise.

Parameters:

Name	Type	Description	Default
state	State	The current state of the game.	required

Returns:

Name	Type	Description
Array	Array	A scalar array f32[] with value 1 if a box was picked
	Array	up, and 0 otherwise.

on_door_done(prev_state, action, state)

A reward function that returns a positive value when the agent uses the action done in front of a door.

Parameters:

Name	Type	Description	Default
state	State	The current state of the game.	required

Returns:

Name	Type	Description
Array	Array	A scalar array f32[] with value 1 if the agent uses the action done in front of a door, and 0 otherwise.

on_door_open(prev_state, action, state)

A reward function that returns 1 when any door is opened this step, and 0 otherwise - unlike on_door_done, no state.mission target is needed; any door opening counts.

Parameters:

Name	Type	Description	Default
state	State	The current state of the game.	required

Returns:

Name	Type	Description
Array	Array	A scalar array f32[] with value 1 if a door was opened,
	Array	and 0 otherwise.

on_goal_reached(prev_state, action, state)

A reward function that returns 1 when the goal is reached, and 0 otherwise.

Parameters:

Name	Type	Description	Default
state	State	The current state of the game.	required

Returns:

Name	Type	Description
Array	Array	A scalar array f32[] with value 1 if the goal is reached, and 0 otherwise.

on_memory_success(prev_state, action, state)

Memory's reward: 1 if the player reached the target position, 0 otherwise (including on failure). Deliberately flat, not MiniGrid's step-count-shaped 1 - 0.9 * (step_count / max_steps) - matches navix's existing on_goal_reached convention, itself already the same simplification versus real MiniGrid's Goal reward, kept here for consistency rather than a one-off shaped reward unique to this environment.

Parameters:

Name	Type	Description	Default
prev_state	State	The previous state of the game.	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 scalar array f32[].

on_ordered_doors_success(prev_state, action, state)

RedBlueDoors' reward: 1 if the blue door was opened this step while red was already open, 0 otherwise (including the failure case of opening blue first).

Parameters:

Name	Type	Description	Default
prev_state	State	The previous state of the game.	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 scalar array f32[].

on_put_near_success(prev_state, action, state)

PutNear's reward: 1 if the carried object was dropped within Chebyshev distance 1 of the second mission target, 0 otherwise.

Parameters:

Name	Type	Description	Default
prev_state	State	The previous state of the game.	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 scalar array f32[].

on_target_done(prev_state, action, state)

GoToObject's reward: 1.0 if the done action was taken while the player is orthogonally adjacent to the mission's target object (facing it is not required; see events.on_target_done), else 0.0.

Returns:

Name	Type	Description
Array	Array	f32[].

on_target_fetched(prev_state, action, state)

Fetch's reward: 1 if the mission's target object was the one picked up this step, 0 otherwise (including picking up the wrong one, which still ends the episode via terminations. on_any_target_pickup).

Parameters:

Name	Type	Description	Default
prev_state	State	The previous state of the game.	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 scalar array f32[].

time_cost(prev_state, action, new_state, cost=0.01)

A flat -cost on every step. Compose it with a goal reward (compose(on_goal_reached, time_cost)) to make shorter successful episodes score higher.

Parameters:

Name	Type	Description	Default
prev_state	State	$s_t$ (unused).	required
action	Array	the integer action taken (unused).	required
new_state	State	$s_{t+1}$ (unused).	required
cost	float	the per-step penalty magnitude. Default 0.01.	0.01

Returns:

Name	Type	Description
Array	Array	f32[], always -cost.

wall_hit_cost(prev_state, action, state, cost=0.01)

-cost on any step where the player moved into a wall this step (detected via events.on_wall_hit), 0.0 otherwise. Opt-in shaping for tasks that want to discourage bumping walls; same sign convention as time_cost.

Parameters:

Name	Type	Description	Default
prev_state	State	$s_t$ (unused).	required
action	Array	the integer action taken (unused).	required
state	State	$s_{t+1}$ - read for the wall-hit event.	required
cost	float	the penalty magnitude on a wall hit. Default 0.01.	0.01

Returns:

Name	Type	Description
Array	Array	f32[] - -cost on a wall hit, else 0.0.