Better ECS Game Engine

A client-first ECS-based game engine using TypeScript, Vite, and Nx monorepo.

Architecture

This project follows a strict Entity-Component-System architecture:

• Entities: Opaque IDs only (using type-fest tagged types)
• Components: Pure data, no logic
• Systems: Operate over component sets, no direct system-to-system calls
• Feature-oriented structure: Not "components vs systems"
• Client-first: Browser-based runtime with Vite
• Multiplayer-ready: Networking layer to be added later
• Schema-first serialization: Supports JSON (authoring) and binary (runtime)

Project Structure

/better-ecs
/apps
/client # Browser game (Vite)
/server # Placeholder for future backend
/packages
/engine # ECS, math, serialization, runtime
/shared # Shared utilities/types
nx.json
package.json
tsconfig.base.json

Engine Package Structure

/packages/engine/src
/ecs
entity.ts # Entity type & factory
world.ts # World container
storage.ts # Component storage
/math
index.ts # Math utilities (to be implemented)
/serialization
schema.ts # Component schema interface
json.ts # JSON serialization (to be implemented)
binary.ts # Binary serialization (to be implemented)
index.ts
/core
game.ts # Game initialization
time.ts # Time management (to be implemented)
index.ts

Setup

Install dependencies:

npm install

Development

Run the client:

npm run dev

Or run specific app:

npx nx dev client

Design Principles

1. Entities are IDs only - No classes, no methods
2. Components are pure data - No behavior, no cross-references
3. Systems do not call each other - Communication via shared data
4. Serialization is schema-driven - Not raw JS objects
5. Rendering is policy-driven - Draw order is a rendering decision
6. Multiplayer is layered later - Architecture stays clean
7. Structure precedes implementation - This is bootstrap phase only

Current Status: Bootstrap Phase

This is structure only. The following are NOT implemented yet:

• ❌ Rendering systems
• ❌ Gameplay systems
• ❌ Components (Transform, Renderable, etc.)
• ❌ Serialization logic
• ❌ Networking
• ❌ Editors
• ❌ Game loop logic

Next Steps

After bootstrap:

1. Implement core game loop
2. Add basic component types (Transform, etc.)
3. Create render system
4. Add serialization implementation
5. Build gameplay systems
6. Add networking layer