fuel

Reusable Crystal game backend framework

Fuel

Fuel is an MIT-licensed Crystal game backend framework. A game supplies pure account/combat rules and player-specific views; Fuel owns identity, persistence, sessions, joining, matching, transport, reliable effects and recovery.

Status: 0.3 development preview. One backend process, tested Crystal 1.22.1 and PostgreSQL 17. Pin both peers to the same reviewed release; development APIs may change. No registry publication or production deployment is implied.

Deliberate limits

  • All active session data lives in RAM, including positions, turns and solo runs. Restarting the backend loses those sessions. The client receives session_lost; reconnect cannot restore them.
  • PostgreSQL is the only database for persistent data. Other database engines are not planned.
  • Every session belongs to one backend instance. Cross-instance sessions and interactions between players on different instances are not supported.
  • Multi-instance player stickiness, moving players for scale-down and automatic rebalancing after scale-up are separate roadmap items.

Start here

Getting started · Architecture and storage · Wire API · Security · Migration guide

# shard.yml in your game
dependencies:
  fuel:
    github: Xanders/fuel
    version: ~> 0.3.0

Until a version tag is published, pin a reviewed commit instead of using the version constraint above.

Implement Fuel::Rules for RAM gameplay and Fuel::AccountRules for permanent game state/actions. Fuel::Runtime runs the shared lifecycle, fixed-step ticker, FIFO durable effects and optional analytics. The counter example is a complete neutral server using the simpler completion hook.

Included services

  • Optional trusted issuer enrollment/login, separate from owner-confirmed transfer, with one-time grants and ordinary Fuel bindings afterward.

  • Permanent guest devices, independent device bindings, owner-confirmed six-character transfer, revocation and account deletion.

  • Pure persistent account hooks, sorted multi-account transactions, exact action receipts, terminal summaries and HTTP recovery after RAM session loss.

  • Bounded per-room FIFO effects, one head in flight, explicit saving backpressure and shared drain/health lifecycle.

  • Private invite codes and HTTPS links, public rooms, FIFO automatch, trusted co-op party matching.

  • Serial session commands, per-viewer revisions, epoch fencing, exact-ID receipts, realtime input sequences, bounded fixed-step catch-up.

  • JSON HTTP, long polling and bounded WebSocket transport.

  • Best-score leaderboards and outcome ratings; games own display names and scoring rules.

  • Instance-global, session, guild-policy and private chat; bounded RAM and optional PostgreSQL history per kind, mutes, reports and configurable literal-word censor/glyph variants.

  • Consumer-provided localized dictionary name generation.

  • Optional Questmetry delivery with a PostgreSQL outbox, stable event IDs, retry and opt-out. No analytics service is contacted unless configured.

Only pg is a direct runtime shard dependency; db is transitive. EventWinder is not required.

Test

docker compose -p fuel-test run --rm test
docker compose -p fuel-test down

The test database is disposable, has no host port and uses tmpfs. Override FUEL_TEST_SUBNET if its test network conflicts with your host. Contributing explains TDD and review.

The companion Dart SDK and Flutter/Flame bridges keep network code independent of the renderer.

Repository

fuel

Owner
Statistic
  • 0
  • 0
  • 3
  • 0
  • 1
  • 6 days ago
  • October 24, 2026
License

MIT License

Links
Synced at

Tue, 10 Nov 2026 12:27:42 GMT

Languages