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

Samples

Runnable example projects live in the repository's samples/ directory, ranging from focused single-feature demos (e.g. KeenEyes.Sample.Replay, KeenEyes.Sample.InputDebugger) to complete games. Highlight:

  • NOVAFALL (samples/KeenEyes.Sample.NovaFall) - the flagship 2D arcade sample, a reimagining of Fall Down. Its 26 systems exercise the 2D batch renderer (I2DRenderer), particles, animation, UI, spatial partitioning, and audio together. It exposes a TestBridge named pipe (KeenEyes.NovaFall.TestBridge) that can be registered in .mcp.json for MCP-driven inspection, and offers a headless deterministic simulation mode (--simulate <frames>, plus --seed and --mode) whose output is byte-identical for the same seed and mode - handy for CI.

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

  • Singletons - World-level resources
  • Serialization - Save and restore world state
  • Plugins - Modular extensions and feature packaging
  • Networking - Multiplayer replication, prediction, and interpolation
  • Logging - Pluggable logging system
  • AI System - Finite State Machines, Behavior Trees, and Utility AI

Testing & Tooling

  • Testing Guide - Unit testing with mocks
  • TestBridge Architecture - External tool integration, IPC protocol, command reference
  • MCP Server - AI tool integration via Model Context Protocol
  • Editor - The visual editor: panels, play mode, hot reload, and the plugin model
  • Editor Plugin Development - Reference for authoring editor plugins (lifecycle, capabilities, extension points)
  • CLI (keeneyes) - Manage editor plugins, package sources, and save-file migrations

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

  • Abstractions - Lightweight interfaces for plugin development
  • Animation - Skeletal playback, animator state machines, sprite animation, and tweening
  • Asset Management - Loading, caching, reference counting, and hot reload for game assets
  • Audio - ECS-driven sound playback, 3D spatial audio, and mixer channels (OpenAL)
  • Common - Shared utilities (float extensions, velocity components)
  • Debugging & Profiling - Profilers, memory/GC tracking, entity inspection, and timeline recording
  • Graphics - OpenGL/Vulkan rendering with Silk.NET
  • Input - Keyboard, mouse, and gamepad input handling
  • Localization - Multi-language text and locale-aware assets/fonts
  • Navigation & Pathfinding - Path following with pluggable Grid (A*) and DotRecast (navmesh) providers
  • Networking - Server-authoritative multiplayer with prediction
    • KeenEyes.Network - Core networking plugins and LocalTransport
    • KeenEyes.Network.Transport.Tcp - TCP transport (reliable ordered)
    • KeenEyes.Network.Transport.Udp - UDP transport (configurable reliability)
  • Node Graph Editor - Visual pan/zoom node-graph editor (canvases, nodes, ports, connections)
  • Particles - High-performance pooled particle effects
  • Persistence & Encryption - Save slots with optional AES-256 encryption over the snapshot system
  • Physics - BepuPhysics v2 integration (rigid bodies, colliders, collision events)
  • Replay Recording & Playback - Frame-by-frame recording for crash repro, killcams, demos, and ghosts
  • Shaders & KESL - The KESL shader language, its compiler pipeline, and GPU compute abstractions
  • Spatial - 3D transform components with System.Numerics
  • UI - ECS-based retained-mode UI system
  • UI Theming - OS-aware light/dark theming and automatic UIStyle application

Architecture Decisions

Key design decisions are documented as Architecture Decision Records:

Research

Technical research reports for planned features:

Editor & Tooling

Planned Systems

Foundation Research

Getting Help

API Reference

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

Edit this page