[v3.0.1] Babylon.js Port Implementation Plan

Module: Implementation / Babylon.js Port

Author: Cipherfall Dev Team

Created: 2026-05-01

Modified: 2026-05-01

Status: Implementation

Overview

This document outlines the full port of Cipherfall MMORPG from Godot 4 to Babylon.js + TypeScript.
The goal is to leverage Babylon.js's browser-based testing, TypeScript type safety, and smaller bundle size
while maintaining all existing game logic, Rustmoor asset integration, and item signing architecture.

Key Decisions

1. Babylon.js + TypeScript for all game logic and UI
2. Oimo.js for physics (built into Babylon.js)
3. A* Pathfinding for navigation (implement from scratch or use third-party library)
4. Rust WASM for ML-DSA-44/Kyber-512/BLAKE3 cryptography (port from Godot stub)
5. Protobuf for network serialization (already defined in game.proto)
6. FastAPI Backend for server-side item signing (port from Python stub)

Implementation Phases

Phase 1: Project Setup & Core ECS (2 days)

• [ ] Initialize TypeScript project with tsconfig.json
• [ ] Install Babylon.js + Oimo.js + Protobuf libraries
• [ ] Create project structure (src/, assets/, scripts/, etc.)
• [ ] Implement TypeScript ECS (Entity, Component, System)
• [ ] Implement A* pathfinding algorithm
• [ ] Implement collision detection (Oimo.js)
• [ ] Implement physics system (gravity, movement)
• [ ] Create base game scene (GameScene.ts)
• [ ] Test ECS + pathfinding + physics integration

Phase 2: Rustmoor Asset Pipeline (2 days)

• [ ] Create asset import pipeline (GLB loading)
• [ ] Import Kenney City Kit Industrial (Factory A/B, Chimney, Tank)
• [ ] Import Kenney Modular Dungeon Kit (Corridor, Room, Gate, Stairs)
• [ ] Import Kenney Blaster Kit (Crate, Training Dummy)
• [ ] Import Kenney City Kit Commercial (Building for Merchant Square)
• [ ] Import Kenney Furniture Kit (Benches, Tables, Lamps)
• [ ] Import Kenney Platformer Kit (Terrain for Outskirts)
• [ ] Import Kenney Modular Space Kit (Houses for Residential Area)
• [ ] Import Kenney Isometric Miniature Library (Boss placeholder)
• [ ] Import OpenGameArt characters (Warden, Sentinel, Reaver, Striker, Mender)
• [ ] Import OpenGameArt enemies (Drone, Spider-bot, Sentinel bot)
• [ ] Import OpenGameArt boss (Factory Overseer)
• [ ] Create Rustmoor PBR material system (9 materials)
• [ ] Apply Rustmoor PBR materials to all props
• [ ] Test asset import pipeline

Phase 3: Multibox System (3 days)

• [ ] Port multibox_group.gd → MultiboxGroup.ts
• [ ] Port multicast_intent.gd → MulticastIntent.ts
• [ ] Port navigation_server.gd → NavigationServer.ts
• [ ] Implement formation system (V/Line/Circle/Spread)
• [ ] Implement intent broadcast with role-aware suppression
• [ ] Implement state synchronization (positions, health, mana, cooldowns)
• [ ] Implement formation movement interpolation
• [ ] Test 5-character multibox spawn + formation positioning
• [ ] Test multibox group initialization
• [ ] Test formation switching during movement

Phase 4: Combat + Quest + Leveling (5 days)

• [ ] Port combat_engine.gd → CombatEngine.ts
• [ ] Port quest_engine.gd → QuestEngine.ts
• [ ] Port level_engine.gd → LevelEngine.ts
• [ ] Port equipment_engine.gd → EquipmentEngine.ts
• [ ] Port movement_engine.gd → MovementEngine.ts
• [ ] Implement combat rotation system (taunt, shield_bash, cleave, heroic_strike)
• [ ] Implement threat management (add_threat, get_threat_leader, get_threat_percentage)
• [ ] Implement target selection (quest → closest → weakest → highest_threat)
• [ ] Implement quest auto-accept/complete/turn-in
• [ ] Implement quest objective tracking (kill count, item collection, NPC interaction)
• [ ] Implement stat/skill point distribution (role-based allocation)
• [ ] Implement auto-equip better gear
• [ ] Implement auto-vendor below-threshold items
• [ ] Implement auto-repair below-threshold durability
• [ ] Implement auto-path to quest targets
• [ ] Implement formation maintenance during movement
• [ ] Implement obstacle avoidance (world static only)
• [ ] Test combat automation (5-char vs 3 drones)
• [ ] Test quest automation (auto-accept/complete/turn-in chain)
• [ ] Test leveling automation (stat/skill distribution)
• [ ] Test equipment automation (gear optimization)
• [ ] Test movement automation (auto-path + formation)

Phase 5: UI + Damage Meter (3 days)

• [ ] Port damage_meter.gd → DamageMeter.ts
• [ ] Port group_hud.gd → GroupHUD.ts
• [ ] Port intent_panel.gd → IntentPanel.ts
• [ ] Port auction_house.gd → AuctionHouse.ts
• [ ] Implement damage meter (DPS/HPS/threat/spell breakdown)
• [ ] Implement group HUD (5-character portraits, health/mana bars)
• [ ] Implement intent panel (broadcast toggles, action queue)
• [ ] Implement auction house UI (item listing, detail, buy/sell, drop rate audit, key rotation)
• [ ] Implement Babylon.js GUI (AdvancedDynamicTexture)
• [ ] Implement custom canvas for damage visuals
• [ ] Implement spell effect canvas
• [ ] Test damage meter output during combat
• [ ] Test group HUD updates during combat
• [ ] Test intent panel broadcast toggles
• [ ] Test auction house UI transactions

Phase 6: Rustmoor Sections 001-005 (7 days)

• [ ] Build Rustmoor Section 001 (Entry Plaza) in Babylon.js
• [ ] Place Factory A/B (City Kit Industrial)
• [ ] Place Chimney (City Kit Industrial)
• [ ] Place Tank (City Kit Industrial)
• [ ] Place Corridor (Modular Dungeon Kit)
• [ ] Place Room (hangar) (Modular Dungeon Kit)
• [ ] Place Crate (Blaster Kit)
• [ ] Place Awning (City Kit Commercial)
• [ ] Place Training Dummy (Blaster Kit)
• [ ] Place Quest NPC (OpenGameArt)
• [ ] Configure 5 spawn markers (Master + 4 slaves)
• [ ] Configure collision layers (Layer 1: world static)
• [ ] Configure NavigationRegion3D equivalent
• [ ] Add DirectionalLight (neon surveillance #06B6D4)
• [ ] Add ambient lighting (ashen gray #2D2D2D sky)
• [ ] Add fog (industrial smog #6B7280)
• [ ] Test multibox spawn + formation positioning
• [ ] Test combat_engine.gd against training dummies
• [ ] Test damage_meter.gd output
• [ ] Build Rustmoor Section 002 (Training Grounds) in Babylon.js
• [ ] Place Gate (Modular Dungeon Kit)
• [ ] Place Stairs (Modular Dungeon Kit)
• [ ] Place Ground Plane (Modular Dungeon Kit)
• [ ] Place 3 Training Dummies (Blaster Kit)
• [ ] Place Quest NPC (OpenGameArt)
• [ ] Configure navigation link to Section 001
• [ ] Add warm torchlight (#FFA500)
• [ ] Add light mist fog (#D3D3D3)
• [ ] Test navigation between sections
• [ ] Test combat against training dummies
• [ ] Build Rustmoor Section 003 (Merchant Square) in Babylon.js
• [ ] Place 4 Buildings (City Kit Commercial)
• [ ] Place 3 Vendor NPCs (OpenGameArt)
• [ ] Place Auction House placeholder (City Kit Commercial)
• [ ] Place Benches (Furniture Kit)
• [ ] Place Tables (Furniture Kit)
• [ ] Place Crates (Blaster Kit)
• [ ] Configure navigation link to Section 002
• [ ] Add warm torchlight (#FFA500)
• [ ] Add light mist fog (#D3D3D3)
• [ ] Test auction house UI with item listing
• [ ] Build Rustmoor Section 004 (Residential Area) in Babylon.js
• [ ] Place 6 Houses (Modular Space Kit adapted)
• [ ] Place 3 Gathering Points (Furniture Kit)
• [ ] Place 3 Benches (Furniture Kit)
• [ ] Place 3 Lamps (Furniture Kit)
• [ ] Configure navigation link to Section 003
• [ ] Add warm torchlight (#FFA500)
• [ ] Add light mist fog (#D3D3D3)
• [ ] Test navigation between sections
• [ ] Build Rustmoor Section 005 (Outskirts) in Babylon.js
• [ ] Place Terrain Variation (Platformer Kit adapted)
• [ ] Place 5 Wild Mobs (Sci-Fi Pack adapted)
• [ ] Place Boss Placeholder (Isometric Miniature Library adapted)
• [ ] Configure navigation link to Section 004
• [ ] Add warm torchlight (#FFA500)
• [ ] Add light mist fog (#D3D3D3)
• [ ] Test combat against wild mobs
• [ ] Test boss encounter

Phase 7: Item Signing + Verification (3 days)

• [ ] Port crypto_bridge.gd → CryptoBridge.ts
• [ ] Port item_signer.gd → ItemSigner.ts
• [ ] Port item_verifier.gd → ItemVerifier.ts
• [ ] Implement ML-DSA-44 signing (stub for skeleton)
• [ ] Implement BLAKE3 hashing (stub for skeleton)
• [ ] Implement Merkle tree construction
• [ ] Implement item signature verification
• [ ] Implement Merkle proof verification
• [ ] Implement drop rate hash verification
• [ ] Update local_anchor.json with real Merkle root
• [ ] Test item signing locally
• [ ] Test item verification against anchor
• [ ] Test drop rate audit verification
• [ ] Wire auction house UI to item signing
• [ ] Test full transaction flow in auction house

Phase 8: Full Automation Testing (3 days)

• [ ] Implement combat automation test
• [ ] Test 5-char multibox group auto-attacks 3 drones
• [ ] Verify rotation execution (taunt, shield_bash, cleave, heroic_strike)
• [ ] Verify threat management (tank maintains aggro)
• [ ] Verify target selection (quest → closest → weakest → highest_threat)
• [ ] Verify damage meter output during combat
• [ ] Implement quest automation test
• [ ] Test auto-accept quest from Quest NPC
• [ ] Test auto-complete quest objectives
• [ ] Test auto-turn-in quest to Quest NPC
• [ ] Test quest chaining through Sections 001-002
• [ ] Verify objective tracking (kill count, item collection, NPC interaction)
• [ ] Implement leveling automation test
• [ ] Test stat point distribution on level up
• [ ] Test skill point distribution on level up
• [ ] Verify role-based stat allocation (tank: health/armor/strength, dps: strength/intellect/crit)
• [ ] Test auto-equip better gear
• [ ] Test auto-vendor below-threshold items
• [ ] Implement equipment automation test
• [ ] Test gear optimization (best gear equipped)
• [ ] Test auto-vendor below-threshold items
• [ ] Test auto-repair below-threshold durability
• [ ] Verify stat weighting per role
• [ ] Implement movement automation test
• [ ] Test auto-path to quest targets
• [ ] Test formation maintenance during movement
• [ ] Test obstacle avoidance (world static only)
• [ ] Verify waypoint tolerance and arrival detection
• [ ] Test full automation through Rustmoor 001-005
• [ ] Test 5-char multibox auto-completes all Rustmoor quests
• [ ] Test stats distributed correctly on level up
• [ ] Test gear optimized automatically
• [ ] Test formation maintained during combat
• [ ] Test intent broadcast and suppression working correctly

Phase 9: Polish & Optimization (2 days)

• [ ] Implement frustum culling for off-screen entities
• [ ] Implement LOD system (4 levels: high/medium/low/billboard)
• [ ] Implement memory management (object pooling)
• [ ] Optimize network bandwidth (delta compression, Protobuf)
• [ ] Test with 10k, 50k, and 100k entities
• [ ] Verify performance targets (100ms network, 20ms crypto, 60 FPS)
• [ ] Polish UI visuals (damage meter, group HUD, intent panel)
• [ ] Polish Rustmoor lighting and atmosphere
• [ ] Test WebGL export compatibility

Phase 10: Deployment & CI/CD (1 day)

• [ ] Set up GitHub Actions for automated testing
• [ ] Configure WebGL export pipeline
• [ ] Test on multiple browsers (Chrome, Firefox, Safari, Edge)
• [ ] Test on multiple devices (desktop, tablet, mobile)
• [ ] Optimize bundle size (aim for <10MB)
• [ ] Deploy to production server
• [ ] Monitor performance and fix issues

Estimated Timeline

Key Technical Decisions

1. Pathfinding

• Option A: Implement A* from scratch (more control, more work)
• Option B: Use third-party library like pathfinding.js (faster, less control)
• Recommendation: Start with Option A for full control, switch to B if needed

2. Physics

• Option A: Use Oimo.js (built into Babylon.js, easy integration)
• Option B: Implement custom physics (more control, much more work)
• Recommendation: Use Oimo.js (already built-in, well-tested)

3. ECS Architecture

• Option A: TypeScript ECS (clean, type-safe, more work)
• Option B: Godot-style dictionary-based ECS (faster, less type-safe)
• Recommendation: TypeScript ECS (aligns with Babylon.js approach)

4. Item Signing

• Option A: Rust WASM (real ML-DSA-44, requires native build)
• Option B: JavaScript stub (skeleton, deterministic hash)
• Recommendation: Start with B for skeleton, migrate to A for production

5. Networking

• Option A: Protobuf (binary, efficient, more work)
• Option B: JSON (text, simpler, larger payloads)
• Recommendation: Protobuf for production, JSON for skeleton

Files to Create/Port

Core Systems (TypeScript)

• src/ecs/Entity.ts - Entity class
• src/ecs/Component.ts - Component base class
• src/ecs/System.ts - System base class
• src/ecs/ECSManager.ts - ECS Manager
• src/pathfinding/AStar.ts - A* pathfinding algorithm
• src/pathfinding/NavMesh.ts - NavMesh class
• src/physics/PhysicsManager.ts - Physics manager
• src/collision/CollisionManager.ts - Collision detection
• src/crypto/CryptoBridge.ts - Crypto bridge (WASM)
• src/crypto/ItemSigner.ts - Item signer
• src/crypto/ItemVerifier.ts - Item verifier
• src/crypto/MLDSA44.ts - ML-DSA-44 stub
• src/crypto/BLAKE3.ts - BLAKE3 stub
• src/crypto/Kyber512.ts - Kyber-512 stub

Game Systems (TypeScript)

• src/game/MultiboxGroup.ts - Multibox group controller
• src/game/MulticastIntent.ts - Intent broadcast system
• src/game/NavigationServer.ts - Navigation wrapper
• src/game/CombatEngine.ts - Combat automation
• src/game/QuestEngine.ts - Quest automation
• src/game/LevelEngine.ts - Leveling automation
• src/game/EquipmentEngine.ts - Equipment automation
• src/game/MovementEngine.ts - Movement automation
• src/game/ProfileManager.ts - Profile management
• src/game/AssetLoader.ts - Asset loading
• src/game/LODManager.ts - LOD system

UI Components (TypeScript)

• src/ui/DamageMeter.ts - Damage meter
• src/ui/GroupHUD.ts - Group HUD
• src/ui/IntentPanel.ts - Intent panel
• src/ui/AuctionHouse.ts - Auction house UI
• src/ui/InventoryUI.ts - Inventory UI
• src/ui/ChatUI.ts - Chat UI
• src/ui/MainMenu.ts - Main menu

Game Scenes (TypeScript)

• src/game/GameScene.ts - Main game scene
• src/game/SceneManager.ts - Scene manager
• src/game/CameraSystem.ts - Camera system
• src/game/LightingManager.ts - Lighting manager
• src/game/PhysicsManager.ts - Physics manager
• src/network/NetworkManager.ts - Network manager
• src/network/DeltaCompression.ts - Delta compression

Rustmoor Sections (TypeScript)

• src/sections/Section001_EntryPlaza.ts - Rustmoor Section 001
• src/sections/Section002_TrainingGrounds.ts - Rustmoor Section 002
• src/sections/Section003_MerchantSquare.ts - Rustmoor Section 003
• src/sections/Section004_ResidentialArea.ts - Rustmoor Section 004
• src/sections/Section005_Outskirts.ts - Rustmoor Section 005

Protobuf (TypeScript)

• src/protobuf/game_pb.ts - Protobuf TypeScript bindings (already exists)
• src/protobuf/game.proto - Protobuf schema (already exists)

Tests (TypeScript)

• src/tests/multibox_spawn_test.ts - Multibox spawn test
• src/tests/combat_engine_test.ts - Combat engine test
• src/tests/quest_engine_test.ts - Quest engine test
• src/tests/level_engine_test.ts - Level engine test
• src/tests/equipment_engine_test.ts - Equipment engine test
• src/tests/movement_engine_test.ts - Movement engine test
• src/tests/full_automation_test.ts - Full automation test

Migration Strategy

Step 1: Core Systems

• Implement TypeScript ECS
• Implement A* pathfinding
• Implement Oimo.js physics
• Implement collision detection

Step 2: Multibox System

• Port multibox_group.gd → MultiboxGroup.ts
• Port multicast_intent.gd → MulticastIntent.ts
• Port navigation_server.gd → NavigationServer.ts
• Test formation positioning

Step 3: Combat/Quest/Leveling

• Port combat_engine.gd → CombatEngine.ts
• Port quest_engine.gd → QuestEngine.ts
• Port level_engine.gd → LevelEngine.ts
• Port equipment_engine.gd → EquipmentEngine.ts
• Port movement_engine.gd → MovementEngine.ts
• Test automation

Step 4: UI/Damage Meter

• Port damage_meter.gd → DamageMeter.ts
• Port group_hud.gd → GroupHUD.ts
• Port intent_panel.gd → IntentPanel.ts
• Port auction_house.gd → AuctionHouse.ts
• Test UI

Step 5: Rustmoor Sections

• Import Kenney GLB assets
• Apply Rustmoor PBR materials
• Build Section 001 (Entry Plaza)
• Build Section 002 (Training Grounds)
• Build Section 003 (Merchant Square)
• Build Section 004 (Residential Area)
• Build Section 005 (Outskirts)
• Test navigation between sections

Step 6: Item Signing

• Port crypto_bridge.gd → CryptoBridge.ts
• Port item_signer.gd → ItemSigner.ts
• Port item_verifier.gd → ItemVerifier.ts
• Test item signing/verification

Step 7: Full Automation Testing

• Test combat automation
• Test quest automation
• Test leveling automation
• Test equipment automation
• Test movement automation
• Test full automation through Rustmoor 001-005

Step 8: Polish/Optimization

• Implement frustum culling
• Implement LOD system
• Implement memory management
• Optimize network bandwidth
• Polish UI visuals
• Polish Rustmoor lighting

Step 9: Deployment

• Set up CI/CD
• Test WebGL export
• Deploy to production

Notes

• All Rustmoor assets are already downloaded (631 Kenney GLB + 140 OpenGameArt)
• All Rustmoor PBR materials are already defined (9 materials)
• All item sheets are already defined (15 items + drop rates)
• All documentation is already written (20+ files)
• All cryptography stubs are already implemented (ML-DSA-44, BLAKE3, Kyber-512)
• All auction house UI is already designed (5 panels)
• All automation tests are already designed (5 scenarios)

This port is about re-implementing existing logic in TypeScript/Babylon.js, not re-designing.

[v3.0.1] Babylon.js Port Implementation Plan - End of Document