Skip to content

Entities

The concrete things that live on a grid: Player, Goal, Wall, Key, Door, Lava, Ball, Box.

Each is a frozen flax.struct pytree built by composing the mixins in navix.components (Positionable, Directional, Openable, ...). All fields are batched: state.entities["key"] is a single Key struct holding every key in the environment, with the instance count as the leading axis (key.position is i32[n_keys, 2]). Index into a batch with entity[i].

Entities also expose derived, per-instance properties the engine reads: walkable, transparent, tag, sprite, symbolic_state.

Bases: Entity, Pickable, HasColour, Stochastic

A blocking obstacle that is also pickable. Not walkable, transparent. Colliding with the player fires a (BALL, HIT) event (terminations.on_ball_hit).

Under the default transitions.stochastic_transition, every ball moves one random step each timestep (transitions.update_balls), so it acts as a wandering hazard. An environment that wants a static ball - a pickup target or decoy - must use transitions_fn=transitions.deterministic_transition instead (as GoToObject / Fetch / PutNear / BlockedUnlockPickup do).

id (from Pickable) is the pickup identity, matched against player.pocket; probability (from Stochastic) is unused by Ball.

Parameters:

Name Type Description Default
position Array

(row, col), i32[2] (or batched).

 required
colour Array

palette index (see HasColour).

 required
probability Array

unused by Ball; pass 1.0.

 required
id Array

i32[] >= 1 pickup identity.

 required

Returns:

Name Type Description
Ball Ball

the entity.

Bases: Entity, Pickable, HasColour, Holder

A pickable container. Not walkable, transparent. open (the toggle action) while facing it removes the box and, if its pocket holds a Key's id, reveals that key at the box's former cell (matching MiniGrid's Box.toggle). Used by ObstructedMaze to hide keys.

Two separate id fields: id (from Pickable) is the box's own pickup identity, matched against player.pocket; pocket (from Holder) is the id of the item hidden inside.

Parameters:

Name Type Description Default
position Array

(row, col), i32[2] (or batched).

 required
colour Array

palette index (see HasColour).

 required
id Array

i32[] >= 1, the box's own pickup identity.

 required
pocket Array

id of the contained item, or EMPTY_POCKET_ID (-1) for an empty box.

 required

Returns:

Name Type Description
Box Box

the entity.

Named values for Directional.direction: EAST=0, SOUTH=1, WEST=2, NORTH=3 (clockwise). rotate_cw adds 1 (mod 4).

Bases: Entity, Openable, HasColour

A door in a wall. While closed it is not walkable and not transparent; once open it is both. Opening needs the open action while facing it and, if requires != -1, the matching Key in the pocket (which is then consumed and requires set to -1). navix doors do not re-close.

bool[*shape] - True while the door still needs a key (requires != -1). Becomes False once unlocked.

Returns an integer array encoding the symbolic state of the door:

  • 0: Door is open
  • 1: Door is closed but not locked
  • 2: Door is closed and locked (requires a key or tool)

Examples:

  • If open = 1 and locked = 0: symbolic_state = 0 (open)
  • If open = 0 and locked = 0: symbolic_state = 1 (closed, not locked)
  • If open = 0 and locked = 1: symbolic_state = 2 (closed and locked)

Parameters:

Name Type Description Default
position Array

(row, col), i32[2] (or batched).

 required
requires Array

Key.id needed to unlock, or -1 for an unlocked door.

 required
colour Array

palette index (see HasColour).

 required
open Array

0 closed, 1 open.

 required

Returns:

Name Type Description
Door Door

the entity.

Bases: PyTreeNode

The string keys used in state.entities (a dict[str, Entity]). Use Entities.KEY etc. rather than the bare literal "key" so a rename is caught statically.

Bases: Positionable, HasTag, HasSprite

Base of every concrete entity: has a position, a tag and a sprite. Subclasses add more mixins and fill in the derived properties below. Build one with the subclass's create.

The class name ("Key", "Door", ...).

Number of batch dimensions (len(self.shape)) - 0 for a single instance, 1 for a flat batch.

The batch shape - the entity's axes excluding each field's own trailing axes. () for a single instance, (n,) for a batch of n (position is then (n, 2)).

i32[*shape] - the third channel of a symbolic observation for this entity (e.g. a door's open/closed/locked; 0 for entities with no internal state).

Raises:

Type Description
NotImplementedError

on the base class.

bool[*shape] - does line of sight pass through this cell? Feeds the first-person view cone (False blocks vision).

Raises:

Type Description
NotImplementedError

on the base class.

bool[*shape] - can the player step onto this entity's cell? (False for walls and closed doors, True for goal/lava/floor.)

Raises:

Type Description
NotImplementedError

on the base class.

__getitem__(idx)

Selects instance(s) from the batch - key[0] is the first key, key[mask] the masked subset - by indexing every field's leading axis.

The integer tag each entity type takes in a categorical observation and in the first channel of a symbolic one. uint8 scalars. The values are not contiguous (there is no 3) - treat them as opaque ids, and MAX_CATEGORICAL_VALUE (in environments.environment) as the count the observation Space uses. UNKNOWN (0) is also the value of a cell that has not been seen in a first-person observation.

Bases: Entity, HasColour, Stochastic

The target cell. Walkable and transparent. Reaching it fires a (GOAL, REACH) event with probability probability (1.0 in the standard tasks) - rewards.on_goal_reached / terminations.on_goal_reached react to it.

Parameters:

Name Type Description Default
position Array

(row, col), i32[2] (or batched).

 required
probability Array

f32[] in [0, 1] - chance the reward fires on contact (1.0 for the standard tasks). Colour is fixed to green.

 required

Returns:

Name Type Description
Goal Goal

the entity.

Bases: Entity, Pickable, HasColour

A pickable key. Not walkable, transparent. pickup puts its id in the player's pocket; a Door whose requires equals that id can then be opened, consuming the key. Its colour matches the door it opens.

Parameters:

Name Type Description Default
position Array

(row, col), i32[2] (or batched).

 required
colour Array

palette index (see HasColour).

 required
id Array

i32[] >= 1, matched against Door.requires.

 required

Returns:

Name Type Description
Key Key

the entity.

Bases: Entity

A hazard cell. Walkable and transparent (the player can step onto it), but doing so fires a (LAVA, FALL) event that terminations.on_lava_fall turns into a TERMINATION - stepping in ends the episode with no reward.

Parameters:

Name Type Description Default
position Array

(row, col), i32[2] (or batched).

 required

Returns:

Name Type Description
Lava Lava

the entity.

Bases: Entity, Directional, Holder

The agent. Has a direction it faces and a pocket holding at most one Pickable. navix is single-agent, so state.entities["player"] is a batch of one.

Parameters:

Name Type Description Default
position Array

(row, col), i32[2] (or batched).

 required
direction Array

facing, i32[] in 0..3 (see Directions).

 required
pocket Array

carried item id, or EMPTY_POCKET_ID (-1).

 required

Returns:

Name Type Description
Player Player

the entity.

Bases: Entity, HasColour

An impassable, opaque cell. Not walkable, not transparent. The grid border is walls; interior walls form rooms and corridors.

Parameters:

Name Type Description Default
position Array

(row, col) of each wall, i32[n, 2]. Colour is fixed to grey.

 required

Returns:

Name Type Description
Wall Wall

the batch of walls.