Formal Specification
Traditional Walnut Rolling Game — Formal Specification
Tunisia · dexterity-throw · Confidence: medium
← Back to game pageImplementation Suitability
Suitability: engine-readyFidelity: probabilistic-proxyGap-fills: 2
# El-Karkaa — AI-optimized specification
## General idea
A turn-based dexterity and collision game. Agents roll a heavy shooter walnut from a baseline at distance `D = 4.0m` toward a cluster of target walnuts inside a circle of radius `R = 0.5m`. Struck walnuts driven outside the boundary are captured, awarding bonus rolls to the shooter until all walnuts are cleared.
## Formal model
- **Abstraction taken:** The rolling walnut's trajectory, ground friction, and rotational asymmetry are modeled on a 2D plane with landing coordinates `(x, y) ~ Normal(AimTarget, sigma(Power, Skill))` and 2D elastic collision dynamics.
- **Player/agent count:** `N` agents (default `N = 2`, Player 0 and Player 1).
- **Turn model:** Sequential rolling turns with bonus turn continuation upon scoring a capture.
## Formal rules
R1. Setup: Circle of radius `R = 0.5m` centered at `(0, 4.0m)`. A stack of `M = 8` target walnuts is placed at `(0, 4.0m)`. Baseline at `y = 0`.
R2. Rolling Action:
- Active agent selects `aim_x in [-0.5, 0.5]` and `roll_power in [0.8, 1.2]`.
- Shooter walnut rolls toward target with trajectory affected by ground noise.
R3. Collision & Knock-out:
- Collisions resolve via 2D impulse physics.
- Any target walnut whose center of mass is displaced to distance `> R` from `(0, 4.0m)` is captured by the active agent (`+1 captured walnut`).
- Shooter walnut comes to rest at `(x_shooter, y_shooter)`.
R4. Continuation Rule:
- If at least 1 target walnut was captured, the active agent takes another shot immediately from `(x_shooter, y_shooter)`.
- If 0 walnuts were captured, turn passes to the next agent.
R5. Win Condition: The match ends when all 8 target walnuts are cleared. The agent with the most captured walnuts wins.
## Edge cases
- Tie at the end condition: [gap-fill] If agents finish with 4 captures each on an 8-walnut board, a sudden-death single closest-to-center roll determines the victor.
- A player with no legal move: Not applicable; roll action is always valid.
- Repetition / cycles: [gap-fill] If 20 consecutive non-scoring rolls occur, remaining target walnuts are cleared and scores compared.
- Simultaneous claims on the same resource or position: Sequential rolling order eliminates simultaneous collision ambiguities.
- Player elimination mid-round; turn order repair: Not applicable; 2-player format.
- Resource exhaustion: Monotonically decreasing target walnut pool (8 down to 0).
- Termination guarantee: Enforced by the finite 8-walnut capacity and the 20-turn stagnation threshold.
## State representation
- Persistent state: `scores: Array[N][int]`, `target_positions: List[(float, float)]`, `active_player: int in [0..N-1]`, `stagnation_counter: int`.
- Ephemeral state: `shooter_pos: (float, float)`.
- Observability: Complete, perfect public information.
## Action space
- `roll_walnut(aim_x, power)` where `aim_x in [-0.5, 0.5]`, `power in [0.8, 1.2]`.
## Playability notes
- Single-player-vs-AI: Engine-ready; play against an AI bot balancing roll aim precision against bounce risks.
- Group games (n>4): Extends naturally to `N` players in rotation.
- Physical-skill games: Asymmetric sphere rolling physics and momentum transfer parameterized cleanly.
- What is lost: The fragrant earthy aroma of fresh autumn walnuts and the crack of shell collisions.
## Implementation hints
2D coordinate collision engine. First milestone: implement circular boundary checks and 2D elastic sphere collision before tuning ground noise parameters.
Download as JSON
Download the full game corpus entry for this game as structured JSON.
Download JSONCite this page
Traditional Walnut Rolling Game (Tunisia). (n.d.). Games of Countries. https://gamesofcountries.com/games/tn-tunisia/karkaa
@misc{gamesofcountries-tn-tunisia-karkaa,
title = {Traditional Walnut Rolling Game (Tunisia)},
year = {n.d.},
publisher = {Games of Countries},
url = {https://gamesofcountries.com/games/tn-tunisia/karkaa}
}