Externality Mushrooms Dense¶

externality_mushrooms/dense is a native PettingZoo port of Melting Pot's public externality_mushrooms__dense substrate. Five players move around a bounded mushroom garden where each color has a different mix of private reward, public reward, digestion delay, and ecological side effect.

Screenshot¶

API¶

See the generated Externality Mushrooms API reference for signatures and public objects.

Use the family dispatcher:

from mp.externality_mushrooms import env, parallel_env

parallel = parallel_env("dense")
aec = env("dense")

Or import the variant directly:

from mp.externality_mushrooms.dense import ExternalityMushroomsDenseConfig, parallel_env

config = ExternalityMushroomsDenseConfig()
env = parallel_env(config=config, render_mode="rgb_array")

Agents are named player_0 through player_4. Each infos[agent] includes meltingpot_player_index, preserving Melting Pot's 1-based player ID.

Actions and observations¶

The action space is Discrete(8):

Default per-agent observations are:

state() and render_mode="rgb_array" return the global world RGB frame with shape (112, 184, 3).

Mechanics¶

Red mushrooms give +1 to the eater. Green mushrooms split +2 across all five players. Blue mushrooms split +3 across everyone except the eater. Orange mushrooms split -1 across all players and destroy a fraction of live red mushrooms. Green, blue, and orange mushrooms freeze the eater for digestion.

Eating mushrooms releases spores that can regrow mushrooms on empty unoccupied potential sites. Live mushrooms spoil back to empty sites after their color's timer expires. Zap beams destroy mushrooms, mark and freeze avatars on first hit, and remove already marked avatars until respawn.

Episodes can terminate stochastically after step 1000, checked every 100 steps, and truncate at step 5000 by default.

Reward strategy and failure modes¶

High-return policies account for both private and public effects. Red gives safe private reward, green creates broadly shared reward, blue rewards everyone except the eater, and orange is harmful. Agents can improve group outcomes by favoring green, using blue when others benefit enough to justify the eater's delay, and zapping destructive mushrooms or disruptive marked players.

Bad equilibria include red-only foraging that ignores public-good mushrooms, orange consumption that damages the ecosystem, and punishment cycles where zaps remove players who would otherwise be creating shared reward. Digestion delays can also make high-public-reward mushrooms unattractive to selfish agents even when they improve total welfare.

Playable notebook¶

Launch the playable notebook with:

uv run marimo run notebooks/externality_mushrooms/dense_mo.py

Controls:

• WASD or arrow keys move the active player.
• Q/E turn the active player.
• SPACE fires the zap beam.
• TAB switches the controlled player.
• ESC closes the pygame window.

The notebook exposes regrowth and spoil-time sliders for playability. The environment defaults remain parity-oriented.