Fortress Rollback Godot

A GDScript-only port of fortress-rollback — a fortified, deterministic, GGPO-inspired rollback networking library — targeting Godot 4.x.

[!WARNING] This project is in an early development phase. Local sync-test sessions and an external-input rollback core are implemented. Fixed-membership byte sessions include bounded input exchange and rollback. Optional SignalFish binary relay and direct WebRTC byte delivery are implemented. Browser release validation remains planned.

AI-Assisted Development Notice

This repository is developed with heavy AI-assistance and carries a generic agentic harness (inspired by unity-helpers):

• Every agent front-end (Claude Code, Codex, Copilot, OpenCode, Cursor, Gemini CLI, Windsurf, Cline, …) reads a thin pointer file that delegates to a single canonical context document.
• The canonical context and all skills live under .llm/.
• Skills follow the open Agent Skills SKILL.md standard, with generated discovery stubs under .claude/skills/ and .agents/skills/.
• Every file in the harness is capped at 300 lines (hard limit), enforced by tests, git hooks, and CI.

See .llm/context.md for the full operating manual. GitHub operations use authenticated MCP first and authenticated gh CLI for capability gaps.

Quick Start

Run the offline example with Godot 4.3 or newer:

godot --path . res://examples/offline/offline.tscn

Move the two players with WASD and the arrow keys. The example uses the shipped driver and complete integer snapshots while sync-test repeatedly rewinds gameplay.

Run the packet-loss example with two independent byte sessions:

godot --path . res://examples/peer/peer.tscn

Move players with WASD and the arrow keys. Toggle packet loss, reordering or a partition to observe prediction stalls and recovery. Delivery runs in process.

To add rollback to your own game, follow the integration guide. It covers inputs, snapshots, the frame loop, stalls, errors and sounds that must not replay after rollback.

Try its playable effects example:

godot --path . res://examples/integration/integration.tscn

Move with A/D or arrows and fire with Space. Press 1/2/3 to delay remote input; watch predicted flashes disappear while confirmed effects play once. R restarts.

For a browser game, follow the online example guide to install the optional SignalFish SDK and export examples/online/online.tscn.

Create a room and share its code with another player. Both players ready up; the host starts the game. WASD or arrow keys move your player. The scene uses WebRTC with relay fallback and shows confirmation, stalls and terminal failures. Leave and create a fresh room to restart.

Contributor tooling:

# Install git hooks (blocks commits that break the harness)
make hooks

# Validate the entire .llm harness
make lint-llm

# Run the harness self-tests
make test-llm

# Regenerate the skills index + agent discovery stubs
make llm-index

Implementation and verification

PLAN.md defines the roadmap and supported product contracts. Reference baseline documents verified source/tool pins and reproducible upstream/native/web probes. The interface ADR and evidence policy define the next implementation gates. These development artifacts do not imply that a supported browser release is available.

The session guide documents the shared expert engine, bounded snapshots and thin game driver. The raw input queue provides bounded per-player history. The protocol codec specifies bounded binary messages for the byte session layer, with independent native and exported-Web vectors. The fixed-peer handshake consumes those bytes, validates agreement and peer identity, and reports synchronization progress or specific mismatches. Protocol time and request tokens come from the caller. The byte session guide connects that handshake, bounded input exchange and the shared game driver. The application selects delivery and drains bounded packet/event/diagnostic queues. The optional SignalFish membership seam freezes room UUIDs into stable player slots and validates SDK plans before mesh setup. The SignalFish relay adapter delivers opaque binary packets with bounded queues, recipient filtering and explicit send pressure. The SignalFish WebRTC adapter owns bounded direct bytes through the SDK mesh. The fallback coordinator keeps mixed direct/relay paths in one session and restores ready direct links. Live browser recovery and the release matrix remain separate gates. Run make test-godot for unit tests or make queue-probes GODOT=/path/to/godot for direct pinned Rust/Godot queue comparisons. make handshake-probes compares actual upstream handshake observations with the Godot endpoint. make p2p-probes compares real upstream sessions through packet faults. Rust is development-only.

License

MIT