Skip to content

Native Gridworld Observations

src/environments/gridworlds/native.py provides two policy adapters for Coins, Chemistry, Harvest, Territory, and Gift Refinements:

  • NativeObjectObservationWrapper flattens structured observations without rendering and is the training default.
  • NativeRGBObservationWrapper normalizes rendered frames for play, inspection, and visual comparisons.

Factory Modes

The domain factories default to render_mode=None. That returns the native structured observation unchanged and performs no rendering. With flatten_observations=True, the factory installs the object adapter. The flag is rejected in RGB/human render modes.

Experiment specs use the flattened object path. It iterates each Box field in the native Dict, flattens it, normalizes elements with finite unequal bounds to [0, 1], preserves unbounded or constant elements, and concatenates the fields into one float32 vector. Matrix-valued fields stay in the policy vector; only scalar/vector side channels are copied into infos to avoid duplicating object grids.

Visual factories default to fully_observable=True. The native substrate uses global observation mode and the adapter calls env.state() once per step, then returns the same processed world frame to every active agent. Set fully_observable=False for local per-agent RGB observations.

Preprocessing

rgb_preprocessing="tile_scale" is the default. It average-pools each spatial axis by four and normalizes pixels to float32 in [0, 1]:

Domain Native world RGB Default policy RGB
Coins 136 x 136 x 3 34 x 34 x 3
Chemistry 112 x 200 x 3 28 x 50 x 3
Harvest 144 x 192 x 3 36 x 48 x 3
Territory 168 x 168 x 3 42 x 42 x 3
Gift Refinements 216 x 216 x 3 54 x 54 x 3

rgb_preprocessing="native" preserves native resolution while normalizing. An explicit rgb_resize=(height, width) overrides either default; the input dimensions must divide evenly into the requested output. Local visual mode defaults to 22 x 22 x 3 unless rgb_resize is supplied.

Side Channels

The adapter copies every non-RGB, non-mapping native observation field into info. Domain factories namespace these keys, including:

  • chemistry.collective_reward
  • coins.mismatched_coin_collected_by_partner and coins.collective_reward
  • harvest.ready_to_shoot and harvest.collective_reward
  • territory.ready_to_shoot and territory.collective_reward
  • gift_refinements.ready_to_shoot, gift_refinements.inventory, and gift_refinements.collective_reward

Array values are copied as float32; scalar values become Python floats. The collective reward key is overwritten after every step with the sum of native per-agent rewards so label code sees one consistent value.

Temporal Wrapper Ordering

Install either native adapter below BoolRewardWrapper. The temporal wrapper then appends exactly one monitor-state component to the already-flat object vector or flattened RGB tensor. This ordering preserves the final-component invariant required by counterfactual replay. It also keeps reward side channels available to label mixins without requiring RGB generation during training.