MPE2
EnvPool implements all twelve scenarios from Farama MPE2 v1.1.1 in C++. This includes simulation, communication, randomization, assignment, and RGB rendering. The official Python package is used only for tests and documentation.
Each pair shows EnvPool on the left and MPE2 on the right after identical actions. Initial state is synchronized once after reset for this comparison.
Available tasks
The observation lengths below are the original lengths in upstream agent order. EnvPool pads shorter observations to the longest length in the scenario. Both discrete and continuous actions are supported for every task.
Task ID |
Players |
Observation lengths |
|---|---|---|
|
8 |
86 for collectors; 84 for deposits |
|
3 |
8 for adversary; 10 for other agents |
|
3 |
4 for Eve; 8 for Bob and Alice |
|
4 |
6 |
|
4 |
8 |
|
2 |
8 for adversary; 19 for agent |
|
2 |
21 |
|
2 |
3 for speaker; 11 for listener |
|
3 |
18 |
|
4 |
16 for adversaries; 14 for agent |
|
1 |
4 |
|
6 |
34 for adversaries; 28 for agents |
Every upstream module name is also registered as an alias, for example
mpe2/simple_spread_v3 and mpe2/collect_treasure_v1. The registry is
generated from the pinned upstream source.
Options
num_envs,batch_size,num_threads, andseeduse the normal EnvPool meanings. A seed sequence can specify one seed per environment.max_episode_stepsdefaults to 25, corresponding to upstreammax_cycles. One step advances every player simultaneously.continuous_actions=Falseselects discrete actions;Trueselects float32 vectors in[0, 1].Nchanges the population in Adversary, Spread, Formation, and Line. The default is taken from the selected upstream scenario.num_good,num_adversaries, andnum_obstaclesconfigure Tag and World Comm. World Comm also supportsnum_foodandnum_forests.num_collectors,num_deposits, andnum_treasuresconfigure Collect Treasure. There may be one to six deposit types.num_agent_neighborsandnum_landmark_neighborsconfigure partial observations in Adversary, Spread, and Tag.-1means all; positive counts select nearest neighbors and pad missing neighbors with zeros.local_ratio=0.5blends local and global rewards in Reference and Spread.terminate_on_success=Falseenables early completion in Spread, Formation, Line, and Tag when set toTrue. Tag succeeds when every prey is simultaneously touching an adversary.curriculum=Falseenables the initial curriculum stage in Spread and Tag. MPE2 1.1.1’s inherited stage setter is a no-op, so its stage remains zero even after calling the upstream stage-advancement methods.benchmark_data=Falseenables the scenario’s benchmark values.dynamic_rescaling=Truescales entity radii as the world bounds change. The camera follows the current bounds in both modes, matching MPE2 1.1.1. Rendering defaults to 700 by 700 RGB pixels;render_widthandrender_heightselect other canvas sizes and scale the geometry.max_num_playersis resolved from the scenario’s population at construction. A supplied capacity must fit the population.
Player API
Observations and rewards have a leading player dimension. Termination and truncation have a leading environment dimension because every player in an MPE2 world finishes together. A time limit takes precedence over success on the final step, matching the upstream API.
info["players"] contains env_id, id, obs_size, action_size,
and action_mask. The action size is the number of legal choices
in discrete mode and the original vector length in continuous mode. Continuous
actions use zero padding for roles with fewer controls. The mask identifies
legal choices in discrete mode and valid control dimensions in continuous mode.
Movement controls are no-op, left, right, down, up. A communicating movable
agent uses movement + 5 * message in discrete mode. Its continuous vector
contains the five movement controls followed by the communication channels.
A stationary speaker has only communication controls.
info["state"] concatenates the original observations in upstream agent
order. info["players"]["reward"] preserves the float64 upstream reward;
the normal EnvPool reward is float32. Benchmark values are padded under
info["players"]["benchmark"] with lengths in benchmark_size;
Collect Treasure’s absent inventory value (upstream None) is encoded as
-1. Empty upstream benchmark dictionaries have length zero.
import envpool
import numpy as np
env = envpool.make_gymnasium(
"MPE2/SimpleSpread-v3", num_envs=8, seed=42, render_mode="rgb_array"
)
obs, info = env.reset()
rng = np.random.default_rng(7)
action = np.array([
rng.integers(n) for n in info["players"]["action_size"]
], dtype=np.int32)
obs, reward, terminated, truncated, info = env.step({
"players": {"env_id": info["players"]["env_id"], "action": action}
})
frames = env.render([0, 3])
env.close()
Validation
The family tests compare all registered tasks against MPE2 1.1.1 using both action modes. Native reset state initializes the oracle; both then receive identical external actions. Collect Treasure also transfers sampled position and type after independently checking when a collected treasure reappears, before the oracle computes observations and rewards. The tests separately check sampling bounds, treasure types and variation, pickup, and delivery. Independent tests inspect native resets without synchronization, including goals, keys, treasure types, continuous resets, and parallel streams. Native seed sequences use standard C++ distributions and do not promise NumPy’s seed-to-state map or draw order.
The float64 reward comparison uses rtol=1e-14 and atol=1e-14. NumPy’s
BLAS contraction, vector math, and reduction order can vary across CPU
backends, causing last-bit differences from native scalar arithmetic.
The oracle uses its default backend; native code does not reproduce a
particular backend’s rounding. Observations, state, float32 rewards, benchmark
data and completion flags are still compared exactly. Rendered RGB channels
allow one 8-bit level for text-edge alpha quantization.