Zanna

Zanna is a from-scratch, IL-first compiler toolchain and virtual machine for building platform-native applications and games. Source languages lower to a typed intermediate language, Zanna IL, which can run on the VM, feed the optimizer, or compile to native code through the built-in backends.

Zia is the flagship language: a modern, statically typed language with classes, generics, enums, lambdas, modules, pattern matching, and direct access to the Zanna runtime. A BASIC frontend is included for education, compatibility experiments, and quick prototypes.

Status: Pre-alpha, active development. The current source tree is v0.2.99; the IL reference is 0.3.0. APIs, diagnostics, IL rules, and tooling are still evolving.

Latest tagged release: v0.2.7-dev (2026-06-30)

• Source (tar.gz)
• Source (zip)
• Release notes

In development: v0.2.99 on master. See the draft v0.2.99 release notes.

git clone https://github.com/zannagames/zanna.git
cd zanna

Build, test, and install the toolchain with the platform scripts:

# macOS
./scripts/build_zanna_mac.sh

# Linux
./scripts/build_zanna_linux.sh

# Windows
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build_zanna_win.ps1

Verify the build:

zanna --version

Create and run a project:

zanna init my-app              # Zia project (default)
zanna init my-app --lang basic # BASIC project
zanna run my-app

Try the REPL:

zanna repl

zia> 2 + 3 * 4
14
zia> Say("Hello from Zanna")
Hello from Zanna

See the Getting Started Guide for platform-specific setup, build directory layout, and troubleshooting.

• IL thin waist: Zia, BASIC, and future frontends share one typed IR, verifier, optimizer, VM, and native backend path.
• Self-contained native toolchain: Zanna includes its own runtime, assembler, linker, object writers, package generation, and install packaging paths.
• Machine-readable tooling: zanna check, zanna eval, zanna explain, --dump-runtime-api, and --dump-opcodes expose JSON-friendly surfaces for editors, scripts, and AI agents.
• Cross-platform by design: macOS, Linux, and Windows are first-class targets; platform checks are centralized in adapter layers.
• Runtime-first apps and games: The standard library includes 2D/3D graphics, GUI widgets, game systems, audio, networking, localization, threading, and structured data APIs.

The examples tree includes curated applications, games, 3D scenes, API audits, language samples, IL programs, and C++ embedding demos.

zanna run examples/games/chess/
zanna build examples/apps/paint/ -o paint
./scripts/build_demos.sh

The larger showcase titles — XENOSCAPE, Ashfall, 3D Bowling, Ridgebound, ZannaSQL, and more — live in the zannademos repository, which tests and builds them against a Zanna checkout.

+-------------------------+
|    Source Languages     |
|      Zia / BASIC        |
+-----------+-------------+
            |
            v
+-------------------------+
|  Parser / Sema / Lower  |
+-----------+-------------+
            |
            v
+-------------------------+
|       Zanna IL          |
|  Verifier / Optimizer   |
+------+------------+-----+
       |            |
       v            v
+-------------+  +-----------------+
|     VM      |  | Native Backends |
|  Interpreter|  | AArch64/x86-64  |
+------+------+  +-------+---------+
       |                 |
       +--------+--------+
                v
+-------------------------+
|      Zanna Runtime      |
| Collections / Graphics  |
| GUI / Game / Network    |
| Text / Threads / ...    |
+-------------------------+

See the Architecture Overview and Code Map for subsystem details.

Frontends lower to typed Zanna IL that is compact, explicit, and inspectable.

Zia source:

module Hello;

bind Zanna.Terminal;
bind Fmt = Zanna.Text.Fmt;

func start() {
    var x = 2 + 3;
    var y = x * 2;
    Say("HELLO");
    Say(Fmt.Int(y));
}

Representative IL:

il 0.3.0
extern @Zanna.Text.Fmt.Int(i64) -> str
extern @Zanna.Terminal.Say(str) -> void
global const str @.L0 = "HELLO"
func @main() -> void {
entry_0:
  %t0 = iadd.ovf 2, 3
  %t1 = imul.ovf %t0, 2
  %t2 = const_str @.L0
  call @Zanna.Terminal.Say(%t2)
  %t3 = call @Zanna.Text.Fmt.Int(%t1)
  call @Zanna.Terminal.Say(%t3)
  ret
}

Use --dump-il, --dump-il-opt, and zanna il-opt to inspect the pipeline. The IL Quickstart is the practical introduction; IL Guide is the normative reference.

All frontends share the Zanna Runtime Library. The runtime surface is generated from the live registry and spans:

• Collections, core types, functional helpers, math, text, structured data, I/O, time, and utilities
• 2D graphics, 3D graphics, Game3D, GUI widgets, input, audio, and game systems
• Networking, crypto, diagnostics, memory controls, threading, system APIs, and localization

Authoritative runtime inventory:

zanna --dump-runtime-api

Authoritative IL opcode inventory:

zanna --dump-opcodes

See the installer and package release guide for native signing, checksums, artifact inventories, release workflows, and clean-VM install/upgrade/uninstall validation.

Common examples:

zanna run program.zia
zanna -run program.il --max-steps 100000
zanna build project/ -o app
zanna check project/ --diagnostic-format=json
zanna eval '2 + 3 * 4' --json --type
zanna explain V-ZIA-UNDEFINED --json
zanna --dump-runtime-api
zanna --dump-opcodes

See the Tools Reference, Debugging Guide, and MCP tool reference for full details.

• CMake 3.20+
• C++20 compiler: Apple Clang, Clang, GCC 11+, or MSVC

# macOS
./scripts/build_zanna_mac.sh

# Linux
./scripts/build_zanna_linux.sh

# Windows
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build_zanna_win.ps1

The scripts configure, build, test, and install Zanna. The Unix wrappers delegate to scripts/build_zanna_unix.sh.

Useful iteration knobs:

Targeted checks after a build:

ctest --test-dir build -L codegen --output-on-failure
ctest --test-dir build -R test_zia_lexer --output-on-failure
./scripts/example_smoke.sh --fast

Platform guides:

• macOS
• Linux
• Windows

Getting Started: Setup Guide, REPL Guide, Zia Tutorial, The Zanna Book

Language References: Zia, BASIC, IL Guide, IL Quickstart

Runtime & APIs: Runtime Library, 3D Graphics, Game Engine, GUI

Internals: Architecture, VM, Code Map, Backend, IL Passes

Contributors: Contributor Guide, Frontend How-To, Testing

Zanna is in active development and the architecture is still stabilizing. Small fixes, documentation improvements, bug reports, and focused tests are welcome.

Before proposing changes:

• Read the relevant spec or reference first; IL Guide is normative for IL.
• Keep the product dependency-free.
• Preserve macOS, Windows, and Linux behavior.
• Use the platform build scripts and keep tests green.
• Follow Conventional Commits for commit messages.

See Contributor Guide and Testing for the full workflow.

Zanna is licensed under the GNU General Public License v3.0 (GPL-3.0-only).

See LICENSE for the full text.