README

Apus Game Engine

Cross-platform 2D/3D game engine written in Delphi/Pascal by Ivan Polyacov (Apus Software). In active development since the early 2000s, used in several commercial titles.

Engine 5 targets Windows, Linux and macOS (up from Windows and Linux in Engine 4). Android and iOS builds run in emulators/simulators and are available to try out, but they are in preview state and not production-ready yet.

Games made with this engine:

• Astral Masters — Windows, iOS (Engine-2)
• Spectromancer — Windows, iOS (Engine-2.5 (late))
• Astral Towers — Windows, Linux, iOS (Engine-3 / 4)
• Astral Heroes — Windows (Engine-3)

🚀 Getting started

Requirements: FPC 3.2.2+ or Delphi 12+. No other setup is needed: the engine is used from source.

Build a demo with FPC - from the repository root:

build.cmd SimpleDemo          (Windows: the exe goes to bin64\, next to the DLLs it needs)
bin64\SimpleDemo.exe

./build.sh SimpleDemo         (Linux: the exe goes next to the .dpr)
demo/SimpleDemo/SimpleDemo

On Linux install libsdl2-dev libfreetype-dev first (plus libsdl2-mixer-dev for audio). The compiler options live in one place, build.cfg, shared by both scripts and CI; a project can add its own in <project>/build.cfg. The scripts are internal tools for the engine's own programs (demos, tests, tools); a project outside the repository builds with its own script around build.cfg (see demo/ProjectTemplate). Extra options can be passed after the name, e.g. ./build.sh SimpleDemo -dDEBUG.

With Delphi, open demo\SimpleDemo\SimpleDemo.dproj; with Lazarus, the .lpi next to it.

macOS - ./build.sh works as on Linux (SDL2 and FreeType from Homebrew); for a proper .app see platform/ and platform/BUILDING_BUNDLES.md.

Your own project: copy demo/ProjectTemplate - its README has the steps. Other demos are listed in demo/demo_inventory.md.

Opt-in defines (see defines.inc), passed as -d<NAME>: SDLMIX - audio via SDL_mixer; WEBP - .webp image loading; SDL - SDL platform layer on Windows (Linux and macOS always use it).

💡 Philosophy

The engine is written in standard Object Pascal and compiles with both Delphi 12+ and FPC 3.2+ from a single codebase, with no conditional forks for compiler-specific syntax. This is a deliberate design constraint: language features that work in one compiler but not the other are avoided. The goal is long-term portability — the same source should remain buildable regardless of which Pascal toolchain you use or what platform you target.

This means: no inline variables, no type inference, no attributes, no anonymous methods beyond what both compilers support. Compatibility is not a limitation to work around — it is part of the design.

📦 What's included

Base library (Base/Apus.*.pas) — platform-independent utilities that can be used without the engine:

• Math: vectors, matrices, quaternions, geometry (2D/3D), spatial primitives
• Strings: UTF-8 (String8) as the primary string type, with full helper API
• Collections: hash maps, arrays, containers, sorted structures
• Animation: tweening, animated values
• I/O: file handling, compression, image loading/saving, cryptography
• Network: TCP, HTTP requests
• Platform: threading, logging, profiling, clipboard, cross-platform time

Engine (Apus.Engine.*.pas) — the game engine itself:

• Scene system with defined lifecycle (Load → Init → Process → Render)
• UI system: widgets, layout, CSS-like style system, event signals
• OpenGL renderer (GL 3.3 core baseline, GLES 3.0 for mobile targets; newer GL features only as optional extension-gated fast paths): 2D/3D drawing, shaders, textures, nine-patch, text
• Resource management with reference counting
• Audio: SDL_mixer backend (opt-in, -dSDLMIX)
• Platform layer: Windows, Linux, macOS; Android and iOS in preview
• Multi-window and DPI-aware display support

✅ Engine 4 — stable

The current stable version is engine4. It is used in shipped games and is the recommended starting point if you want something that works today.

→ Download engine4 releases
→ Documentation / Tutorial

🚧 Engine 5 — in development

engine5 is a major refactoring of the entire codebase. APIs may still change. Preview snapshots are published as pre-releases; coming from engine4, see the migration guides engine_changes.md (engine) and Base/engine5_changes.md (Base library).

What's being worked on is tracked in engine5_feature_roadmap.md. Current highlights:

• New foundation library (Apus.Core, Apus.Strings, Apus.Conv, Apus.Log, Apus.Threads, …) replacing the monolithic legacy Apus.Common
• OpenGL core profile pipeline with a GL 3.3 desktop baseline and a shared GLES 3.0 mobile path
• CSS-like style system for UI (declarative, inherited, state-aware)
• Geometry library overhaul: single-precision first, spatial primitives, intersection and culling tests
• Multi-window support with runtime DPI changes
• Robot API for automated testing and tooling integration (file-based protocol, UI introspection, screenshot/pixel commands)
• CI coverage on Windows, Linux and macOS arm64 (GitHub Actions)
• Modernized demo suite, including the touch-oriented TouchDemo used for mobile bring-up

Build notes and platform-specific tooling live under platform/. The engine5 manual is being written - see manual/README.md for the published chapters; detailed implementation status is in the feature roadmap.

Known limitations

• Skeletal 3D models (Model3D, IQM/AEM loaders) are not migrated yet - see legacy/. Static meshes and OBJ work.
• Some old demos do not build yet - they are kept in demo/legacy/.
• The WebP decoder is not bundled for macOS and iOS.
• UI widget colors are only partly themeable (the style system is in progress).

License: BSD-3 — see license.txt; third-party components and their notices are indexed in THIRD-PARTY.md
VK group: https://vk.com/apusgameengine