KioECS
Lightweight ECS Game Framework
A lightweight, type-safe Entity Component System (ECS) framework built with TypeScript for web-based game development. Features pure ECS architecture, built-in systems, and developer-friendly API.
Tech Stack
🎮 Overview
A lightweight, type-safe Entity Component System (ECS) framework built with TypeScript for web-based game development. KioECS follows a pure ECS architecture with clean separation of Entities, Components, and Systems, providing a performant and developer-friendly foundation for building browser games.
✨ Core Features
🚀 Pure ECS Architecture
Clean separation of Entities, Components, and Systems following industry-standard ECS patterns
🔒 Type-Safe
Full TypeScript support with autocomplete for Components and compile-time type checking
⚡ Performant
Efficient component storage and query system optimized for browser performance
🎯 Engine/Game Separation
Reusable engine framework with game-specific logic clearly separated
🧩 Built-in Engine Systems
🏗️ Architecture
KioECS follows a clean Engine/Game separation pattern, making the framework reusable across different game projects:
Engine Layer (Reusable)
- • ECS Core - Entity/Component/System management
- • Generic Systems - Input, Movement, Rendering, Collision
- • Resources - InputResource, RenderResource
- • Can be used for any game!
Game Layer (Game-Specific)
- • GameSetup - Initializes your specific game
- • Custom Systems - EnemyAISystem, etc.
- • Entity Creation - Player, Enemies, Items
- • Your game logic lives here!
📚 Quick Start
Creating Entities
// Create a player entity
const player = ecs.createEntity();
ecs.addComponent(player, "Position", { x: 100, y: 100 });
ecs.addComponent(player, "Health", { current: 100, max: 100 });
ecs.addComponent(player, "PlayerControlled", {});
// Create an enemy entity
const enemy = ecs.createEntity();
ecs.addComponent(enemy, "Position", { x: 200, y: 200 });
ecs.addComponent(enemy, "Health", { current: 50, max: 50 });
ecs.addComponent(enemy, "Velocity", { dx: 10, dy: 0 });Querying Entities
// Get all entities with Health
const livingEntities = ecs.query("Health");
// Get all entities with Position AND Velocity
const movingEntities = ecs.query("Position", "Velocity");
// Get all player-controlled entities
const players = ecs.query("PlayerControlled");Creating Custom Systems
export class MovementSystem extends System {
update(ecs: ECS, deltaTime: number): void {
// Query all entities that have both Position and Velocity
const entities = ecs.query("Position", "Velocity");
for (const entity of entities) {
const pos = ecs.getComponent(entity, "Position")!;
const vel = ecs.getComponent(entity, "Velocity")!;
// Update position based on velocity
pos.x += vel.dx * deltaTime;
pos.y += vel.dy * deltaTime;
}
}
}🎯 Demo Game
The included demo showcases the framework's capabilities:
- •Player Movement - WASD/Arrow keys (200 px/s)
- •Shooting System - Space to shoot projectiles towards mouse cursor
- •Particle Effects - Projectile trails, muzzle flash, and impact particles
- •Sound Effects - Synthesized audio for shooting, hits, and damage (no files!)
- •Enemy AI - 5 enemies that chase player within 300px range
- •Collision System - AABB collision with damage cooldown (1s)
- •Projectile Combat - Projectiles deal 25 damage to enemies on contact
- •Health System - Health regeneration and entity destruction on death
- •Debug Overlay - FPS, velocity, position, and entity count
Controls: WASD/Arrows to move • Space to shoot • Mouse to aim
🔊 Synthesized Audio System
KioECS features a unique Web Audio API integration with procedurally generated sound effects - no audio files needed!
Why Synthesized Audio?
- ✅ No Asset Loading - Instant, no HTTP requests
- ✅ Tiny Bundle Size - Few lines of code vs KB/MB files
- ✅ Customizable - Adjust frequency, duration, envelope in code
- ✅ Retro Aesthetic - Classic arcade/chiptune vibes
- ✅ No Copyright Issues - 100% procedural generation
Built-in Sounds
shoot - Laser pew sound (frequency sweep)hit - Impact sound (noise + tone)hurt - Damage taken (descending tone with vibrato)🔧 Developer Experience
📦 Installation
# Clone the repository
git clone https://github.com/KibaOfficial/KioECS.git
cd KioECS
# Install dependencies
npm install
# Start development server
npm run dev
# Build for production
npm run build