Mechanics and races

Theme shape

theme.yaml declares the gameplay groups and attributes. Every race has one task per group; a player selects one owned instance per group.

The server selects and stores the task combination, validates the lineup, calculates every result and returns an explainable outcome.

Determinism

• A seed is chosen or stored by the server.
• The same seed, lineup and mechanics version produce the same result.
• Results carry a trace (trial_results) for auditing and replays.
• The client never chooses the authoritative seed or result.

Mechanics profile

The versioned mechanics profile controls:

• race layout (per_group, mono, custom),
• task counts,
• win condition (majority, best_of, total_score, margin),
• variance and caps,
• fusion input counts and spread,
• ability and quiz rules.

MechanicsConfiguration validates the profile against the theme (group and attribute counts, layout keys, bounds). Saving creates a version and activates it atomically with an audit event. The admin Mechanics page exposes the form and version activation.

Race calculation

RaceCalculationService:

1. validates the lineup and rules;
2. resolves environment modifiers;
3. runs the trials deterministically;
4. resolves the outcome;
5. grants rewards idempotently;
6. stores the replay and the trace.

Fusion and breeding

• Fusion consumes input instances and produces a new one according to the theme rules.
• Breeding follows the theme's reproductive system and the life cycle (maturity, window, lifespan).
• A consumed instance is removed exactly once.

Life cycle

• Active-day clock, integer age and maturity.
• Death at lifespan + 1.
• Paid lifespan extension and maturity acceleration are configurable.
• Reproductive systems are resolved from the theme and life-history data.

Simulations

php artisan animalia:simulate:races
php artisan animalia:simulate:economy
php artisan animalia:simulate:all
php artisan animalia:simulate:competitions
php artisan animalia:simulate:fusion-cadence
php artisan animalia:simulate:abilities
php artisan animalia:simulate:card-rewards

These are diagnostics. They do not change game data.

Next steps

• Abilities and quiz
• Admin panel