60Hz · deterministic · pluggable

Deterministic Mouse Training Engine

A fully deterministic simulation engine for mouse dexterity training. Fixed timestep, composable blueprint mutators, platform-stable run identity, and replay verification — built on .NET 8 MAUI.

Explore Read the Handbook

Determinism

Same seed → same simulation → same score

Identity

FNV-1a(seed + mode + mutators) = RunId

Timestep

60Hz fixed + alpha interpolation

Design Principles

The rules that shape every frame.

Determinism is Constitutional

Same seed produces the same simulation and the same score, always. No DateTime.Now, no Random, no platform-dependent floats.

Protocol-Grade Identity

MutatorId, ModeId, and RunId are permanent. FNV-1a hashing with canonical parameter serialization freezes run identity forever.

Warnings are Errors

Library projects enforce TreatWarningsAsErrors. MAUI host opts out only for SDK-generated warnings.

Architecture

Modular Monolith

Domain        → (nothing)     # Leaf: primitives, RNG, run identity
Simulation    → Domain         # Engine: loop, modes, mutators, levels
Audio         → Domain         # Cue system, asset verification
MauiHost      → all three      # Composition root, MAUI platform host

Engine Core

IGameSimulation    # Pluggable game mode (2 methods)
DeterministicLoop  # 60Hz fixed timestep + accumulator
DeterministicRng   # xorshift32, seed-reproducible
MutatorPipeline    # Ordered fold over LevelBlueprint

Blueprint Mutators

Six composable transforms that reshape generated levels before play.

Mutator

Key Params

Effect

NarrowMargin

pct ∈ [0,1]

Scales aperture heights down — tighter gaps

WideMargin

pct ∈ [0,1]

Scales aperture heights up — more forgiving

DifficultyCurve

exp ∈ [0.1,5]

Remaps gate difficulty by index

RhythmLock

div ∈ {2,3,4,6,8}

Quantizes gate phases — rhythmic patterns

GateJitter

str ∈ [0,1]

Deterministic vertical offset via sin()

SegmentBias

seg, amt, shape

Per-segment difficulty bias (Crescendo/Valley/Wave)

Game Modes

ReflexGates

Side-scrolling gate challenge. Oscillating apertures on vertical walls — navigate the cursor through each gate before the scroll catches you.

Pluggable Interface

IGameSimulation is a two-method contract. New game modes plug in without touching the engine core.

Level Generation

LevelBlueprint + ILevelGenerator + MutatorPipeline. Deterministic seed produces identical levels across platforms.

Build & Test

Build

# Build simulation library (0 warnings)
dotnet build src/MouseTrainer.Simulation/

# Run MAUI host (Windows)
# Use Visual Studio, set startup to MauiHost

Test

# Run all 214 tests across 6 categories
dotnet test tests/MouseTrainer.Tests/

# Architecture, Determinism, Levels,
# Mutators, Persistence, Runs