Aster Learning Engine

Aster Learning Engine is an educational C++20 game engine by Faruk Alpay. The core engine, native renderer, platform adapters, networking, profiling, sample game, editor UI, generated media, and tests live in one inspectable source tree.

Aster v1 keeps reusable code in include/aster and src, keeps executable code thin, and limits outside boundaries to standard C++ plus direct operating-system APIs inside isolated platform files.

Captures

The images below are generated from the current build.

What Is Included

• A macOS native Metal renderer with depth, translucent sorting, procedural material shading, contact shadows, fog, tonemapping, frame pacing, and UI composition.
• A deterministic software renderer used for fallback, capture, preview, and renderer diagnostics.
• Lumen Run, a playable sample that exercises terrain, castle geometry, cave traversal, mineral formations, water, vegetation, avatar animation, inventory, HUD, interaction, physics, particles, and capture automation.
• Engine-owned math, mesh preparation, brush level mesh generation, procedural noise, scene import, scenery assembly, TCP loopback transport, and lightweight CPU profiling.
• Native platform adapters behind aster::Window; product code consumes only window size and input snapshots.

Repository Layout

Path	Purpose
apps/	Thin executables for Lumen Run, Studio, preview, and network probe
include/aster/	Public engine headers
src/	Engine, renderer, platform, game, UI, asset, geometry, net, and core code
tests/	Unit, regression, and structure tests
assets/	Generated screenshots and README media
docs/	Architecture and research notes

Build

Prerequisites:

• CMake 3.24+
• A C++20 compiler
• macOS with Cocoa and Metal, or Linux with a local X server

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failure

Run the game:

./build/aster_lumen_run

The desktop executables default to frame-paced interactive presentation. Pass --unlocked only when measuring raw throughput or debugging the render loop.

Run the studio:

./build/aster_studio

Run smoke checks:

./build/aster_lumen_run --smoke-test
./build/aster_studio --smoke-test
./build/aster_net_probe

Check frame timing:

./build/aster_lumen_run --frame-report --frame-report-warmup 30 --run-frames 240 --lag-budget-ms 16.7 --window-width 1280 --window-height 720 --msaa 0

Set ASTER_FORCE_SOFTWARE_RENDERER=1 to run the deterministic software fallback on macOS.

Refresh Screenshots

mkdir -p assets/screenshots /tmp/aster_learning_shots
find /tmp/aster_learning_shots -type f \( -name '*.ppm' -o -name '*.png' \) -delete

./build/aster_lumen_run --screenshot /tmp/aster_learning_shots/lumen_run.ppm --screenshot-frame 8 --capture-hud --msaa 0 --window-width 1280 --window-height 720
./build/aster_lumen_run --screenshot /tmp/aster_learning_shots/lumen_cave.ppm --screenshot-frame 8 --msaa 0 --window-width 1280 --window-height 720 --camera-target-x 31.0 --camera-target-y 6.3 --camera-target-z -59.0 --camera-yaw-deg 0 --camera-pitch-deg 31 --camera-radius 16.2 --camera-fov-deg 31
./build/aster_lumen_run --screenshot /tmp/aster_learning_shots/lumen_cave_interior.ppm --screenshot-frame 8 --msaa 0 --window-width 1280 --window-height 720 --camera-target-x 31.2 --camera-target-y 2.65 --camera-target-z -85.0 --camera-yaw-deg 2 --camera-pitch-deg 7 --camera-radius 5.6 --camera-fov-deg 50
./build/aster_lumen_run --screenshot /tmp/aster_learning_shots/lumen_inventory.ppm --screenshot-frame 2 --open-inventory --capture-hud --msaa 0 --window-width 1280 --window-height 720
./build/aster_studio --screenshot /tmp/aster_learning_shots/studio.ppm --window-width 1280 --window-height 720
./build/aster_preview --output /tmp/aster_learning_shots/preview.ppm --width 960 --height 540

sips -s format png /tmp/aster_learning_shots/lumen_run.ppm --out assets/screenshots/lumen_run.png
sips -s format png /tmp/aster_learning_shots/lumen_cave.ppm --out assets/screenshots/lumen_cave.png
sips -s format png /tmp/aster_learning_shots/lumen_cave_interior.ppm --out assets/screenshots/lumen_cave_interior.png
sips -s format png /tmp/aster_learning_shots/lumen_inventory.ppm --out assets/screenshots/lumen_inventory.png
sips -s format png /tmp/aster_learning_shots/studio.ppm --out assets/screenshots/learning_studio.png
sips -s format png /tmp/aster_learning_shots/preview.ppm --out assets/screenshots/aster_preview.png

On non-macOS hosts, use an equivalent PPM-to-PNG encoder for the media refresh commands.

Platform Targets

Aster v1 targets macOS and Linux.

• macOS uses a native Cocoa adapter for windows, events, cursor state, and Metal presentation.
• Linux uses a raw X11 protocol adapter implemented over POSIX sockets; no desktop client library is linked.
• Windows and Wayland are not v1 targets.

Authorship

Engine-owned source files include:

Author: Faruk Alpay
Do not remove this notice.

License

Original Aster Learning Engine code and assets are available for educational, non-commercial, and nonprofit use with attribution. See LICENSE.