Formal Specification
Ball in the Hole (Topa-gropash) — Formal Specification
Albania · dexterity-throw · Confidence: low
← Back to game pageImplementation Suitability
Suitability: engine-readyFidelity: probabilistic-proxyGap-fills: 3
# Topagropë — AI-optimized specification
## General idea
A multi-agent turn-based rolling and spatial evasion game. In the rolling phase, an agent aims a rolling ball toward a line of discrete player holes. If the ball enters hole `j`, Agent `j` becomes the active thrower, causing all other agents to scatter across a 2D grid before a freeze command locks their coordinates; Agent `j` then executes a precision throw to assign a penalty token.
## Formal model
- **Abstraction taken:** The 2D outdoor space is discretized into a 2D coordinate plane `(x, y) ∈ [-10..10] × [0..20]`. The row of holes is located at `y = 0`, indexed `0..N-1`. Rolling accuracy is modeled as a categorical distribution over holes plus a miss state.
- **Player/agent count:** `N` agents (`N = 3..8`, default `N = 4`).
- **Turn model:** Sequential rolling phase, followed by simultaneous scatter tick, then discrete target selection and throw resolution.
## Formal rules
R1. Setup: Each agent `i ∈ {0..N-1}` owns hole `i` at position `(i * 2, 0)` and has `penalties[i] = 0`. Active roller is agent `0`.
R2. Rolling Phase: Active roller executes `roll_ball(aim_hole)`.
- Trajectory resolver selects outcome:
- Enters hole `j ∈ {0..N-1}` with probability `P_enter(j | aim_hole)` [gap-fill: 70% targeted hole, 20% adjacent hole, 10% complete miss].
- If miss: Ball misses all holes. Turn passes to `(active_roller + 1) % N`. Advance to next roll.
R3. Scatter Phase: If ball enters hole `j`:
- Agent `j` is designated `THROWER` at position `(j * 2, 0)`.
- All other agents `k != j` simultaneously select scatter vectors and move `distance ~ Uniform(4, 12)` units away from origin, then `FREEZE`.
R4. Throwing Phase:
- `THROWER` takes up to 3 step units toward chosen target agent `target ∈ {k != j}`.
- `THROWER` executes `throw_at_target(target)`.
- Distance between thrower and target is `D`. Hit probability `P_hit = max(0.15, 0.85 - 0.05 * D)` [gap-fill].
- If hit: `penalties[target] += 1`. Active roller for next round becomes `target`.
- If miss: `penalties[THROWER] += 1`. Active roller for next round becomes `THROWER`.
R5. Elimination and Win Condition:
- When any agent reaches `penalties[i] == 5`, the game ends immediately.
- The agent with the fewest penalties is declared the winner; the agent with 5 penalties is the loser.
R6. [gap-fill] Tie-breaking: If multiple agents share the lowest penalty score when the game terminates, the agent who initiated the most successful hits wins.
## Edge cases
- Tie at the end condition: Resolved by R6 hit count comparison.
- A player with no legal move: Not applicable; legal roll targets and scatter vectors are always valid.
- Repetition / cycles: Bounded because every successful hole entry strictly increments exactly one agent's penalty counter, and max penalties is 5 per agent.
- Simultaneous claims on the same resource or position: Scatter phase moves agents to distinct coordinates using repulsive collision avoidance.
- Player elimination mid-round; turn order repair: The game terminates immediately upon the first agent hitting 5 penalties, eliminating mid-round vacancy issues.
- Resource exhaustion (pieces, tokens, space, time): Penalty counters are bounded integers `0..5`.
- Termination guarantee: why the game provably ends: Guaranteed because every non-miss roll triggers a penalty increment with strictly positive probability, and total game penalties cannot exceed `5 * N`.
## State representation
- Persistent state: `penalties: array[N] of int`, `active_roller_idx: int`, `round_num: int`.
- Per-turn ephemeral state: `hole_struck: int (-1 for miss, 0..N-1)`, `agent_positions: map[AgentID -> (float, float)]`, `thrower_idx: int`.
- Observable information: Fully observable by all agents.
## Action space
- `roll_ball(aim_hole: int)`: Active roller action.
- `scatter(angle: float, speed: float)`: Fleeing agents action upon hole entry.
- `throw_at_target(target_id: int)`: Thrower action targeting a frozen agent.
## Playability notes
- Single-player-vs-AI: Natural; player controls 1 agent against `N-1` AI agents.
- Group games (n>4): Supports up to 8 agents directly without modifying the core state machine.
- Physical-skill games: Ground roll physics and ball throws are abstracted into distance-dependent probability curves.
- What is lost in the adaptation: The sudden physical panic of sprinting away in real time upon seeing the ball roll toward a hole.
## Implementation hints
Simple 2D coordinate tracking with discrete phase transitions. Branching factor is `N` for rolling and `N-1` for target selection. First milestone: Implement single-round roll, scatter coordinate assignment, and throw hit calculation.
Download as JSON
Download the full game corpus entry for this game as structured JSON.
Download JSONCite this page
Ball in the Hole (Topa-gropash) (Albania). (n.d.). Games of Countries. https://gamesofcountries.com/games/al-albania/topagrope
@misc{gamesofcountries-al-albania-topagrope,
title = {Ball in the Hole (Topa-gropash) (Albania)},
year = {n.d.},
publisher = {Games of Countries},
url = {https://gamesofcountries.com/games/al-albania/topagrope}
}