gymnasium-orchard 1.0.0

Gymnasium environments for the Orchard cooperative dice game

gymnasium-orchard

Gymnasium environments for the cooperative dice game Orchard (First Orchard).

Background and analysis: Recommend.Games blog

Installation

pip install gymnasium-orchard

To also use the bulk simulation and analysis tools (OrchardGame.run_games, OrchardGame.analyse_games):

pip install "gymnasium-orchard[analysis]"

Usage

import gymnasium as gym
import orchard  # registers the environments

env = gym.make("Orchard-round")
obs, info = env.reset(seed=42)

terminated = False
while not terminated:
    action = env.action_space.sample()  # or your policy
    obs, reward, terminated, truncated, info = env.step(action)

Environments

Orchard-round

One step() = one die roll. The agent provides an action every step; it is only applied when the basket face is rolled.

Orchard-decision

One step() = one basket decision. The environment advances automatically through fruit-tree and raven rolls, pausing only when a basket is rolled or the game ends. Cleaner for tabular RL methods.

Observation space

Both environments use the same observation space:

Key	Space	Description
fruits	Box(int8, shape=(num_trees,))	Fruits remaining on each tree
raven	Discrete(raven_steps + 1)	Raven's distance from the orchard

Action space

Discrete(num_trees) — which tree to pick from on a basket roll. Ignored on all other rolls; falls back to the tree with the most fruit if the chosen tree is empty.

Reward

Sparse: +1 on win (all fruit picked), -1 on loss (raven reaches the orchard), 0 otherwise.

Info dict

Both environments include an action_mask in info on every step:

info["action_mask"]  # np.int8 array, 1 = tree has fruit, 0 = empty

Orchard-round additionally includes the die result:

info["die"]             # int, face rolled
info["basket"]          # bool, whether it was a basket roll
info["action_applied"]  # bool, whether the action was used

Orchard-decision includes the rolls that were skipped:

info["auto_rolls"]  # list[int], die values of non-basket rolls since last step

Configuration

Pass an OrchardGameConfig to customise the game:

from orchard.game import OrchardGameConfig

config = OrchardGameConfig(
    num_trees=4,
    fruits_per_tree=10,
    fruits_per_basket_roll=2,
    raven_steps=9,
)
env = gym.make("Orchard-round", config=config)

Licence

MIT