moikas-code/kenji-engine

Kenji - The TUI Engine

A Terminal User Interface (TUI) engine built with TypeScript/Bun, designed for creating games and terminal applications with AI-driven development through MCP (Model Context Protocol) integration.

Features

• 120 FPS: Fixed timestep with interpolation for smooth games and interactive applications
• Entity Component System (ECS): Flexible architecture for game objects and UI components
• Terminal Rendering: Double-buffered rendering with damage tracking for optimal performance
• Input System: Non-blocking keyboard input with configurable mappings
• TUI Components: Rich terminal interface components for forms, menus, and interactive elements
• MCP Integration: AI agents can create and modify games and applications through natural language

Quick Start

Prerequisites

• Bun (latest version)
• Terminal emulator with UTF-8 support

Installation

bun install

Using Kenji Engine

# Show the main menu
bun run kenji

# Create a new game or application project
bun run kenji create "My Amazing Game" --type=game
bun run kenji create "My Terminal App" --type=app

# Get help
bun run kenji --help

# Show version
bun run kenji --version

Testing the Engine

bun run test-engine.ts

Playing Pong

cd examples/pong
bun run index.ts

Controls:

• Player 1: W (up) / S (down)
• Player 2: I (up) / K (down)
• Q: Quit

Architecture

Core Systems

1. Core Engine (src/engine/core.ts)

   • Manages the main loop with fixed timestep for games and smooth UI interactions
   • Emits events for update, fixed update, and render cycles
   • Maintains stable 60 FPS for responsive games and applications

2. Renderer (src/engine/renderer.ts)

   • Double-buffered terminal rendering
   • Character-based sprites and UI elements with Unicode support
   • Damage tracking for optimal performance

3. ECS (src/ecs/world.ts)

   • Entities as numeric IDs for game objects and UI components
   • Components as plain data objects
   • Efficient entity queries and management

4. Input Manager (src/engine/input/inputManager.ts)

   • Non-blocking keyboard input
   • Key mapping system
   • Event-based input handling for games and TUI interactions

Game & Application Systems

• MovementSystem: Handles game object movement and animated UI transitions
• CollisionSystem: AABB collision detection for games and UI boundary management
• RenderSystem: Draws game entities and UI components to the terminal

Project Structure

kenji-engine/
├── packages/
│   ├── kenji/         # Core TUI engine
│   ├── tui/           # Rich TUI components and views
│   ├── cli/           # Command-line interface
│   └── mcp/           # MCP server integration
├── examples/
│   └── pong/          # Example game implementation
└── test/              # Test suites

Development Roadmap

Phase 1: Foundation ✅

• Core application loop implementation
• Terminal rendering system
• ECS architecture for UI components
• Basic input system

Phase 2: Game Example ✅

• Pong game as proof of concept
• Game entity management and physics
• Real-time rendering and player controls
• Performance optimization for smooth gameplay

Phase 3: CLI & Menu System ✅

• CLI command interface (kenji)
• Project creation and management
• Interactive menu system
• Configuration management
• ASCII branding and UI elements

Phase 4: Rich TUI Components (In Progress)

• OpenTUI integration foundation
• React-based TUI components
• Advanced form components
• Navigation and routing systems
• Data visualization components

Phase 5: MCP Integration (In Progress)

• MCP server setup
• Tool definitions for AI assistance
• Full AI-driven game and application development

Phase 6: More Examples

• Games: Breakout, Snake, Tetris, RPG systems
• Applications: File manager, code editor, database browser
• Tools: System monitoring dashboard, log viewer, task manager

TUI Architecture Notes

Kenji leverages OpenTUI and React for building rich terminal applications. The architecture supports:

• @opentui/core - Terminal rendering and component system
• @opentui/react - React integration for reactive TUI components
• Component-based architecture with JSX
• Event-driven interactions and state management
• Responsive terminal layouts and theming

What You Can Build

Games:

• Action games with physics and collision detection
• Puzzle games with interactive mechanics
• RPGs with turn-based or real-time combat
• Classic arcade games (Pong, Breakout, Snake, Tetris)

Applications:

• Interactive forms with validation and complex inputs
• Data dashboards with real-time visualization
• File managers and system navigation tools
• Development tools (code editors, database browsers)
• Monitoring dashboards and log viewers

"Kenji bridges the gap between game engines and application frameworks, offering the performance of native terminal interfaces with the creative freedom to build both entertaining games and powerful productivity tools."