FRONTIDE

Ride the Living Front. FRONTIDE is a deterministic RTS framework built on Bevy ECS with a handful of examples (tower defense, MOBA mini, goldens, hook demos) proving the APIs end-to-end. The repo currently hosts three major surfaces:

• frontide/core — fixed-tick scheduling, Q16.16 numerics, deterministic RNG, snapshot helpers.
• frontide/orders — deterministic command buffering with action ordering and latency controls. The project is framework-first: gameplay logic must live in example crates or data packs while the frontide_* crates stay faction-agnostic and deterministic.

Quickstart

# Launch the tower defense sandbox
cargo run -p frontide_examples_tower_defense

# Explore framework demos from a single CLI
cargo run -p frontide_examples_runner -- list
cargo run -p frontide_examples_runner -- run tower-defense --release

# Run determinism goldens, visual hashes, stress sims, and replay checks
cargo run -p frontide_examples_goldens

# Generate a deterministic map asset (same seed → same bytes)
cargo run -p frontide_io --bin maptool -- build --seed 0xdeadbeef --out target/demo.frontide-map

# Build the documentation site (requires `mdbook` in PATH)
just docs

# Execute the full test suite (framework + examples)
cargo test

The workspace targets Rust stable. Tests are expected to pass on Linux, macOS, and Windows with identical hashes for determinism checks.

Workspace Layout

Path / Crate	Purpose
frontide/core	Core deterministic primitives (time, numerics, RNG, determinism helpers).
frontide/orders	Lockstep command queues and latency scheduling.
frontide/tech	Data-driven tech graphs and research queues.
frontide/fow	Fog-of-war state, sensor handling, and memory tracking.
frontide/influence	Influence grids with deterministic budgets, decay/diffusion, and hashing.
frontide/ui	Shared HUD widgets, minimap overlay, and tick telemetry taps (see docs/UI_KIT_USAGE.md for integration patterns).
frontide/examples/goldens	Cross-platform determinism fixtures (FoW, influence, tech).
docs/	Roadmaps, design notes, binary format specs (see docs/README.md for a navigation hub).
scripts/	Helper scripts for generating deterministic assets.

Determinism Guardrails

FRONTIDE follows a strict determinism playbook:

1. Fixed schedules only. Simulation runs in a dedicated FixedSimSchedule; Update must not mutate state (flag_main_schedule_violation reveals misuse in debug builds).
2. Fixed-point math. All spatial and gameplay math uses SimNum (Q16.16) with saturating helpers.
3. Isolated RNG streams. A xorshift128+ facade exposes stream IDs for map/combat/neutral/fx/ability work.
4. Ordered systems. Every ECS system lives in an explicit FixedCoreSet ordering chain.
5. Command envelopes. Commands are stamped (tick, player, action_id, payload) and sorted before execution so the authority and every replica observe the same order.

Contributing

1. Read AGENTS.md and the engine/game checklists in docs/ for the current milestone map.
2. Prefer editing frontide_* crates for reusable systems; place example-specific logic in the frontide/examples/* crates or data packs as they come online.
3. Run cargo fmt and cargo test before submitting changes.
4. Describe deterministic implications (tempo, field interaction, skill expression) in change summaries.

Issues and PRs that push the framework toward the roadmap while maintaining determinism are very welcome.