Table of Contents

KeenEyes Documentation

Build and Test Coverage Status .NET License: MIT

Welcome to the KeenEyes ECS framework documentation.

What is KeenEyes?

KeenEyes is a high-performance Entity Component System (ECS) framework for .NET 10, reimplementing OrionECS in C#.

Quick Start

using KeenEyes.Core;

// Create a world
using var world = new World();

// Create an entity with components using the fluent builder
var entity = world.Spawn()
    .With(new Position { X = 10, Y = 20 })
    .With(new Velocity { X = 1, Y = 0 })
    .Build();

// Query and process entities
foreach (var e in world.Query<Position, Velocity>())
{
    ref var pos = ref world.Get<Position>(e);
    ref readonly var vel = ref world.Get<Velocity>(e);
    pos.X += vel.X;
    pos.Y += vel.Y;
}

Key Features

  • No Static State - All state is instance-based. Each World is completely isolated.
  • Components are Structs - Cache-friendly, value semantics for optimal performance.
  • Entities are IDs - Lightweight (int Id, int Version) tuples for staleness detection.
  • Fluent Queries - world.Query<A, B>().With<C>().Without<D>()
  • Source Generators - Reduce boilerplate while maintaining performance.
  • Parallel Execution - Automatic system batching and job system for multi-threaded processing.
  • Native AOT Compatible - No reflection in production code.

Documentation Sections

Learn

Section Description
Getting Started Build your first ECS application step-by-step
Core Concepts Understand ECS fundamentals: World, Entity, Component, System
Cookbook Practical recipes for common game patterns

Reference

Section Description
Features Complete guides for all KeenEyes features
Libraries Package documentation: Abstractions, Common, Spatial, Graphics
API Reference Auto-generated API documentation

Understand

Section Description
Design Philosophy Why KeenEyes is designed the way it is
Architecture Decisions Detailed ADRs explaining key decisions
Research Technical research for planned features

Help

Section Description
Troubleshooting Common issues and solutions

Cookbook Highlights

Jump straight to practical examples:

Recipe What You'll Learn
Basic Movement Position, velocity, acceleration, delta-time
Health & Damage Damage events, healing, death, invulnerability
State Machines AI states, transitions, behavior systems
Entity Pooling Reuse entities to avoid allocation
Physics Integration Sync ECS with physics engines
Input Handling Keyboard, mouse, gamepad, action mapping
Scene Management Load, unload, and transition between scenes

Design Philosophy

KeenEyes makes deliberate choices that differ from many game engines:

Modular Architecture

KeenEyes is designed as a fully-featured game engine that is also completely customizable. Rather than a monolithic framework, KeenEyes uses a layered architecture with clear abstraction boundaries.

┌─────────────────────────────────────────────────────────┐
│                    Your Game                            │
├─────────────────────────────────────────────────────────┤
│  KeenEyes.Graphics   │  KeenEyes.Audio   │  Physics     │
│  (Silk.NET OpenGL)   │  (OpenAL)         │  (Your Pick) │
├──────────────────────┴───────────────────┴──────────────┤
│              KeenEyes.Core (ECS Runtime)                │
├─────────────────────────────────────────────────────────┤
│           KeenEyes.Abstractions (Interfaces)            │
└─────────────────────────────────────────────────────────┘
Package Purpose
KeenEyes.Abstractions Core interfaces (IWorld, ISystem, IComponent) - no implementation dependencies
KeenEyes.Core Full ECS runtime with archetype storage, queries, and system execution
KeenEyes.Graphics OpenGL/Vulkan rendering via Silk.NET
KeenEyes.Audio Spatial audio via OpenAL
KeenEyes.Spatial Transform components and spatial partitioning

Swap Any Subsystem

Don't like our physics implementation? Use your own. Prefer FMOD over OpenAL? Swap it out:

// The default setup - everything works out of the box
using var world = new WorldBuilder()
    .WithPlugin<SilkGraphicsPlugin>()     // Built-in OpenGL rendering
    .WithPlugin<OpenALAudioPlugin>()      // Built-in audio
    .Build();

// Or bring your own implementations
using var world = new WorldBuilder()
    .WithPlugin<MyCustomRendererPlugin>()  // Your Vulkan renderer
    .WithPlugin<FmodAudioPlugin>()         // Third-party audio
    .WithPlugin<BulletPhysicsPlugin>()     // Your physics choice
    .Build();

Features Guide

Entity Features

Component Features

System Features

World Features

UI Features

  • UI System - Retained-mode UI with ECS entities
  • Widget Factory - Pre-built widgets (buttons, panels, sliders, etc.)
  • Anchor-based Layout - Responsive positioning system
  • Flexbox Containers - Automatic child arrangement

Libraries

Architecture Decisions

Key design decisions are documented as Architecture Decision Records:

Research

Technical research reports for planned features:

Planned Systems

Foundation Research

Getting Help

API Reference

See the API Documentation for detailed reference of all public types.

Edit this page