CUBE3D

Fully on-chain multiplayer Pac-Man built with BOLT ECS (MagicBlock) + Ephemeral Rollups for real-time gameplay on Solana.

Stack

Layer	Tech
On-chain framework	BOLT ECS (extends Anchor)
Real-time engine	Ephemeral Rollups (MagicBlock)
Language	Rust (programs) / TypeScript (frontend)
Frontend	Next.js 16 + React 19 + Tailwind 4

BOLT ECS (Entity Component System)

• Entity — just an ID (a PDA on Solana). No data, no logic.
• Component — pure data struct (= a Solana account). Position, health, score, etc.
• System — a Solana program that contains the logic. Receives components, modifies them, returns them.

Each element in the game (player, map, monster) is an Entity with Components attached. The World program handles PDA derivation, account routing, and component lifecycle — you just declare what components your system needs.

Ephemeral Rollups (ER)

A temporary mini-Solana dedicated to the game session.

• Cost: 0 SOL per transaction (gasless)
• Latency: ~50ms per transaction
• Regions: EU (eu.magicblock.app), US (us.magicblock.app), Asia (as.magicblock.app)

All 5 components use #[component(delegate)] for ER support.

1. INIT (L1)
   Create World + map entity + 5 components
   init-map: spawn snake at random bottom corner, 3 ghosts at other corners, set status Playing

2. DELEGATE (L1 → ER)
   DelegateComponent for all 5 component PDAs (2 batches)
   Accounts locked on L1, cloned into ER

3. GAMEPLAY (ER — all gasless, ~50ms)
   move-player: wall check, snake body block, coin pickup, kill check, anti-teleport, spawn lock
   move-monster: BFS pathfinding (snake + 3 ghosts), ghost wander, kill check
   Session keys: wallet signs once, then moves auto-sign (no popup)

4. END GAME (ER → L1)
   end-game system checks: timeout / all coins / no players
   Commit & Undelegate → final scores permanent on Solana L1

Real-time state sync

Every frontend connects to the ER via WebSocket (onAccountChange). When any account changes (player moves, coin collected, monster moves), all connected clients receive the update instantly. No game server needed.

Components (6)

Component	Fields	Description
Position	x (i64), y (i64), spawn_x (i64), spawn_y (i64), orientation (u16), sprinting (bool)	Player/entity position + spawn point. Coords x100 (1300 = tile 13, 1350 = tile 13 right quadrant)
PlayerState	authority (Pubkey), alive (bool), spawn_time (i64), locked (bool), lock_time (i64), coins_saved (u16), respawn_time (i64)	Player stats, life status, spawn lock, respawn timer
CollectedCoins	bits ([u8; 421]), count (u16)	Per-player coin bitset — 4 coins per tile (1 per quadrant), 841 tiles × 4 = 3364 bits
MapConfig	seed (u64), width (u16), height (u16), active_players (u8), total_coins (u16), start_time (i64), status (GameStatus)	Map metadata + game state (Waiting/Playing/Finished)
PlayerRegistry	players ([[u8;32]; 10]), player_states ([[u8;32]; 10]), count (u8)	Registry of active players (Position + PlayerState PDAs). Max 10
Monster	x (i64), y (i64), direction (u16), body ([i64; 12]), ghosts ([i64; 6]), ghosts_dir ([u16; 3])	Snake head (centered, +50) + 6 body segments + 3 ghost positions + ghost directions. All coords x100

Systems (5)

System	Input Components	Description
init-map	MapConfig, Monster	Parse totalCoins from args. Snake spawns at random bottom corner (start_time % 2), 3 ghosts at other 3 corners. Init snake body. Set status to Playing
spawn-player	Position, PlayerState, MapConfig, PlayerRegistry	Spawn player in ghost house center (10 predefined positions in x=12-16, y=12-16). Init alive=true, coins zeroed, locked=false. Register in PlayerRegistry. Increment active_players
move-player	Position, CollectedCoins, MapConfig, Monster, PlayerState	Sub-tile movement (0.25 tile per move). Wall check. Snake body block. Per-quadrant coin pickup. Rectangle kill check (snake) + quadrant kill check (ghosts). Spawn lock (5s + coin reset)
move-monster	Monster, MapConfig, Position, PlayerState, CollectedCoins + remaining_accounts	Snake: BFS + 25 unit/tick smooth movement, body shifts on tile change. Ghosts: BFS to tile, sub-tile chase on same tile (targets exact player position). Random wander when no target. Respawn check (revives dead players after 15s). Kill check vs all players
end-game	MapConfig, PlayerState	Check 3 end conditions: all coins collected, no active players, timeout (50 min)

Monsters

Snake (1)

• 1 head (full tile size, centered at +50) + 6 body segments
• Moves 25 units per tick (0.25 tile) — smooth sub-tile movement
• Body segments shift only when head enters a new tile (body stays tile-aligned)
• BFS pathfinding toward nearest alive player within detection range
• Random wander when no target (erratic, constrained by body)
• Players cannot walk through the snake body (SnakeCollision error)
• Kill check: centered rectangle collision — player dies if inside the snake's 100x100 hitbox centered on the head position (sx-50 to sx+50)

Ghosts (3)

• Quarter-tile size each (no body) — same size as the player
• Moves 25 units per tick (0.25 tile) — smooth sub-tile movement
• BFS pathfinding to reach the player's tile, then sub-tile chase to reach exact position (targets the player's quadrant)
• Sub-tile chase checks all players (local + remaining_accounts) for exact coordinates
• Ghost wander when no target: continue straight in corridors, pick random direction at intersections, no U-turn (Pac-Man style)
• Cannot overlap each other or the snake (anti-collision bitset)
• Kill check: quadrant collision — player dies if in the same tile AND same quadrant as a ghost

Detection range

All monsters have a 20-tile Manhattan distance detection range. Beyond that, they wander randomly. This means you can avoid monsters by staying far enough away, but they'll chase you aggressively once you're in range.

Monster tick

The frontend sends a moveMonster transaction every 400ms via session key. The on-chain system moves all 4 monsters in a single transaction (400k CU budget).

Respawn

When a player dies (monster kill), they are teleported to their spawn point and must wait 15 seconds before respawning. The respawn is handled by move-monster (runs every 400ms even when dead). On death, collected coins are reset (bitset cleared). coins_saved is preserved.

Spawn lock & coin reset

When a player enters the safe zone (ghost house) from outside:

1. CollectedCoins bits reset to zero → all coins respawn on the map for that player
2. coins_saved += collected_coins.count → score is banked permanently
3. CollectedCoins count reset to zero
4. locked = true, lock_time = now + 5 seconds

During the lock:

• Player can move freely inside the safe zone
• Player cannot exit the safe zone until lock_time expires (on-chain Locked error)
• Frontend shows countdown timer

Map

Fixed 29x29 Pac-Man layout with ghost house safe zone.

• 841 tiles total (29 x 29)
• Safe zone (ghost house): x 12-16, y 12-16, with entrances at (14,11), (14,17), (11,14), (17,14)
• Coins: 4 per walkable tile (one per quadrant), ~1440 coins total
• Integer-only math (no floats — BPF float emulation differs from native)
• Coords x100: on-chain positions are multiplied by 100 (1350 = tile 13, right half). Sub-tile movement in 25-unit steps
• Bitset storage: collected coins stored as 421-byte bitset per player in CollectedCoins component (4 bits per tile)
• Map layout identical in Rust (libs/map-utils/src/bsp.rs) and TypeScript (app/frontend/app/lib/map-gen.ts)

Anti-cheat & Desync

All validation is on-chain — the frontend is untrusted.

Desync system

Instead of failing transactions on invalid moves, move-player uses a desync flag. When a validation fails (wall, teleport, snake body), the transaction still confirms but player_state.desync = true is set and the move is rejected silently. While desync:

• No movement is processed
• The frontend detects the flag via WebSocket subscription
• The frontend sends a resync tx with the current on-chain coordinates
• When the coords match, desync = false and the player can move again

This prevents tx failures from causing SOL loss and keeps the client synchronized.

Validation checks

Check	Behavior
Anti-teleport (max 25 units walk / 50 sprint)	Sets desync = true
Wall collision	Sets desync = true
Snake body collision	Sets desync = true
Spawn lock (can't exit safe zone during cooldown)	Move silently ignored (no desync)
Game must be Playing	require! — tx fails
Player must be alive	require! — tx fails
Snake kill (centered rectangle — player inside 100x100 box centered on snake head)	Sets alive = false
Ghost kill (same tile + same quadrant)	Sets alive = false
Spawn position validation	require! — tx fails

Monster rate limit

move-monster uses a slot-based rate limit (last_monster_slot in MapConfig). Monsters only move if current_slot >= last_slot + 3 (~150ms on ER). Multiple clients calling moveMonster in the same window only results in one move. Kill check and respawn always run regardless of rate limit.

Project structure

CUBE3D/
├── programs-ecs/
│   ├── components/
│   │   ├── position/           # x, y, orientation, sprinting
│   │   ├── player-state/       # authority, alive, locked, coins_saved, respawn_time
│   │   ├── collected-coins/    # per-player coin bitset (4 coins/tile, 421 bytes)
│   │   ├── map-config/         # seed, width, height, total_coins, status
│   │   ├── player-registry/    # Position + PlayerState PDAs, max 10 players
│   │   └── monster/            # snake (head + body) + 3 ghosts (positions + directions)
│   └── systems/
│       ├── init-map/           # Spawn monsters at corners, set Playing
│       ├── spawn-player/       # Register player in ghost house
│       ├── move-player/        # Movement + coins + anti-teleport + kill check + spawn lock
│       ├── move-monster/       # BFS pathfinding + ghost wander + anti-collision + kill
│       └── end-game/           # Check win/lose/timeout conditions
├── libs/
│   └── map-utils/              # Shared map bitset, coin detection, PRNG (Rust)
├── app/
│   └── frontend/               # Next.js 16 + React 19 + Tailwind 4 (see frontend/README.md)
├── tests/                      # E2E tests
├── docs/                       # Architecture & decisions
├── patches/                    # session-keys custom lib
└── Anchor.toml

Local dev setup

Prerequisites

• Solana CLI 2.3+
• Anchor 0.32.1+
• Bolt CLI 0.2.4+
• Surfpool (local Solana validator)
• Ephemeral Validator
• Node.js 18+

1. Start local validators

# Terminal 1 — L1 (Surfpool)
surfpool start --rpc-url 'https://devnet.helius-rpc.com/?api-key=YOUR_KEY'

# Terminal 2 — Ephemeral Rollup
ephemeral-validator --remotes "http://localhost:8899" --remotes "ws://localhost:8900" -l "7799" --lifecycle ephemeral

2. Build & deploy programs

bolt build
anchor deploy --provider.cluster http://localhost:8899

Important: After redeploying, restart the ER validator and delete magicblock-test-storage/ for a clean start. The ER caches program binaries.

3. Run the frontend

cd app/frontend
npm install
npm run dev

Open http://localhost:3000, connect a Solana wallet (Phantom on localhost).

Game flow

1. Create Game — creates world + map entity + 6 components + init-map + delegates to ER (2 wallet approvals)
2. Join Game — creates session key + player entity + 4 components + delegates + spawns in ghost house (1 wallet approval)
3. Play — arrow keys to move, Shift to sprint. Collect coins, avoid monsters. Session key auto-signs (no popups)
4. Safe zone — enter ghost house to bank coins (5s lock, coins respawn)
5. Death — monster catches you → respawn at spawn after 15s countdown
6. End game — timeout, all coins collected, or no players alive

Deploy to devnet

bolt build
anchor deploy --provider.cluster 'https://devnet.helius-rpc.com/?api-key=YOUR_KEY'

Program IDs (devnet)

Program	ID
position	D6arufzkdPfmne2TrUGaMSA73HEQvSMpSpW81EtrpfEg
player-state	3R6wE1awZdKHDSGchGhS2xHKKB2QSR1xQfCB9GgagZah
map-config	4tNjQVh1bSjqMYNRoWK8jpgvBr1suSjX7adpt6vrgsLV
player-registry	3KYSbQkcqDoRdRUbyT6HGU8a67VCzuhKkfQTUHLDmKLL
monster	8xPThZpo5mJf9avTuGbgDnLKojHxuGF5V53iiUUn6yT2
init-map	5CB1AR5p23rHraxA367Rt2cyFC3kLRxDga8nywY5dNEV
spawn-player	62SXEXeaqYAQ4PTL3Vgu5LU1bt5iwCYwPvkjmVWUWKnE
move-player	GX7dFnXqthzMkBdsvEwsqtprcaPLHUVbxkC2G2j4L8Ap
move-monster	EJYmw1gd3eq6ig6aDMAqNfvN3ZiFqsGo5FCCWZrtCok
end-game	DNPfzbrCvfodqjTzqgcRYRSfxVyivvZ3BoThcNXoPXgM

Solana BPF constraints

These constraints shaped the architecture:

• Heap limit 32KB: no Vec, no heap allocations. All arrays are stack-allocated ([u8; 106], [u16; MAX_TILES])
• Stack frame limit 4096 bytes: BFS arrays (~3.5KB) allocated once in execute() and passed by reference to bfs_direction(). Cannot call BFS as a function with its own stack arrays 4 times
• No floats: BPF emulates f64 in software with different rounding than native. All math is integer-only
• Compute budget: default 200k CU per tx. move-monster needs 400k CU (4 BFS pathfinding calls). Set via ComputeBudgetProgram.setComputeUnitLimit() — free on ER
• JSON args: BOLT SDK serializes args as JSON text ({"x":300,"y":100}). On-chain systems parse with custom stack-only JSON parsers (no serde, no heap)

Links

• BOLT ECS docs
• Ephemeral Rollups docs
• MagicBlock
• Frontend README — detailed frontend architecture