Skip to content

Components

The reusable "capability" mixins that navix.entities compose into concrete entities.

Each Component subclass adds one field (or one abstract property) plus its semantics: Positionable -> position, Directional -> direction, Openable -> requires/open, and so on. An entity like Door is just Positionable + Directional + Openable + HasColour + .... Every field is a JAX array and the leading axis is the entity-instance axis, so a whole batch of doors is one Door struct.

The off-grid (row, col) an entity's position is set to once it has been picked up / consumed. Column -1 is outside every grid, so such an entity renders nowhere and matches no real cell.

The flat patch index that DISCARD_PILE_COORDS maps to; rendering slices it off (patches[:DISCARD_PILE_IDX]).

Holder.pocket / Player.pocket value meaning "carrying nothing".

Sentinel for a "consumed key" slot that has not been used yet.

Directional.direction sentinel for an entity whose facing is irrelevant (it is never used as a rotation).

Bases: PyTreeNode

Base of every capability mixin. A Component is a frozen flax.struct pytree; concrete entities inherit from several at once. Carries no data itself.

Hook for asserting each field has the expected rank (one extra axis when batched). The base implementation does nothing; subclasses may override. Not called on the hot path.

Parameters:

Name Type Description Default
batched bool

whether an extra leading instance axis is expected.

 False

Bases: Component

Entity has a facing direction.

i32[] in 0..3: 0 east, 1 south, 2 west, 3 north (clockwise). Used directly by grid.translate / grid.rotate.

Bases: Component

Entity is drawn/encoded in one of the palette colours.

i32[] index into navix.rendering.registry.PALETTE (0 red, 1 green, 2 blue, 3 purple, 4 yellow, 5 grey). This is the colour channel of a symbolic observation and picks the sprite variant for rgb.

Bases: Component

Entity has an RGB sprite for rgb rendering.

u8[TILE_SIZE, TILE_SIZE, 3] (or with leading instance / direction axes) - the tile drawn for this entity.

Raises:

Type Description
NotImplementedError

on the base class.

Bases: Component

Entity has an integer tag identifying its type in observations.

i32[] - the value this entity's cells take in a categorical observation and the first channel of a symbolic one. Constant per entity type (see entities.EntityIds).

Raises:

Type Description
NotImplementedError

on the base class.

Bases: Component

Entity can carry one Pickable in a pocket (the Player).

i32[] - the Pickable.id currently carried, or EMPTY_POCKET_ID (-1) when empty.

Bases: Component

Entity (a Door) can be opened, possibly after unlocking.

0 closed, 1 open. navix doors do not re-close, so this only ever goes 0 -> 1.

i32[] - the Pickable.id of the key that unlocks this door, or -1 if it needs no key. Set to -1 once the door has been unlocked.

Bases: Component

Entity can be picked up into a pocket (Key, Ball, Box).

i32[] >= 1 - the identity written to player.pocket when this entity is picked up, and matched against Openable.requires.

Bases: Component

Entity has a location on the grid.

(row, col) as i32[2] (or i32[n_instances, 2] batched). DISCARD_PILE_COORDS ((0, -1)) once the entity has been picked up or consumed.

Bases: Component

Entity's reward (e.g. a Goal) is granted only with some probability when reached.

f32[] in [0, 1] - the chance the reward fires on contact. 1.0 for a deterministic goal.

A dataclasses.field that also records the per-instance shape of the array (excluding the leading instance axis) in its metadata, so Component.check_ndim can validate batched vs unbatched structs.

Parameters:

Name Type Description Default
shape tuple[int, ...]

the shape of one instance's value - () for a scalar field, (2,) for a (row, col) position.

 required
**kwargs

forwarded to dataclasses.field (e.g. default_factory).

 {}

Returns:

Type Description

dataclasses.Field: the field descriptor.