Context

Cougr should include more deterministic board games that demonstrate board-wide state updates. Reversi is a strong candidate because one move can flip multiple pieces, making it a useful example of directional validation and batched state mutation.

Goal

Create examples/reversi/ as a standalone Soroban smart contract example that implements a playable two-player Reversi game.

The example should support legal move detection, directional flipping, turn progression, pass handling when no legal move exists, and final score calculation.

Scope

In scope:

• smart contract logic only
• standard Reversi rules
• legal move validation
• piece flipping in all directions
• pass handling and game completion
• final score calculation
• README and CI workflow

Out of scope:

• frontend or graphical interface
• matchmaking or rankings

ECS Design Direction

Suggested components:

Suggested systems:

• MoveValidationSystem
• FlipResolutionSystem
• TurnSystem
• PassSystem
• ScoringSystem
• EndConditionSystem

Contract API

fn init_game(env: Env, player_one: Address, player_two: Address)
fn submit_move(env: Env, player: Address, row: u32, col: u32)
fn get_state(env: Env) -> GameState
fn get_board(env: Env) -> BoardState
fn get_score(env: Env) -> ScoreState

Tests

Add tests covering:

• initialization
• legal move submission
• illegal move rejection
• horizontal, vertical, and diagonal flips
• turn progression
• pass behavior when a player has no legal move
• final scoring at game completion

Deliverables

• examples/reversi/
• contract implementation and tests
• examples/reversi/README.md
• .github/workflows/reversi.yml

Acceptance Criteria

• directional flipping works correctly
• only legal moves are accepted
• pass and completion behavior are correct
• scoring is correct at the end of the game
• documentation and commands use wasm32v1-none
• the example uses clear Cougr-style decomposition

Validation Commands

cd examples/reversi
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
stellar contract build