Context

Cougr benefits from examples that demonstrate deterministic, rules-heavy gameplay where state transitions are easy to validate and test. Sudoku is a strong fit for this because it is compact, fully on-chain friendly, and centered around constraint validation rather than animation or large mutable worlds.

This example would strengthen the repository in two ways:

• it adds a board-based puzzle game with clear invariants
• it demonstrates how to model strict rule validation and progression using Cougr-oriented structure

There is currently no example that focuses on a single-player logic puzzle with dense rule checking and a compact board state.

Goal

Create examples/sudoku/ as a standalone Soroban smart contract example that implements a playable Sudoku puzzle with deterministic validation rules.

The example should allow a player to initialize a puzzle, submit values into editable cells, reject invalid placements, and detect puzzle completion. The implementation should be structured as a Cougr example rather than a plain monolithic contract.

Scope

In scope:

• smart contract logic only
• puzzle initialization from a predefined board or test fixture
• validation of moves against Sudoku rules
• tracking of editable versus fixed cells
• completion detection
• README and CI workflow for the example

Out of scope:

• frontend or graphical interface
• random puzzle generation on-chain
• difficulty generation algorithms
• multiplayer or leaderboard features

Gameplay Flow

1. Initialize a Sudoku board with fixed cells and empty editable cells.
2. Player submits a value for a target cell.
3. Contract verifies that:
   • the cell is editable
   • the value is in range
   • the placement does not violate row, column, or 3x3 block constraints
4. If valid, the board is updated.
5. If the board is fully and validly completed, the game status changes to solved.

ECS Design Direction

The implementation should use clear Cougr-style decomposition so the example teaches structure, not only behavior.

Suggested components:

Suggested systems:

• PlacementValidationSystem — validates row, column, and block constraints
• BoardUpdateSystem — applies valid moves to the board
• CompletionSystem — checks whether the puzzle is solved
• InputSystem — validates allowed value range and editability of target cells

The final design does not need to match these names exactly, but the example should clearly separate validation, mutation, and completion logic.

Contract API

A minimal API should include:

fn init_game(env: Env)
fn submit_value(env: Env, row: u32, col: u32, value: u32)
fn get_state(env: Env) -> GameState
fn get_cell(env: Env, row: u32, col: u32) -> CellState
fn is_solved(env: Env) -> bool

The exact return types may vary, but the public API should be concise, stable, and easy to test.

Implementation Notes

• Keep the first version deterministic by using a known puzzle fixture rather than introducing puzzle generation.
• Prefer a compact board representation to avoid unnecessary state bloat.
• Make invalid move rejection explicit and testable.
• Keep contract entrypoints thin and move rule logic into helper functions or systems.
• Ensure the example reads as a Cougr example: state should be organized by gameplay responsibility, not as one oversized struct with inline rule handling everywhere.

Tests

Add tests covering at minimum:

• successful initialization
• reading initial board state
• submitting a valid value into an editable cell
• rejecting writes to fixed cells
• rejecting out-of-range values
• rejecting row conflicts
• rejecting column conflicts
• rejecting 3x3 block conflicts
• solving the puzzle through a valid sequence
• rejecting additional moves after the puzzle is solved, if that is the chosen rule

Tests should read like short puzzle-progression scenarios rather than isolated implementation details.

Deliverables

• examples/sudoku/ example project
• contract implementation and tests
• examples/sudoku/README.md
• .github/workflows/sudoku.yml

Acceptance Criteria

• examples/sudoku/ builds and tests successfully
• all documented commands use wasm32v1-none
• the example enforces standard Sudoku constraints correctly
• fixed cells cannot be modified
• puzzle completion is detected correctly
• the code is structured with clear Cougr-style component and system decomposition
• the README explains the puzzle model, architecture, contract API, and build/test commands
• CI for the example is added and aligned with existing example workflows

Validation Commands

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

References

• examples/tic_tac_toe/ for board-oriented turn/state handling
• examples/snake/ and examples/tetris/ for grid-oriented game structure
• README.md and ARCHITECTURE.md for repository-level Cougr positioning