game-room 0.1.0__tar.gz

game_room-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Austin Poor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

game_room-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: game-room
+Version: 0.1.0
+Summary: PettingZoo environments for tabletop games
+Keywords: pettingzoo,reinforcement-learning,multi-agent,card-games
+Author: Austin Poor
+Author-email: Austin Poor <45295232+a-poor@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: pettingzoo>=1.24.3,<2
+Requires-Dist: gymnasium>=1.0,<2
+Requires-Dist: numpy>=2.1
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# game-room
+
+A collection of PettingZoo environments for a few different games.
+
+## Installation
+
+Requires Python 3.14+. Once the first release is published to PyPI, install it
+with pip:
+
+```sh
+python -m pip install game-room
+```
+
+Or add it to a [uv](https://docs.astral.sh/uv/) project with `uv add game-room`.
+The first release is being prepared; until it is published, install from this
+repository with `python -m pip install .`.
+
+## Getting Started
+
+Save the following as `play.py`, then run `python play.py` (or
+`uv run python play.py` in a uv project) to simulate a
+three-player Flip 7 game with random legal actions and print the final scores:
+
+```python
+from game_room import flip7_v0
+
+env = flip7_v0.env(num_players=3, render_mode="ansi")
+env.reset(seed=42)
+
+for agent in env.agent_iter():
+    observation, reward, terminated, truncated, info = env.last()
+    if terminated or truncated:
+        action = None
+    else:
+        action = env.action_space(agent).sample(observation["action_mask"])
+    env.step(action)
+
+print(env.render())
+env.close()
+```
+
+## Flip 7
+
+`game_room.flip7_v0` implements the 94-card game for 3-18 players using
+PettingZoo's turn-based AEC API. It includes the opening deal, all special cards,
+chained Flip Threes, deck recycling, and complete games across multiple rounds.
+
+Actions are `0` (Hit), `1` (Stay), and `2 + seat_index` (choose the recipient
+of an action card). Always use the mask: target selection is a separate decision,
+and the same player can act multiple times in succession. Invalid actions raise
+`ValueError` without changing game state.
+
+Rewards are points earned at each round's end, so each player's episode return
+equals their final score. Winners are reported in `info["winners"]` at game end;
+the reward is not a win/loss reward. By default, a game ends after a completed
+round brings someone to 200 points. Set `target_score` to change that threshold,
+or `max_rounds` to truncate training episodes at a round boundary (default: no
+limit). Tied leaders share the win. Scores and the last completed round's scores
+are available in `info` after the first round.
+
+The environment supports `ansi` and `human` text rendering. It has no parallel
+API because each decision can immediately affect other players.
+
+See [rules and observation reference](docs/rules-flip7.md) for rule conventions,
+card IDs, and the public observation layout.
+
+The `_v0` suffix identifies version 0 of the environment's rules and interface.
+It is independent of the package version (`0.1.0`). Changes that invalidate
+existing policies or experiment comparisons should introduce a new environment
+version, such as `flip7_v1`, rather than silently replacing `flip7_v0`.
+
+## Development
+
+From a checkout, install the package and development tools:
+
+```sh
+uv sync --group dev
+```
+
+`dev` is the dependency group defined in `pyproject.toml` for pytest and Ruff.
+uv includes this group by default, so `uv sync` also works; `--group dev` makes
+the intent explicit. These tools are not runtime dependencies and are not
+installed when users install the published package.
+
+```sh
+uv run pytest
+uv run ruff check src tests
+uv run ruff format --check src tests
+```
+
+Tests include PettingZoo API and seed checks, controlled special-card scenarios,
+and full randomized games checking card conservation and cumulative rewards.
+
+See [publishing instructions](docs/publishing.md) for building and releasing
+the package. The implementation is distributed under the [MIT license](LICENSE).

game_room-0.1.0/README.md

@@ -0,0 +1,95 @@
+# game-room
+
+A collection of PettingZoo environments for a few different games.
+
+## Installation
+
+Requires Python 3.14+. Once the first release is published to PyPI, install it
+with pip:
+
+```sh
+python -m pip install game-room
+```
+
+Or add it to a [uv](https://docs.astral.sh/uv/) project with `uv add game-room`.
+The first release is being prepared; until it is published, install from this
+repository with `python -m pip install .`.
+
+## Getting Started
+
+Save the following as `play.py`, then run `python play.py` (or
+`uv run python play.py` in a uv project) to simulate a
+three-player Flip 7 game with random legal actions and print the final scores:
+
+```python
+from game_room import flip7_v0
+
+env = flip7_v0.env(num_players=3, render_mode="ansi")
+env.reset(seed=42)
+
+for agent in env.agent_iter():
+    observation, reward, terminated, truncated, info = env.last()
+    if terminated or truncated:
+        action = None
+    else:
+        action = env.action_space(agent).sample(observation["action_mask"])
+    env.step(action)
+
+print(env.render())
+env.close()
+```
+
+## Flip 7
+
+`game_room.flip7_v0` implements the 94-card game for 3-18 players using
+PettingZoo's turn-based AEC API. It includes the opening deal, all special cards,
+chained Flip Threes, deck recycling, and complete games across multiple rounds.
+
+Actions are `0` (Hit), `1` (Stay), and `2 + seat_index` (choose the recipient
+of an action card). Always use the mask: target selection is a separate decision,
+and the same player can act multiple times in succession. Invalid actions raise
+`ValueError` without changing game state.
+
+Rewards are points earned at each round's end, so each player's episode return
+equals their final score. Winners are reported in `info["winners"]` at game end;
+the reward is not a win/loss reward. By default, a game ends after a completed
+round brings someone to 200 points. Set `target_score` to change that threshold,
+or `max_rounds` to truncate training episodes at a round boundary (default: no
+limit). Tied leaders share the win. Scores and the last completed round's scores
+are available in `info` after the first round.
+
+The environment supports `ansi` and `human` text rendering. It has no parallel
+API because each decision can immediately affect other players.
+
+See [rules and observation reference](docs/rules-flip7.md) for rule conventions,
+card IDs, and the public observation layout.
+
+The `_v0` suffix identifies version 0 of the environment's rules and interface.
+It is independent of the package version (`0.1.0`). Changes that invalidate
+existing policies or experiment comparisons should introduce a new environment
+version, such as `flip7_v1`, rather than silently replacing `flip7_v0`.
+
+## Development
+
+From a checkout, install the package and development tools:
+
+```sh
+uv sync --group dev
+```
+
+`dev` is the dependency group defined in `pyproject.toml` for pytest and Ruff.
+uv includes this group by default, so `uv sync` also works; `--group dev` makes
+the intent explicit. These tools are not runtime dependencies and are not
+installed when users install the published package.
+
+```sh
+uv run pytest
+uv run ruff check src tests
+uv run ruff format --check src tests
+```
+
+Tests include PettingZoo API and seed checks, controlled special-card scenarios,
+and full randomized games checking card conservation and cumulative rewards.
+
+See [publishing instructions](docs/publishing.md) for building and releasing
+the package. The implementation is distributed under the [MIT license](LICENSE).

game_room-0.1.0/docs/publishing.md

@@ -0,0 +1,74 @@
+# Publishing game-room
+
+The initial distribution name is `game-room`, the Python import is `game_room`,
+and the first planned version is `0.1.0`. Python 3.14+ is currently required.
+The package uses the MIT license and uv's build backend.
+
+## Validate and build
+
+Run from the repository root:
+
+```sh
+uv sync --locked --group dev
+uv run pytest
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv build --no-sources
+uvx --from twine twine check --strict dist/game_room-0.1.0*
+```
+
+The build produces a source archive (`.tar.gz`) and a wheel (`.whl`) in `dist/`.
+uv builds the wheel from the source archive by default, checking that the source
+distribution is sufficient to build the package. The source archive includes
+tests and documentation; the wheel includes the importable package, typing
+marker, metadata, and license. Development dependencies are not wheel runtime
+requirements.
+
+Before releasing, install the wheel into a fresh environment and run the README
+example from outside the checkout. Confirm the imported package comes from that
+environment's site-packages.
+
+## Registry setup
+
+1. Create or select your PyPI and TestPyPI accounts. They are separate services.
+2. Confirm the distribution name is available or owned by your account on each
+   service. A missing project page does not guarantee the name can be registered.
+3. Configure authentication locally. For manual uploads, use a registry API token
+   through `UV_PUBLISH_TOKEN` or uv's credential prompt. Never commit tokens.
+4. When a repository is hosted, add its actual URL to `[project.urls]` and configure
+   a Trusted Publisher if you want releases through CI. No remote repository or
+   publisher is configured by this checkout's initial packaging setup.
+
+## Test release
+
+With TestPyPI credentials configured:
+
+```sh
+uv publish --publish-url https://test.pypi.org/legacy/ dist/game_room-0.1.0.tar.gz dist/game_room-0.1.0-py3-none-any.whl
+```
+
+To test that artifact, create a fresh environment, install the runtime
+dependencies from regular PyPI, then install this package from TestPyPI without
+dependency resolution:
+
+```sh
+uv venv /tmp/game-room-test-release
+uv pip install --python /tmp/game-room-test-release/bin/python 'pettingzoo>=1.24.3,<2' 'gymnasium>=1.0,<2' 'numpy>=2.1'
+uv pip install --python /tmp/game-room-test-release/bin/python --index-url https://test.pypi.org/simple/ --no-deps game-room==0.1.0
+```
+
+## Production release
+
+After verifying the test release, use production PyPI credentials:
+
+```sh
+uv publish dist/game_room-0.1.0.tar.gz dist/game_room-0.1.0-py3-none-any.whl
+```
+
+PyPI release files cannot be overwritten. For subsequent releases, update
+`project.version`, refresh `uv.lock`, rebuild, and publish only the intended
+version's artifacts. Update these versioned commands accordingly. After the
+first upload succeeds, remove the README's pre-release installation notice.
+
+References: [uv packaging guide](https://docs.astral.sh/uv/guides/package/),
+[Python packaging tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/).

game_room-0.1.0/docs/rules-flip7.md

@@ -0,0 +1,108 @@
+# Flip 7 environment reference
+
+Implementation: `game_room.flip7_v0`, based on The Op's
+[official rules, edition 3.1](https://cdn.shopify.com/s/files/1/0611/3958/3198/files/25_FLIP_7_TB_RULES_C_Rev_9_2_25_ND.pdf?v=1756935535).
+The game name belongs to its respective owner; this repository supplies an
+independent implementation and does not include card artwork.
+
+## Implemented rules
+
+The deck contains 94 cards: one zero, n copies of each number n from 1 through
+12, one each of +2/+4/+6/+8/+10/x2, and three each of Freeze, Flip Three, and
+Second Chance. Each round starts with one deal per active seat. Special cards
+interrupt that deal. Players then choose Hit or Stay in seat order; staying
+requires at least one card in front of the player.
+
+A duplicate number busts its recipient unless they have Second Chance, in which
+case the duplicate and Second Chance are discarded immediately. A second Second
+Chance must go to another active player without one, or be discarded if there
+is no eligible recipient. Freeze banks a target's current hand. Flip Three
+forces up to three draws, stopping on a bust or seven distinct numbers. Every
+card counts toward those three draws. Second Chance works immediately; Freeze
+and further Flip Three cards wait until the three draws finish and are canceled
+if their recipient busts.
+
+Seven number cards end the round for everyone. Otherwise the round ends when
+everyone stays, freezes, or busts. Non-busted players score their numbers,
+doubled if they hold x2, then add modifiers and the 15-point Flip 7 bonus.
+The highest total wins once a completed round has brought someone to the target
+score. The unused deck carries forward between rounds. Only discards are
+reshuffled when it runs out; cards on the table remain out of the draw pile.
+
+## Explicit conventions
+
+- Seats are fixed as `player_0` through `player_N-1`. The first dealer is seat 0;
+  dealing and turns start on the dealer's left, and the dealer rotates each round.
+- Seats already frozen or busted during the opening deal are skipped.
+- Multiple deferred actions resolve in draw order. Each Flip Three chain resolves
+  before the next deferred action. The player who drew a special card chooses its
+  target, including when forced to draw it by someone else. A player frozen while
+  resolving deferred actions still chooses targets for their remaining actions;
+  a bust cancels their remaining actions. The printed rules do not specify all
+  of these ordering cases.
+- When the only eligible target is oneself, target selection remains an explicit
+  decision with a single legal action.
+- Tied leaders share victory; the rules do not prescribe a tiebreaker.
+- If every card is on the table and both draw and discard piles are empty when
+  a draw is needed, bank the round and proceed normally. This rare large-table
+  case has no printed ruling; this convention avoids an impossible draw.
+- Observations retain publicly revealed cards even after players turn them face
+  down. This gives policies perfect recall of public card counts, never deck
+  order. Deferred action order and scheduled events are also public.
+- This version uses a single deck and the standard 3-18 player competitive game.
+  The one/two-player round-count challenge and multiple decks are not implemented.
+
+## API and rewards
+
+`env(num_players=3, target_score=200, max_rounds=None, render_mode=None)` returns a
+wrapped PettingZoo AEC environment. `raw_env(...)` exposes the underlying class.
+`reset(seed=...)` seeds shuffling and action-space sampling; reset options are
+accepted but unused. `render_mode` accepts `None`, `"ansi"`, or `"human"`.
+
+Each round awards its scored points as rewards to all players together. Stayed,
+frozen, and busted players remain episode agents but are skipped for ordinary
+turns. On episode termination/truncation, drain remaining agents with `step(None)`
+as required by the AEC API. Natural termination takes precedence over a round
+limit. `info` includes `scores`, `round_scores`, `completed_round`, and `winners`
+after a round ends, and retains that information until the next completed round.
+No future draw information is exposed through observations, rendering, or infos.
+
+## Observation layout
+
+`observe(agent)` returns a dictionary:
+
+- `action_mask`: an `int8` vector of length `2 + N`. Legal decisions have value 1;
+  all other entries are zero. Non-selected and finished agents have all-zero masks.
+- `observation`: a flat `float64` vector of length `419 + 24*N`, with the following
+  consecutive blocks. All values represent nonnegative integers. Seats are in
+  absolute order, not rotated relative to the observer.
+
+| Block | Size | Contents |
+| --- | --- | --- |
+| Header | 10 | Observer seat, acting seat, dealer seat, round number (1-based), draw-pile size, target score, max rounds (0 means unlimited), target-decision flag, pending card ID (0 when absent), Flip 7 seat plus one (0 when absent) |
+| Player rows | N * 24 | For each seat: banked total, round status, counts for each of 22 card IDs |
+| Discard counts | 22 | Counts in the current discard pile by card ID |
+| Scheduled events | 128 * 3 | Ordered triples `(kind, seat, card)`, padded with zeros |
+| Deferred actions | 3 | Card ID plus one, in draw order, padded with zeros |
+
+Round status codes: `0` active, `1` stayed, `2` busted, `3` frozen. Banked totals
+update together at round end. Final observations clear hands after moving cards
+to discard; `round_scores` in infos preserves the final scoring result.
+
+Scheduled event kinds: `1` opening deal, `2` forced draw, `3` end of a Flip Three,
+`4` resolve a deferred action, `5` next ordinary turn. Only kind 4 uses the card
+field. Draw events contain no card identities. The fixed padding exceeds the
+maximum scheduler size for the supported player counts and single deck.
+
+| Card IDs | Meaning |
+| --- | --- |
+| 0-12 | Number cards |
+| 13-17 | +2, +4, +6, +8, +10 |
+| 18 | x2 |
+| 19 | Freeze |
+| 20 | Flip Three |
+| 21 | Second Chance |
+
+Actions: `HIT=0`, `STAY=1`, and `TARGET_OFFSET + seat` with `TARGET_OFFSET=2`.
+The `Card` enum exports symbolic names for special cards. The vector layout and
+action IDs are part of the versioned `flip7_v0` interface.

game_room-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "game-room"
+version = "0.1.0"
+description = "PettingZoo environments for tabletop games"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "pettingzoo",
+    "reinforcement-learning",
+    "multi-agent",
+    "card-games",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.14"
+dependencies = [
+    "pettingzoo>=1.24.3,<2",
+    "gymnasium>=1.0,<2",
+    "numpy>=2.1",
+]
+
+[[project.authors]]
+name = "Austin Poor"
+email = "45295232+a-poor@users.noreply.github.com"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.11",
+]
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.uv.build-backend]
+source-include = [
+    "docs/**",
+    "tests/**",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"

game_room-0.1.0/pyproject.toml.orig

@@ -0,0 +1,37 @@
+[project]
+name = "game-room"
+version = "0.1.0"
+description = "PettingZoo environments for tabletop games"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["pettingzoo", "reinforcement-learning", "multi-agent", "card-games"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+authors = [
+    { name = "Austin Poor", email = "45295232+a-poor@users.noreply.github.com" }
+]
+requires-python = ">=3.14"
+dependencies = ["pettingzoo>=1.24.3,<2", "gymnasium>=1.0,<2", "numpy>=2.1"]
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.11"]
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = ["docs/**", "tests/**"]

game_room-0.1.0/src/game_room/__init__.py

@@ -0,0 +1 @@
+"""Tabletop games exposed as PettingZoo environments."""

game_room-0.1.0/src/game_room/flip7_v0.py

@@ -0,0 +1,413 @@
+"""Flip 7 (rules edition 3.1), a sequential, imperfect-information game.
+
+See docs/rules-flip7.md for the observation layout and rule conventions.
+"""
+
+from collections import Counter, deque
+from enum import IntEnum
+from typing import ClassVar
+
+import numpy as np
+from gymnasium import spaces
+from gymnasium.utils import seeding
+from pettingzoo import AECEnv
+from pettingzoo.utils import wrappers
+
+
+class Card(IntEnum):
+    """Numbers use IDs 0..12; the remaining IDs describe special cards."""
+
+    PLUS_2 = 13
+    PLUS_4 = 14
+    PLUS_6 = 15
+    PLUS_8 = 16
+    PLUS_10 = 17
+    TIMES_2 = 18
+    FREEZE = 19
+    FLIP_THREE = 20
+    SECOND_CHANCE = 21
+
+
+HIT = 0
+STAY = 1
+TARGET_OFFSET = 2
+CARD_COUNT = 22
+# Scheduler instructions are public; no future card identities are stored here.
+DEAL, FORCED_DRAW, END_THREE, RESOLVE, TURN = range(1, 6)
+ACTIVE, STAYED, BUSTED, FROZEN = range(4)
+
+
+def make_deck() -> list[int]:
+    """Return one unshuffled 94-card deck."""
+    return (
+        [0]
+        + [number for number in range(1, 13) for _ in range(number)]
+        + list(range(Card.PLUS_2, Card.TIMES_2 + 1))
+        + [
+            card
+            for card in range(Card.FREEZE, Card.SECOND_CHANCE + 1)
+            for _ in range(3)
+        ]
+    )
+
+
+def env(**kwargs):
+    """Create a wrapped AEC environment; illegal actions raise an exception."""
+    return wrappers.OrderEnforcingWrapper(
+        wrappers.AssertOutOfBoundsWrapper(raw_env(**kwargs))
+    )
+
+
+class raw_env(AECEnv):
+    metadata: ClassVar[dict] = {
+        "name": "flip7_v0",
+        "render_modes": ["human", "ansi"],
+        "is_parallelizable": False,
+        "render_fps": 1,
+    }
+
+    def __init__(
+        self,
+        num_players: int = 3,
+        target_score: int = 200,
+        max_rounds: int | None = None,
+        render_mode: str | None = None,
+    ):
+        super().__init__()
+        if (
+            isinstance(num_players, bool)
+            or not isinstance(num_players, int)
+            or not 3 <= num_players <= 18
+        ):
+            raise ValueError("num_players must be an integer from 3 to 18")
+        if (
+            isinstance(target_score, bool)
+            or not isinstance(target_score, int)
+            or target_score < 1
+        ):
+            raise ValueError("target_score must be a positive integer")
+        if max_rounds is not None and (
+            isinstance(max_rounds, bool)
+            or not isinstance(max_rounds, int)
+            or max_rounds < 1
+        ):
+            raise ValueError("max_rounds must be a positive integer or None")
+        if render_mode not in (None, "ansi", "human"):
+            raise ValueError("render_mode must be None, 'ansi', or 'human'")
+        self.num_players = num_players
+        self.target_score = target_score
+        self.max_rounds = max_rounds
+        self.render_mode = render_mode
+        self.possible_agents = [f"player_{i}" for i in range(num_players)]
+        self._indices = {agent: i for i, agent in enumerate(self.possible_agents)}
+        self.action_spaces = {
+            agent: spaces.Discrete(TARGET_OFFSET + num_players)
+            for agent in self.possible_agents
+        }
+        # Header + per-seat scores/status/cards + discard + scheduler + deferred.
+        self._observation_size = 10 + num_players * 24 + CARD_COUNT + 128 * 3 + 3
+        self.observation_spaces = {
+            agent: spaces.Dict(
+                {
+                    "observation": spaces.Box(
+                        0, np.inf, (self._observation_size,), dtype=np.float64
+                    ),
+                    "action_mask": spaces.MultiBinary(TARGET_OFFSET + num_players),
+                }
+            )
+            for agent in self.possible_agents
+        }
+        self.np_random, _ = seeding.np_random()
+
+    def observation_space(self, agent):
+        return self.observation_spaces[agent]
+
+    def action_space(self, agent):
+        return self.action_spaces[agent]
+
+    def reset(self, seed=None, options=None):
+        # Accept unused options for compatibility with PettingZoo's reset API.
+        if seed is not None:
+            self.np_random, _ = seeding.np_random(seed)
+            for i, agent in enumerate(self.possible_agents):
+                self.action_space(agent).seed(seed + i)
+        self.agents = self.possible_agents[:]
+        self.rewards = dict.fromkeys(self.agents, 0.0)
+        self._cumulative_rewards = dict.fromkeys(self.agents, 0.0)
+        self.terminations = dict.fromkeys(self.agents, False)
+        self.truncations = dict.fromkeys(self.agents, False)
+        self.infos = {agent: {} for agent in self.agents}
+        self._skip_agent_selection = None
+        self.scores = [0] * self.num_players
+        self.deck = make_deck()
+        self.np_random.shuffle(self.deck)
+        self.discard = []
+        self.round_number = 0
+        self.dealer = 0
+        self.winners = []
+        self._start_round()
+        self._advance()
+        self._accumulate_rewards()
+
+    def _start_round(self):
+        self.round_number += 1
+        self.hands = [[] for _ in self.possible_agents]
+        self.status = [ACTIVE] * self.num_players
+        self.flip7_player = None
+        self._exhausted = False
+        self.pending_card = None
+        self.deferred = []
+        # The player to the dealer's left acts first; dealer acts last.
+        first = (self.dealer + 1) % self.num_players
+        self.tasks = deque(
+            (DEAL, (first + i) % self.num_players, 0) for i in range(self.num_players)
+        )
+        self.tasks.append((TURN, first, 0))
+
+    def _round_score(self, player):
+        if self.status[player] == BUSTED:
+            return 0
+        hand = self.hands[player]
+        total = sum(card for card in hand if card <= 12)
+        total *= 2 if Card.TIMES_2 in hand else 1
+        total += sum(2 * (card - 12) for card in hand if 13 <= card <= 17)
+        return total + (15 if self.flip7_player == player else 0)
+
+    def _draw(self, player, forced=False):
+        if not self.deck:
+            self.deck, self.discard = self.discard, []
+            self.np_random.shuffle(self.deck)
+        if not self.deck:
+            # Large tables can hold the entire deck without a Flip 7. The
+            # rulebook has no adjudication for this; bank the round (see docs).
+            self._exhausted = True
+            return
+        card = self.deck.pop()
+        hand = self.hands[player]
+        if card <= 12:
+            if card in hand:
+                if Card.SECOND_CHANCE in hand:
+                    hand.remove(Card.SECOND_CHANCE)
+                    self.discard.extend([int(Card.SECOND_CHANCE), card])
+                    return
+                self.status[player] = BUSTED
+            hand.append(card)
+            if self.status[player] != BUSTED and sum(c <= 12 for c in hand) == 7:
+                self.flip7_player = player
+        elif card <= Card.TIMES_2:
+            hand.append(card)
+        elif card == Card.SECOND_CHANCE:
+            if card not in hand:
+                hand.append(card)
+            elif self._targets(player, card):
+                self._ask_target(player, card)
+            else:
+                self.discard.append(card)
+        elif forced:
+            self.deferred.append(card)
+        else:
+            self._ask_target(player, card)
+
+    def _targets(self, player, card):
+        return [
+            i
+            for i in range(self.num_players)
+            if self.status[i] == ACTIVE
+            and (
+                card != Card.SECOND_CHANCE
+                or (i != player and Card.SECOND_CHANCE not in self.hands[i])
+            )
+        ]
+
+    def _ask_target(self, player, card):
+        self.pending_card = int(card)
+        self.agent_selection = self.possible_agents[player]
+
+    def _advance(self):
+        """Run chance events until the next player decision or game end."""
+        while True:
+            if (
+                self.flip7_player is not None
+                or ACTIVE not in self.status
+                or self._exhausted
+            ) and self._finish_round():
+                return
+            if self.pending_card is not None:
+                return
+            kind, player, card = self.tasks.popleft()
+            if kind == TURN:
+                self.tasks.append((TURN, (player + 1) % self.num_players, 0))
+                if self.status[player] == ACTIVE:
+                    self.agent_selection = self.possible_agents[player]
+                    return
+            elif kind in (DEAL, FORCED_DRAW):
+                if self.status[player] == ACTIVE:
+                    self._draw(player, forced=kind == FORCED_DRAW)
+            elif kind == END_THREE:
+                if self.status[player] == BUSTED:
+                    self.hands[player].extend(self.deferred)
+                else:
+                    for action_card in reversed(self.deferred):
+                        self.tasks.appendleft((RESOLVE, player, action_card))
+                self.deferred = []
+            elif kind == RESOLVE:
+                # Busting in a chained Flip Three cancels outstanding actions.
+                if self.status[player] == BUSTED:
+                    self.hands[player].append(card)
+                else:
+                    self._ask_target(player, card)
+
+    def _finish_round(self):
+        round_scores = [self._round_score(i) for i in range(self.num_players)]
+        self.scores = [a + b for a, b in zip(self.scores, round_scores)]
+        for hand in self.hands:
+            self.discard.extend(hand)
+        self.discard.extend(self.deferred)
+        self.discard.extend(card for kind, _, card in self.tasks if kind == RESOLVE)
+        if self.pending_card is not None:
+            self.discard.append(self.pending_card)
+        self.tasks.clear()
+        self.deferred = []
+        self.pending_card = None
+        finished = max(self.scores) >= self.target_score
+        truncated = (
+            not finished
+            and self.max_rounds is not None
+            and self.round_number >= self.max_rounds
+        )
+        if finished:
+            best = max(self.scores)
+            self.winners = [
+                a for a, s in zip(self.possible_agents, self.scores) if s == best
+            ]
+        for i, agent in enumerate(self.possible_agents):
+            self.rewards[agent] += float(round_scores[i])
+            self.infos[agent] = {
+                "scores": dict(zip(self.possible_agents, self.scores)),
+                "round_scores": dict(zip(self.possible_agents, round_scores)),
+                "completed_round": self.round_number,
+                "winners": self.winners[:],
+            }
+            self.terminations[agent] = finished
+            self.truncations[agent] = truncated
+        if finished or truncated:
+            # Clear hands now that their cards have moved to the discard pile.
+            self.hands = [[] for _ in self.possible_agents]
+            self.agent_selection = self.possible_agents[0]
+            return True
+        self.dealer = (self.dealer + 1) % self.num_players
+        self._start_round()
+        return False
+
+    def _mask(self, agent):
+        mask = np.zeros(TARGET_OFFSET + self.num_players, dtype=np.int8)
+        if (
+            agent not in self.agents
+            or self.terminations[agent]
+            or self.truncations[agent]
+            or agent != self.agent_selection
+        ):
+            return mask
+        player = self._indices[agent]
+        if self.pending_card is None:
+            mask[HIT] = 1
+            mask[STAY] = bool(self.hands[player])
+        else:
+            for target in self._targets(player, self.pending_card):
+                mask[TARGET_OFFSET + target] = 1
+        return mask
+
+    def observe(self, agent):
+        header = [
+            self._indices[agent],
+            self._indices[self.agent_selection],
+            self.dealer,
+            self.round_number,
+            len(self.deck),
+            self.target_score,
+            self.max_rounds or 0,
+            int(self.pending_card is not None),
+            0 if self.pending_card is None else self.pending_card,
+            0 if self.flip7_player is None else self.flip7_player + 1,
+        ]
+        rows = []
+        for i, hand in enumerate(self.hands):
+            counts = Counter(hand)
+            rows.extend([self.scores[i], self.status[i]])
+            rows.extend(counts[c] for c in range(CARD_COUNT))
+        discard = Counter(self.discard)
+        deferred = [card + 1 for card in self.deferred]
+        deferred += [0] * (3 - len(deferred))
+        queue = np.zeros((128, 3), dtype=np.float64)
+        for i, task in enumerate(self.tasks):
+            queue[i] = task
+        observation = np.concatenate(
+            [
+                header,
+                rows,
+                [discard[c] for c in range(CARD_COUNT)],
+                queue.ravel(),
+                deferred,
+            ]
+        ).astype(np.float64)
+        return {"observation": observation, "action_mask": self._mask(agent)}
+
+    def step(self, action):
+        agent = self.agent_selection
+        if self.terminations[agent] or self.truncations[agent]:
+            self._was_dead_step(action)
+            return
+        if (
+            not self.action_space(agent).contains(action)
+            or not self._mask(agent)[action]
+        ):
+            raise ValueError(f"Illegal action {action!r} for {agent}")
+        self._cumulative_rewards[agent] = 0
+        self._clear_rewards()
+        player = self._indices[agent]
+        if self.pending_card is not None:
+            target = int(action) - TARGET_OFFSET
+            card, self.pending_card = self.pending_card, None
+            self.hands[target].append(card)
+            if card == Card.FREEZE:
+                self.status[target] = FROZEN
+            elif card == Card.FLIP_THREE:
+                self.tasks.appendleft((END_THREE, target, 0))
+                for _ in range(3):
+                    self.tasks.appendleft((FORCED_DRAW, target, 0))
+        elif action == STAY:
+            self.status[player] = STAYED
+        else:
+            self._draw(player)
+        self._advance()
+        self._accumulate_rewards()
+        if self.render_mode == "human":
+            self.render()
+
+    def render(self):
+        if self.render_mode is None:
+            return None
+        lines = [f"Flip 7 | round {self.round_number} | deck {len(self.deck)}"]
+        names = ["active", "stayed", "busted", "frozen"]
+        for i, agent in enumerate(self.possible_agents):
+            cards = [str(c) if c <= 12 else Card(c).name for c in self.hands[i]]
+            lines.append(
+                f"{agent}: {self.scores[i]} points | {names[self.status[i]]} | {', '.join(cards)}"
+            )
+        if self.winners:
+            lines.append(f"Winners: {', '.join(self.winners)}")
+        elif self.agents:
+            decision = (
+                "Hit / Stay"
+                if self.pending_card is None
+                else f"target for {Card(self.pending_card).name}"
+            )
+            lines.append(f"{self.agent_selection}: {decision}")
+        text = "\n".join(lines)
+        if self.render_mode == "human":
+            print(text)
+            return None
+        return text
+
+    def close(self):
+        pass

game_room-0.1.0/tests/test_flip7.py

@@ -0,0 +1,326 @@
+from collections import Counter, deque
+
+import numpy as np
+import pytest
+from pettingzoo.test import api_test, seed_test
+
+from game_room import flip7_v0 as game
+from game_room.flip7_v0 import Card as C
+
+
+def position(hands=None, draws=(), **kwargs):
+    """Build a controlled public position with a physically consistent deck."""
+    env = game.raw_env(**kwargs)
+    env.reset(seed=1)
+    env.scores = [0] * env.num_players
+    env.hands = hands or [[] for _ in env.possible_agents]
+    env.status = [game.ACTIVE] * env.num_players
+    env.discard = []
+    env.pending_card = None
+    env.deferred = []
+    env.flip7_player = None
+    env.round_number = 1
+    env.tasks = deque([(game.TURN, 1, 0)])
+    env.agent_selection = "player_0"
+    deck = game.make_deck()
+    for card in [c for hand in env.hands for c in hand] + list(draws):
+        deck.remove(card)
+    env.deck = deck + list(reversed(draws))
+    return env
+
+
+def test_deck():
+    counts = Counter(game.make_deck())
+    assert sum(counts.values()) == 94
+    assert counts[0] == 1
+    assert all(counts[i] == i for i in range(1, 13))
+    assert all(counts[i] == 1 for i in range(13, 19))
+    assert all(counts[i] == 3 for i in range(19, 22))
+
+
+def test_api():
+    api_test(game.env(max_rounds=10), num_cycles=2000)
+
+
+def test_seed():
+    seed_test(lambda: game.env(max_rounds=10), num_cycles=1000)
+
+
+def test_duplicate_bust_and_retained_cards():
+    env = position([[12], [], []], [12])
+    env.step(game.HIT)
+    assert env.status[0] == game.BUSTED
+    assert env.hands[0] == [12, 12]
+    assert env._round_score(0) == 0
+    assert env.agent_selection == "player_1"
+
+
+def test_second_chance_consumed():
+    env = position([[12, C.SECOND_CHANCE], [], []], [12])
+    env.step(game.HIT)
+    assert env.status[0] == game.ACTIVE
+    assert env.hands[0] == [12]
+    assert Counter(env.discard) == Counter([12, C.SECOND_CHANCE])
+
+
+def test_second_chance_gift_and_ineligible_players():
+    env = position([[C.SECOND_CHANCE], [C.SECOND_CHANCE], []], [C.SECOND_CHANCE])
+    env.step(game.HIT)
+    assert env.observe("player_0")["action_mask"].tolist() == [0, 0, 0, 0, 1]
+    env.step(4)
+    assert C.SECOND_CHANCE in env.hands[2]
+    assert env.agent_selection == "player_1"
+
+
+def test_second_chance_discard_without_recipient():
+    env = position([[C.SECOND_CHANCE], [], []], [C.SECOND_CHANCE])
+    env.status[1:] = [game.STAYED, game.STAYED]
+    env.step(game.HIT)
+    assert env.discard == [C.SECOND_CHANCE]
+
+
+def test_stay_requires_any_card_and_invalid_action_is_atomic():
+    env = position()
+    before = env.observe("player_0")["observation"].copy()
+    assert env.observe("player_0")["action_mask"].tolist() == [1, 0, 0, 0, 0]
+    with pytest.raises(ValueError):
+        env.step(game.STAY)
+    np.testing.assert_array_equal(before, env.observe("player_0")["observation"])
+    env.hands[0] = [C.PLUS_2]
+    assert env.observe("player_0")["action_mask"][game.STAY]
+
+
+def test_freeze_and_turn_resume():
+    env = position([[10], [11], []], [C.FREEZE])
+    env.step(game.HIT)
+    env.step(3)
+    assert env.status[1] == game.FROZEN
+    assert env._round_score(1) == 11
+    assert env.agent_selection == "player_2"
+    assert env.observe("player_1")["action_mask"].sum() == 0
+
+
+def test_flip_three_deferred_freeze():
+    env = position([[1], [], []], [C.FLIP_THREE, C.FREEZE, 2, 3])
+    env.step(game.HIT)
+    env.step(2)
+    assert env.pending_card == C.FREEZE
+    assert env.hands[0] == [1, C.FLIP_THREE, 2, 3]
+    env.step(2)
+    assert env.status[0] == game.FROZEN
+    assert env._round_score(0) == 6
+    assert env.agent_selection == "player_1"
+
+
+def test_flip_three_bust_cancels_deferred_and_remaining_draws():
+    env = position([[12], [], []], [C.FLIP_THREE, C.FREEZE, 12, 5])
+    env.step(game.HIT)
+    env.step(2)
+    assert env.status[0] == game.BUSTED
+    assert env.pending_card is None
+    assert C.FREEZE in env.hands[0]
+    assert env.deck[-1] == 5
+
+
+def test_second_chance_is_usable_during_flip_three():
+    env = position([[12], [], []], [C.FLIP_THREE, C.SECOND_CHANCE, 12, 2])
+    env.step(game.HIT)
+    env.step(2)
+    assert env.status[0] == game.ACTIVE
+    assert env.hands[0] == [12, C.FLIP_THREE, 2]
+
+
+def test_chained_flip_three():
+    env = position([[0], [], []], [C.FLIP_THREE, C.FLIP_THREE, 1, 2, 3, 4, 5])
+    env.step(game.HIT)
+    env.step(2)
+    assert env.hands[0] == [0, C.FLIP_THREE, 1, 2]
+    assert env.pending_card == C.FLIP_THREE
+    env.step(3)
+    assert env.hands[1] == [C.FLIP_THREE, 3, 4, 5]
+    assert env.agent_selection == "player_1"
+
+
+def test_flip7_ends_round_and_bonus_not_doubled():
+    env = position(
+        [[0, 1, 2, 3, 4, 5, C.TIMES_2, C.PLUS_10], [12], [11]], [6], target_score=1
+    )
+    env.step(game.HIT)
+    assert env.scores == [67, 12, 11]
+    assert env.rewards == {"player_0": 67, "player_1": 12, "player_2": 11}
+    assert all(env.terminations.values())
+    assert env.winners == ["player_0"]
+    for agent in env.agent_iter():
+        assert env.last()[2]
+        env.step(None)
+    assert not env.agents
+
+
+def test_flip7_interrupts_forced_draws():
+    env = position(
+        [[0, 1, 2, 3, 4, 5], [], []], [C.FLIP_THREE, 6, 7, 8], target_score=1
+    )
+    env.step(game.HIT)
+    env.step(2)
+    assert env.scores[0] == 36
+    assert env.deck[-1] == 7
+
+
+def test_winner_only_at_round_end_and_shared_tie():
+    env = position([[12], [12], []], target_score=12)
+    env.step(game.STAY)
+    assert not any(env.terminations.values())
+    env.step(game.STAY)
+    env.hands[2] = [C.TIMES_2]
+    env.step(game.STAY)
+    assert env.winners == ["player_0", "player_1"]
+
+
+def test_modifier_only_score():
+    env = position([[C.PLUS_10, C.TIMES_2], [], []])
+    assert env._round_score(0) == 10
+
+
+def test_next_round_keeps_deck_and_rotates_dealer():
+    env = position([[1], [2], [3]], [4, 5, 6])
+    before = len(env.deck)
+    for _ in range(3):
+        env.step(game.STAY)
+    assert env.round_number == 2
+    assert env.dealer == 1
+    assert env.agent_selection == "player_2"
+    assert env.hands == [[5], [6], [4]]
+    assert len(env.deck) == before - 3
+    assert env.discard == [1, 2, 3]
+
+
+def test_reshuffle_excludes_table():
+    env = position([[12], [], []])
+    env.deck = []
+    env.discard = [3]
+    env.step(game.HIT)
+    assert env.hands[0] == [12, 3]
+    assert env.discard == []
+
+
+def test_exhausted_deck_banks_round():
+    env = position([[1], [2], [3]], max_rounds=1)
+    env.deck = []
+    env.discard = []
+    env.step(game.HIT)
+    assert env.scores == [1, 2, 3]
+    assert all(env.truncations.values())
+
+
+def test_second_chance_gift_resumes_remaining_forced_draws():
+    env = position(
+        [[12, C.SECOND_CHANCE], [], []],
+        [C.FLIP_THREE, C.SECOND_CHANCE, 12, 3],
+    )
+    env.step(game.HIT)
+    env.step(2)
+    assert env.pending_card == C.SECOND_CHANCE
+    env.step(3)
+    assert C.SECOND_CHANCE in env.hands[1]
+    assert env.hands[0] == [12, C.FLIP_THREE, 3]
+    assert env.agent_selection == "player_1"
+
+
+def test_deferred_actions_keep_draw_order_after_self_freeze():
+    env = position([[1], [], []], [C.FLIP_THREE, C.FREEZE, C.FLIP_THREE, 2, 3, 4, 5])
+    env.step(game.HIT)
+    env.step(2)
+    assert env.pending_card == C.FREEZE
+    env.step(2)
+    assert env.status[0] == game.FROZEN
+    assert env.agent_selection == "player_0"
+    assert env.pending_card == C.FLIP_THREE
+    assert env.observe("player_0")["action_mask"].tolist() == [0, 0, 0, 1, 1]
+    env.step(3)
+    assert env.hands[1] == [C.FLIP_THREE, 3, 4, 5]
+
+
+def test_opening_deal_pauses_for_actions(monkeypatch):
+    # A no-op shuffle makes the rigged deck deterministic.
+    class RNG:
+        def shuffle(self, deck):
+            pass
+
+    monkeypatch.setattr(game.seeding, "np_random", lambda seed=None: (RNG(), 1))
+    monkeypatch.setattr(game, "make_deck", lambda: [7, 6, 5, C.FREEZE])
+    env = game.raw_env()
+    env.reset()
+    assert env.agent_selection == "player_1"
+    assert env.pending_card == C.FREEZE
+    env.step(4)  # Freeze player 2 before their opening deal; skip them.
+    assert env.hands[0] == [5]
+    assert env.hands[1] == []
+    assert env.hands[2] == [C.FREEZE]
+    assert env.agent_selection == "player_1"
+    assert not env.observe("player_1")["action_mask"][game.STAY]
+
+
+def test_truncation():
+    env = position([[1], [2], [3]], max_rounds=1)
+    for _ in range(3):
+        env.step(game.STAY)
+    assert all(env.truncations.values())
+    assert not any(env.terminations.values())
+    assert env.scores == [1, 2, 3]
+
+
+@pytest.mark.parametrize("num_players", [3, 6, 18])
+def test_random_games_conserve_cards_and_rewards(num_players):
+    for seed in range(10):
+        env = game.raw_env(num_players=num_players, max_rounds=100)
+        env.reset(seed=seed)
+        totals = dict.fromkeys(env.possible_agents, 0)
+        for agent in env.agent_iter(20000):
+            observation, reward, terminated, truncated, _ = env.last()
+            totals[agent] += reward
+            assert env.observation_space(agent).contains(observation)
+            cards = env.deck + env.discard + [c for h in env.hands for c in h]
+            cards += env.deferred
+            cards += [c for k, _, c in env.tasks if k == game.RESOLVE]
+            if env.pending_card is not None:
+                cards.append(env.pending_card)
+            assert Counter(cards) == Counter(game.make_deck())
+            action = (
+                None
+                if terminated or truncated
+                else env.action_space(agent).sample(observation["action_mask"])
+            )
+            env.step(action)
+        assert not env.agents
+        assert list(totals.values()) == env.scores
+
+
+def test_hidden_deck_order_not_observed_and_observations_are_copies():
+    env = position([[1], [2], [3]])
+    before = env.observe("player_0")["observation"]
+    env.deck.reverse()
+    np.testing.assert_array_equal(before, env.observe("player_0")["observation"])
+    before[:] = 99
+    assert not np.all(env.observe("player_0")["observation"] == 99)
+
+
+def test_render():
+    env = game.env(render_mode="ansi")
+    env.reset(seed=5)
+    assert "Flip 7 | round 1" in env.render()
+    env.close()
+
+
+@pytest.mark.parametrize(
+    "kwargs",
+    [
+        {"num_players": 2},
+        {"num_players": 19},
+        {"target_score": 0},
+        {"max_rounds": 0},
+        {"render_mode": "rgb_array"},
+    ],
+)
+def test_invalid_config(kwargs):
+    with pytest.raises(ValueError):
+        game.raw_env(**kwargs)