Formal Specification
Dirt-Hole Marbles — Formal Specification
Slovenia · dexterity-small · Confidence: low
← Back to game pageImplementation Suitability
Suitability: engine-readyFidelity: probabilistic-proxyGap-fills: 1
# Frnikolanje — AI-optimized specification
## General idea
A turn-based 2D precision flicking game where agents navigate spherical marble tokens across a friction plane toward a central hole target. Qualifying a marble into the hole unlocks an offensive "hunter" state, allowing the agent to target and eliminate opponent marbles through direct projectile strikes.
## Formal model
- **Abstraction taken:** Ground rolling friction and thumb flick impulses are abstracted into 2D velocity vectors with Gaussian landing noise. The central hole is modeled as a sink basin with capture radius m.
- **Player/agent count:** agents (, with , standard ).
- **Turn model:** Sequential turn queue with bonus turns awarded upon qualifying or striking.
## Formal rules
R1. Setup:
- 2D bounded arena m with central hole at .
- Each agent starts with 1 marble token located at baseline m.
- Qualification state initialized: .
R2. Opening Toss & Turn Ordering:
- Agents throw from toward . Turn order sorted ascending by .
R3. Flick Action:
- Active agent declares `flick_marble(angle: float, force: float)`.
- Landing displacement .
- New position: .
R4. Hole Qualification:
- If :
- Agent becomes qualified: .
- Marble position is reset to hole center .
- Agent earns an immediate consecutive turn.
R5. Offensive Elimination:
- If , agent can target opponent marble .
- Strike check: If trajectory passes within collision radius m of opponent :
- Opponent is ELIMINATED and marble captured by .
- earns an immediate bonus turn.
- If strike misses, turn ends; marble rests at landing position.
R6. Victory Condition:
- The last remaining agent with an active marble on the board wins the game.
- [gap-fill] Turn horizon capped at rounds; if multiple agents survive, agent with most captured marbles wins.
## Edge cases
- Tie at the end condition: Tied captured marbles at broken by distance to the central hole.
- A player with no legal move: Flick action is always available while marble remains active.
- Repetition / cycles: Bounded by strictly decreasing active marble count and hard turn cap .
- Simultaneous claims on the same resource or position: Marbles in the hole are stacked or displaced outwards radially.
- Player elimination mid-round; turn order repair: Eliminated agent is removed from turn queue immediately.
- Resource exhaustion: Non-consumable playing arena; marbles are captured permanently for the round.
- Termination guarantee: Strictly decreasing surviving agent count guarantees finite termination.
## State representation
- Persistent state: `marble_positions: dict[int, tuple[float, float]]`, `is_qualified: dict[int, bool]`, `captured_counts: dict[int, int]`, `active_agents: list[int]`.
- Ephemeral turn state: `flick_trajectory: tuple[float, float]`, `hole_entered: bool`, `strike_occurred: bool`.
- Observable information: Fully observable (all coordinates, qualification flags, and captures are public).
## Action space
- `flick_marble(target_x: float, target_y: float, force: float)`: Parameterized marble flick.
## Playability notes
- Single-player-vs-AI: Highly natural; AI balances the trade-off between qualifying in the hole vs positioning for safe defensive concealment.
- Group games (n>4): Natively scales to 2–6 agents.
- Physical-skill games: Thumb flick impulse and surface friction modeled via Gaussian spatial noise.
- What is lost: Tactile glass marble feel, dusty knees on spring dirt.
## Implementation hints
Discrete 2D physics simulation with line-segment intersection checks for collisions and circle-point distance tests for the hole. First milestone: implement 2-agent qualification and strike loop before tuning multi-agent aiming AI.
Download as JSON
Download the full game corpus entry for this game as structured JSON.
Download JSONCite this page
Dirt-Hole Marbles (Slovenia). (n.d.). Games of Countries. https://gamesofcountries.com/games/si-slovenia/frnikolanje
@misc{gamesofcountries-si-slovenia-frnikolanje,
title = {Dirt-Hole Marbles (Slovenia)},
year = {n.d.},
publisher = {Games of Countries},
url = {https://gamesofcountries.com/games/si-slovenia/frnikolanje}
}