Skip to content

Dexploarer/toonscape

BranchesTags

Repository files navigation

Toonscape

⚠️ EXPERIMENTAL PROJECT: This is an experimental RuneScape-inspired MMORPG built with SpacetimeDB to explore AI-human gameplay parity, token-efficient observability, and serverless WASM game architecture.

What This Is

Toonscape is a proof-of-concept MMORPG demonstrating:

  • SpacetimeDB as Game Server: Rust WASM modules handling all game logic, no traditional backend needed
  • AI-First Architecture: AI agents and human players share identical APIs, state access, and observability
  • Token-Efficient Telemetry: TOON format reduces AI/LLM context costs by 70-80%
  • OSRS-Accurate Formulas: Authentic Old School RuneScape combat and progression mechanics

This is NOT a production game - it's a research platform for multiplayer game architecture with AI actors.

Current Status

✅ Integrated & Working

Backend (SpacetimeDB):

  • ~20,000 lines of Rust WASM compiled to SpacetimeDB module
  • 105 tables, 147 reducers
  • Tick system (600ms OSRS-accurate timing)
  • Full combat system (melee, ranged, magic with OSRS formulas)
  • All 23 skills (Attack, Strength, Mining, Fishing, etc.)
  • NPC spawning, combat AI, drops, respawning
  • Item system with 16,353 definitions from OSRS data
  • Quest framework (10+ quests defined)
  • Observability: game_event table + tick_event_batch (TOON-encoded)

Content Pipeline:

  • TOON compiler (Rust) - Converts OSRS JSON → .toonw format
  • 16,353 items compiled from osrsbox data
  • NPCs, quests, skills, drops all seeded via SpacetimeDB tables
  • AI comprehension testing suite (validates LLM understanding of TOON format)

Development Tools:

  • SpacetimeDB CLI integration (build, deploy, SQL query)
  • Cargo workspace (3 Rust crates: server, formulas, toon-compiler)
  • Bun workspace (TypeScript packages)
  • Auto-generated TypeScript client SDK (389 files)

🚧 Partially Integrated

Client (React Three Fiber):

  • Project scaffolding exists (apps/client/)
  • SpacetimeDB TypeScript bindings auto-generated
  • Benchmark framework for testing server load
  • NOT playable - no 3D renderer, no UI, no WebSocket connection active

AI Agents:

  • ai_agent_state and llm_request_queue tables in server
  • process_ai_agents scheduled reducer
  • packages/ai-agent-service/ Node.js service (not tested)
  • ElizaOS plugin stub (packages/plugin-toonscape/) with generated types
  • NOT working - service untested, no live AI agents

❌ Not Integrated

  • 3D world rendering (Three.js/R3F planned but not built)
  • Player authentication beyond username/password
  • Real-time multiplayer UI (inventory, chat, minimap)
  • Asset streaming pipeline
  • Production deployment (Railway, cloud hosting)
  • Minigames (Pest Control, Barbarian Assault, etc. - tables defined but no logic)
  • Trading, Grand Exchange (tables exist, minimal logic)
  • PvP systems

About SpacetimeDB

This project is built entirely on SpacetimeDB, a database that replaces your entire backend:

  • No traditional server: Game logic runs in a Rust WASM module
  • No REST/GraphQL: Clients subscribe to tables via WebSocket
  • No ORM: Tables are defined as Rust structs, queries are type-safe
  • No deployment complexity: spacetime publish deploys database + logic together

Key Concept: In traditional architecture, you'd have PostgreSQL + Node.js/Python server + WebSocket server. With SpacetimeDB, you compile Rust to WASM and the database itself runs your game logic.

Learn more: spacetimedb.com

Quick Start

New to the project? See SETUP.md for complete setup instructions.

Important: This is experimental software. The server works, but there's no playable client yet.

Prerequisites

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown

# Install SpacetimeDB CLI
curl -fsSL https://install.spacetimedb.com | bash

# Install Bun (for TypeScript packages)
curl -fsSL https://bun.sh/install | bash

Initial Setup

# Install all dependencies
bun run setup

# Or manually:
cargo build          # Rust dependencies
bun install          # TypeScript dependencies

Build and Deploy

Build order: formulas → server → client types → client

# Build everything (from root)
bun run build

# Or step-by-step:
# 1. Build server (includes formulas via workspace)
make build

# 2. Generate client types
cd apps/client && bun run generate

# 3. Build client
cd ../.. && bun run --filter='./apps/client' build

# Deploy server locally
make deploy-local

# Or deploy to cloud
cd packages/server && spacetime publish toonscape-server

Development Workflow

# Terminal 1: Start SpacetimeDB
spacetime start

# Terminal 2: Build & deploy server
make build && make deploy-local

# Terminal 3: Run client dev server
bun run dev:client

Test the Server

# View logs
spacetime logs toonscape-server --follow

# Query game state
spacetime sql toonscape-server "SELECT * FROM player LIMIT 10"

# Call reducers for testing
spacetime call toonscape-server init

Project Structure

toonscape/
├── packages/            # Shared libraries and packages
│   ├── server/          # SpacetimeDB module (Rust WASM)
│   │   ├── src/
│   │   │   ├── lib.rs      # Main module (all tables, reducers, game logic)
│   │   │   ├── content.rs  # Content builder framework
│   │   │   ├── formulas.rs # Skill-specific formulas
│   │   │   ├── combat_calculations.rs  # Combat formulas
│   │   │   └── toon_encoder.rs  # AI-optimized event encoding
│   │   └── Cargo.toml
│   ├── formulas/        # Shared combat/skill formulas (benchmarkable)
│   ├── ai-agent/        # ElizaOS plugin for AI agents
│   └── assets/          # Asset pipeline (optimization, CDN deployment)
├── apps/                # Runnable applications
│   ├── client/          # React Three Fiber frontend
│   └── docs/            # Mintlify documentation site
│       ├── ARCHITECTURE.md  # System architecture
│       ├── OBSERVABILITY.md # Observability system
│       ├── CODE_MAP.md      # Code navigation
│       ├── TESTING.md       # Testing guide
│       ├── CI_CD.md         # CI/CD pipeline
│       ├── TOON_FORMAT.md   # Toon encoding format
│       ├── QUICK_START.md   # Metadata population guide
│       ├── examples/        # Example integrations
│       └── reports/         # Historical reports
├── Cargo.toml           # Rust workspace configuration
├── package.json         # Bun workspace configuration
└── CLAUDE.md            # Project-specific instructions for Claude Code

Core Features

Combat System (OSRS-Accurate)

  • Combat Triangle: Melee → Ranged → Magic → Melee
  • Formulas: Authentic OSRS max hit, accuracy, and damage calculations
  • Weapon Speeds: 3-7 tick attack speeds (1.8s - 4.2s)
  • Auto-retaliate: Configurable automatic combat
  • Attack Styles: Accurate, Aggressive, Defensive, Controlled, Rapid, Longrange

Skills System

  • Gathering: Mining, Woodcutting, Fishing, Farming, Hunter
  • Artisan: Smithing, Crafting, Cooking, Fletching, Herblore, Runecraft, Construction
  • Combat: Attack, Strength, Defence, Hitpoints, Ranged, Magic, Prayer
  • Support: Firemaking, Agility, Thieving, Slayer
  • XP Formula: Authentic OSRS experience curve (level 99 cap)

World Systems

  • NPCs: 100+ definitions with combat AI, drops, and respawning
  • Items: 140+ definitions with equipment stats, prices, and metadata
  • Objects: Trees, rocks, fishing spots with resource depletion
  • Quests: 10+ quest definitions with requirements and rewards
  • Music: 50+ region-based music tracks

Observability (AI-Optimized)

  • game_event table: SQL-queryable event log with full context
  • tick_event_batch table: Toon-encoded batches (70-80% token reduction for AI/LLM)
  • Native SpacetimeDB: WASM-compatible, no HTTP dependencies
  • Event Types: 20+ types (combat, skills, items, player actions)
  • Metadata: JSON metadata fields for AI context

Game Mechanics

Tick System

TICK_DURATION_MS = 600  // 0.6 seconds per tick (OSRS-accurate)
TICKS_PER_MINUTE = 100  // Theoretical maximum

All server-side actions are tick-based:

  • Movement: 1 tile per tick (walking) or 2 tiles per tick (running)
  • Combat: Weapon-speed dependent (3-7 ticks between attacks)
  • Skills: Action times vary (e.g., 5 ticks for woodcutting)

Combat Formulas

// Effective Level = Base + Prayer + Potion + Style Bonus
effective_attack = base_attack + prayer_bonus + potion_bonus + style_bonus;

// Max Hit (Melee/Ranged)
max_hit = floor(0.5 + effective_strength * (gear_strength_bonus + 64) / 640);

// Accuracy Roll
player_accuracy = effective_attack * (gear_attack_bonus + 64);
opponent_defence = target_defence * (target_defence_bonus + 64);

// Hit Chance
if player_accuracy > opponent_defence {
    hit_chance = 1.0 - (opponent_defence + 2) / (2 * (player_accuracy + 1));
} else {
    hit_chance = player_accuracy / (2 * (opponent_defence + 1));
}

Experience Formula

// XP required for level L
xp_for_level = sum(floor((L + 300 * 2^(L/7)) / 4) for L in 1..level)

// Combat XP rates per damage dealt
MELEE_XP_PER_DAMAGE = 4.0
RANGED_XP_PER_DAMAGE = 4.0
MAGIC_XP_PER_DAMAGE = 2.0
HP_XP_PER_DAMAGE = 1.33

Documentation

Getting Started

Core Documentation

Specialized Documentation

Reports

Historical implementation reports are in apps/docs/reports/

Development

Building

cd packages/server

# Check code
cargo check

# Format code
cargo fmt --all

# Lint code
cargo clippy --all-targets --all-features

# Build WASM
cargo build --target wasm32-unknown-unknown --release

# Or use SpacetimeDB CLI
spacetime build

# Or from root with workspace
cargo build --target wasm32-unknown-unknown --release

Testing

# Unit tests (formulas crate)
cd packages/formulas && cargo test

# Reducer testing
cd packages/server
spacetime publish --local toonscape-server
spacetime call toonscape-server test_reducer_name

Deployment

# Local deployment
spacetime publish --local toonscape-server

# Cloud deployment
spacetime publish toonscape-server

# View status
spacetime list
spacetime logs toonscape-server --follow

Technology Stack (What's Actually Used)

Backend (Integrated & Working)

  • SpacetimeDB 1.11: Combined database + server runtime
  • Rust 1.85+: WASM module development language
  • WASM32: wasm32-unknown-unknown target (no_std compatible)
  • Cargo Workspace: 3 Rust crates (server, formulas, toon-compiler)

Observability (Integrated & Working)

  • Native Tables: game_event (SQL-queryable), tick_event_batch (TOON-encoded)
  • TOON Format: 70-80% token reduction for AI/LLM context
  • SpacetimeDB Logs: Built-in logging with log crate
  • Event Types: 20+ game event types (combat, skills, items, etc.)

Formulas (Integrated & Benchmarked)

  • packages/formulas: Separate crate for combat/skill calculations (no SpacetimeDB deps)
  • Criterion: Benchmark framework (~500ns per combat calculation)
  • OSRS-Accurate: Max hit, accuracy, XP curves match Old School RuneScape

Content Pipeline (Integrated & Working)

  • TOON Compiler: Rust binary that converts OSRS JSON → .toonw format
  • osrsbox Data: 16,353 items, NPCs, quests from osrsbox-db
  • SpacetimeDB Seeding: init reducer populates tables on first publish
  • AI Testing: Python scripts validate LLM comprehension of TOON format

Client (Scaffolded but NOT Working)

  • Bun 1.1+: Package manager (faster than npm/yarn)
  • TypeScript 5.7+: Client code language
  • React Three Fiber: Planned 3D renderer (NOT BUILT)
  • SpacetimeDB SDK: Auto-generated TypeScript types (389 files)
  • Vite: Build tool (configured but no UI exists)

AI Agents (Designed but NOT Working)

  • ElizaOS: Plugin framework (stub exists, untested)
  • OpenAI/Anthropic APIs: LLM providers (configured but no live agents)
  • Node.js Service: packages/ai-agent-service/ (not deployed)
  • TOON Context: Token-efficient game state for LLMs (format ready, not tested with live agents)

AI-First Design Principles

1. Actor Parity

AI agents and human players use identical:

  • SpacetimeDB reducers (actions)
  • Subscription queries (state access)
  • Rate limits (tick-based)
  • Validation rules

2. Observability Equality

All telemetry captures the same data for both:

  • actor_type is metadata, not a behavioral switch
  • Events have identical schemas
  • No hidden advantages for either actor type

3. Context Transparency

Both actors receive the same game context:

  • Same visibility rules
  • Same state representation
  • Same available action set

4. Tick-Bound Fairness

The tick system ensures fairness:

  • All actions process in tick order
  • No actor can exceed tick-rate actions
  • Server authoritative on all state

Experimental Goals

This project explores several research questions:

1. Can SpacetimeDB Replace Traditional Game Servers?

Hypothesis: A Rust WASM module compiled to SpacetimeDB can handle MMORPG-scale game logic without Node.js/Python backends.

Status: ✅ Validated - 20,000 lines of game logic running in WASM with zero traditional backend code.

2. Can AI Agents Have True Parity with Humans?

Hypothesis: AI agents and humans can use identical APIs, state access, and rate limits without special-casing.

Status: 🚧 Partially validated - Server architecture supports parity, but no live AI agents tested yet.

3. Is Token-Efficient Telemetry Viable for AI?

Hypothesis: Schema-first TOON format can reduce LLM context costs by 70-80% vs JSON.

Status: ✅ Validated - TOON compiler working, AI comprehension tests passing, tick_event_batch table functional.

4. Can OSRS Formulas Run in WASM?

Hypothesis: Complex combat/skill formulas can compile to WASM without performance degradation.

Status: ✅ Validated - All formulas benchmarked, running at ~500ns per calculation in native Rust (WASM overhead minimal).

Roadmap (Experimental Phases)

✅ Phase 1: Server Foundation (COMPLETE)

  • SpacetimeDB module with 105 tables, 147 reducers
  • Tick system (600ms OSRS-accurate)
  • Combat system (melee, ranged, magic with OSRS formulas)
  • All 23 skills implemented
  • NPC AI, spawning, respawning, drops
  • Item/equipment system (16,353 items)
  • Native observability (game_event + tick_event_batch)
  • TOON compiler and AI comprehension tests

🚧 Phase 2: Client Proof-of-Concept (IN PROGRESS)

  • SpacetimeDB TypeScript SDK integration
  • Auto-generated client types (389 files)
  • WebSocket connection to SpacetimeDB
  • Basic 3D renderer (Three.js/R3F)
  • Minimal UI (inventory, skills, chat)
  • Client-side interpolation

Goal: Prove a human can connect and perform basic actions (walk, attack, skill).

🔮 Phase 3: AI Agent Experiment (BLOCKED ON PHASE 2)

  • AI agent service deployment
  • ElizaOS plugin activation
  • Live AI agent performing autonomous actions
  • AI fairness testing (APM limits, reaction times)
  • Multi-agent coordination experiments

Goal: Prove AI agents can play alongside humans with true parity.

🔮 Phase 4: Scale Testing (FUTURE)

  • 50+ concurrent AI agents
  • 10+ human players
  • Performance benchmarks (tick processing time)
  • Token cost analysis ($/hour per AI agent)
  • SpacetimeDB hosting cost analysis

Goal: Determine if this architecture scales economically.

Contributing

This is an experimental research project by a single developer. Contributions are welcome, but be aware:

  • The client is not functional yet (Phase 2)
  • AI agents are untested (Phase 3)
  • No production deployment exists
  • Architecture may change dramatically based on experiments

If you want to contribute:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request with clear explanation of what you're testing/validating
  4. Include any performance benchmarks or token cost measurements

License

See LICENSE file (to be added)

Resources

SpacetimeDB

OSRS Game Mechanics

AI/LLM Integration

Support

For questions or issues:

  1. Check apps/docs/ for detailed documentation
  2. Review SpacetimeDB logs: spacetime logs toonscape-server
  3. Open an issue in the repository
  4. Join SpacetimeDB Discord for SpacetimeDB-specific questions

Disclaimer

This is an experimental project for research and learning purposes. It is:

  • Not affiliated with Jagex Ltd. or Old School RuneScape
  • Not intended for production use - it's a proof-of-concept
  • Not feature-complete - client and AI agents are not working yet
  • MIT Licensed (to be added) - use at your own risk

OSRS game mechanics are used for educational purposes under fair use. All OSRS-related trademarks and copyrights belong to Jagex Ltd.

Last Updated: 2026-01-10

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages