Skip to content

Native Gridworld Substrates

Coins, Chemistry, Commons Harvest, Territory, and Gift Refinements are local PettingZoo ParallelEnv implementations under src/environments/substrates/. They were synchronized from nightly/meltingpot-pz at commit 7d7af52, but this repository has no runtime dependency on DeepMind Melting Pot, Shimmy, dm_env, or Lab2D.

Layering

  • src/environments/substrates/ owns dynamics, structured observations, events, rendering, stochastic termination, and variant configuration.
  • src/environments/gridworlds/<domain>/env.py provides the stable factory and optional flat-object or RGB observation adapters.
  • src/environments/gridworlds/<domain>/mix_in.py turns native rewards, events, infos, and lifecycle state into temporal atoms.
  • src/environments/gridworlds/<domain>/constraints.py attaches one SpecPair per agent through BoolRewardWrapper.

The domain factories accept the historical upstream substrate names. Coins exposes a procedurally generated fixed two-player game, Chemistry supports four metabolic-cycle variants, Harvest supports open, closed, and partnership, Territory supports open, rooms, and inside_out, and Gift Refinements exposes its fixed six-player variant.

Rendering And Observation Contract

  • render_mode=None returns compact structured gymnasium.spaces.Dict observations. Reset, step, and render() do not rasterize an RGB frame.
  • flatten_observations=True in that mode installs NativeObjectObservationWrapper, which normalizes and flattens structured fields into the Box vector required by the trainers.
  • render_mode="rgb_array" and render_mode="human" wrap the substrate with NativeRGBObservationWrapper and return normalized RGB Box observations.
  • state() remains an explicit on-demand global uint8 RGB frame on the base substrate.

Experiment adapters request render_mode=None, flatten_observations=True so training avoids rasterization while still producing the Box values consumed by the neural trainers and temporal wrapper. Inspection callers can leave flattening disabled and interpret categorical values with the base environment's read-only object_observation_ids mapping. Play notebooks use the separate RGB path.

See Native Gridworld Observations for shape, preprocessing, and side-channel details.

Events And Lifecycle

Native step infos carry event dictionaries directly. events_from_infos(...) deduplicates copies shared across per-agent infos before label mixins inspect them. native_lifecycle(...) walks the wrapper chain and distinguishes the configured step-limit timeout from a native stochastic termination.

Both policy adapters preserve relevant scalar side channels in namespaced info keys and derive collective reward as the current sum of per-agent rewards. Label mixins must use these native contracts; do not restore reactive subscriptions or compatibility-wrapper unwrapping from the removed integration.