Army Simulation Prototype

A WebGL-based army battle simulation built with Babylon.js and bitECS, designed to handle 10,000+ animated units at 60 FPS.

Tech Stack

• Babylon.js - 3D rendering with Thin Instances
• bitECS - High-performance Entity Component System
• Yuka - Steering behaviors and behavior trees
• RecastJS - Navigation mesh pathfinding
• Vite - Fast build tool with HMR
• TypeScript - Type safety

Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Project Structure

src/
├── main.ts                 # Entry point
├── core/                   # Application core
│   ├── App.ts              # Main orchestrator
│   ├── GameLoop.ts         # Fixed timestep game loop
│   └── Config.ts           # Configuration constants
│
├── renderer/               # Babylon.js rendering
│   ├── BattleScene.ts      # Scene, camera, lights
│   ├── UnitRenderer.ts     # Thin Instance rendering
│   ├── TerrainRenderer.ts  # Battlefield terrain
│   ├── EffectsRenderer.ts  # Particles, effects
│   └── shaders/            # Custom shaders
│
├── simulation/             # ECS game logic
│   ├── World.ts            # bitECS world
│   ├── components/         # ECS components
│   ├── systems/            # ECS systems
│   └── ai/                 # AI and formations
│
├── input/                  # Input handling
│   ├── InputManager.ts     # Mouse/keyboard
│   ├── CameraController.ts # RTS camera
│   └── SelectionManager.ts # Unit selection
│
├── ui/                     # User interface
│   ├── HUD.ts              # Performance display
│   ├── UnitPanel.ts        # Selection info
│   └── Minimap.ts          # Tactical overview
│
├── types/                  # TypeScript types
└── utils/                  # Utilities

Architecture

Entity Component System (ECS)

All game entities are managed through bitECS with these core components:

Component	Data
Transform	x, y, z, rotationY, scale
Velocity	x, y, z, maxSpeed
Unit	health, maxHealth, faction, type, state
Combat	attack, defense, range, attackSpeed, target
Animation	currentAnim, frame, speed
Navigation	targetX, targetZ, pathIndex, hasPath

System Pipeline

Systems run in this order each tick:

1. NavigationSystem - Pathfinding queries
2. SteeringSystem - Steering behaviors
3. FormationSystem - Formation offsets
4. MovementSystem - Apply velocity
5. CombatSystem - Damage resolution
6. AnimationSystem - State transitions

Rendering

Units are rendered using Babylon.js Thin Instances for maximum performance:

• Single draw call for thousands of units
• Transform matrices updated from ECS data
• VAT (Vertex Animation Textures) for GPU-driven animation

Controls

Input	Action
WASD / Arrows	Pan camera
Mouse wheel	Zoom
Left click	Select unit
Shift + click	Add to selection
Right click	Move selected units
Edge of screen	Edge pan (when enabled)

Performance Targets

• 60 FPS with 10,000 units
• 8ms simulation tick budget
• 8ms render budget

Future: Split-Brain Architecture

The codebase is structured to support WebWorker-based multithreading:

• Simulation runs on Worker thread
• Rendering stays on Main thread
• SharedArrayBuffer for zero-copy data sync

See docs/SPLIT-BRAIN-MIGRATION.md for the migration plan.

Development

Adding a New Component

1. Create src/simulation/components/MyComponent.ts
2. Export from src/simulation/components/index.ts
3. Add to relevant systems

Adding a New System

1. Create src/simulation/systems/MySystem.ts
2. Add to pipeline in src/simulation/systems/index.ts

Custom Shaders

Place GLSL files in public/assets/shaders/ and create corresponding TypeScript wrappers in src/renderer/shaders/.

License

MIT