ConsoleEngine

A .NET 8 framework for building terminal / CLI games with pixel-art sprites, Markdown-driven localisation, and player-editable content.

v0.1.0 .NET 8 MIT License 11 Languages ANSI Truecolor

⭐ View on GitHub Get Started →

HelloConsoleEngine — dotnet run

▄▄▄▄ ▄██████▄ ██▄██▄██ ████████ ██▀▀▀▀██ Welcome to ConsoleEngine! ████████ A terminal RPG framework for .NET 8. ▀██████▀ ConsoleEngine v0.1.0 ▀▀▀▀ Press Enter to exit. _

Architecture

Modular by design

Reference only what you need. Each module is a standalone .NET 8 class library with no game-specific dependencies.

ConsoleEngine.Core

Shared contracts: ILocalizationService, LocalizationTable, EngineVersion. No external dependencies.

ConsoleEngine.Locale

CL static façade, CK base keys, Markdown loader, in-memory service. 11 languages, hot-reload, graceful degradation.

ConsoleEngine.Rendering

PNG → ANSI half-block pixel art. Char-map sprites. AnimationEngine for frame-by-frame terminal animation.

ConsoleEngine.Config

Shared GameConfig — language, audio, display — consumed by both CLI runtime and Unity/Godot front-end.

ConsoleEngine.Persistence

Slot-based JSON save system and config repository. Generic SaveRepository<T> works with any serialisable model.

ConsoleEngine.Editor

Planned — Avalonia visual editor with drag-and-drop, visual scripting, embedded AI terminal, and hot-reload.

Getting Started

From zero to running game in 5 steps

1
Clone the repository

Clone ConsoleEngine and reference the projects from your game's .csproj.
```
git clone https://github.com/maxiusofmaximus/ConsoleEngine.git
```

Add project references

Reference the modules you need. A typical game uses all five:

<ItemGroup>
  <ProjectReference Include="path/to/ConsoleEngine.Core/..." />
  <ProjectReference Include="path/to/ConsoleEngine.Locale/..." />
  <ProjectReference Include="path/to/ConsoleEngine.Rendering/..." />
  <ProjectReference Include="path/to/ConsoleEngine.Config/..." />
  <ProjectReference Include="path/to/ConsoleEngine.Persistence/..." />
</ItemGroup>

Create your locale file

Drop a Markdown table at GameData/locale/en.md. No tools required.

# Locale: en

## Entries

| Key              | Value              |
|------------------|--------------------|
| menu.title       | My Terminal Game   |
| greeting         | Hello, {0}!        |

Initialise and render

Three lines to get a localised, pixel-art terminal game running:

PixelArtRenderer.EnableAnsi();          // enable truecolor on Windows
CL.Initialize("GameData", "en");        // load locale
Console.WriteLine(CL.Get("menu.title")); // → "My Terminal Game"

5
Run the sample

The HelloConsoleEngine sample shows localisation + pixel art in 40 lines of code:
```
cd samples/HelloConsoleEngine
dotnet run
```

Localisation

11 languages. No JSON. No build step.

Locale files are plain Markdown tables. They are diff-friendly, editable in any text editor, and read at runtime with no compilation required.

Missing keys fall back to English automatically. Hot-reload a language by calling CL.Initialize() again — no restart needed.

// Switch to Spanish at runtime — takes effect immediately
CL.Initialize("GameData", language: "es");
Console.WriteLine(CL.Get("menu.title")); // → "Mi Juego de Terminal"

Supported: en · ja · zh-Hans · es · pt · de · ru · it · fr · ca · ko

Rendering

Pixel art in your terminal

ConsoleEngine renders sprites using Unicode ▀ half-block characters and ANSI truecolor — no graphics library, no window, just the terminal.

// Render a PNG at column 10, row 5 — pixels with alpha < 128 are transparent
PixelArtRenderer.RenderPng("Sprites/hero.png", col: 10, row: 5);

// Or build a sprite from a char-map palette (no PNG file needed)
var palette = new Dictionary<char, PixelArtRenderer.Rgb>
{
    ['#'] = new(255, 200, 50),   // gold
    ['.'] = new(0, 0, 0),        // transparent
};
string[] map = { ".###.", "#####", ".###." };
var sprite = PixelArtRenderer.BuildSprite(map, palette, transparent: new(0,0,0));
PixelArtRenderer.RenderRgb(sprite, col: 10, row: 5);