Reality Engine

Overview

Reality Engine Language (ZREL) and the Reality Engine Virtual Machine (VM) are designed for:

• Constrained systems (e.g., microcontrollers, retro consoles)
• Portable environments (e.g., Emscripten/Web)
• Permacomputing principles (e.g., long-term survivability, sustainability, zero dynamic allocation)

Key Design Goals

• Written in portable C89
• No dynamic memory: no malloc/free
• Designed for cross-platform reproducibility
• Inspired by Uxn, but more accessible than Forth-based stacks
• Built-in 3D primitive support for game developers

VM Architecture

CISC-like instruction format:

• 1-byte opcode
• 3-byte operand
• Register-based rather than stack-based

Register Set:

• Default: 32 general-purpose registers (may vary depending on L1/L2/L3 cache sizes)
• Always-initialized: Zero is a valid value; zero-initialized objects are always valid.
• Concept: ZII → Zero Is Initialization

Memory Model:

• Static memory

• Memory is managed via frame-based arenas:

  • function scopes defines a memory frame
  • "Heap" allocations push pointers within this frame
  • When a frame exits, the pointer is reset (like stack-based GC)
  • Values passed to functions must be explicitly returned to propagate
  • Heap values are copy-on-write

Error Handling:

• Stub values: Blocks of zeroed memory
• On failure, return a pointer to the zeroed stub
• Stubs are automatically cleared at the end of the frame

Language Features (ZREL)

Core Types:

• `int` (integer numbers)
• `nat` (natural numbers, also used for pointers)
• `real` (Q16.16 fixed-point real numbers)
• `str` (Fat pointers of 4-byte char packed or slices)

Array Semantics:

• Row-major, Fortran-style; replaces need for vec2/vec3/mat4x4
• Arrays are first-class values
• The compiler generates array multiplication code
• Supports array composition and manipulation without needing OOP or polymorphism

Boolean/Enum Strategy:

• Compile-time transformation of flags into parallel arrays
• Example: `monster_alive`, `monster_dead` → `MultiArrayList`

Graphics & Devices

Graphics:

• Memory-mapped devices (e.g., SDL surface points into memory)
• All rendering is done by manipulating the memory directly

• Texture system:

  • RGB8888 format default
  • Tile sizes: 8×8 to 32×32
  • Built-in automatic mipmapping (default for 128px), optional manual override

3D Primitives:

• Built-in support for simple 3D shapes
• Aimed at enabling PS1/N64-style rendering with minimal code

Development Environment

Goals:

• Live coding: Compile and inject code while VM is running
• Hot module reloading
• Shadowing + symbol versioning (inspired by Forth word tables)
• REPL-style interactivity (inspired by Lisp environments)

Symbol Table & Module System:

• Objects embed load-code for reconstruction
• Runtime symbol manipulation and memory inspection
• Final binaries are snapshots of the memory + symbol table

Sustainability & Permacomputing

The entire system adheres to the ethos of Permacomputing:

• Minimal resource usage
• Transparent, inspectable code and memory layouts
• Deterministic execution
• No garbage collector, no dynamic allocation
• Emphasis on long-term legibility and preservation

Implementation Status & Roadmap

• Implement frame-based memory management
• Add SDL device layer
• Write compiler front-end for ZREL
• Add array multiplication code generation
• Develop 3D primitive library
• Design module and hot reload system

License

To be determined. Preferably a permissive license (e.g., MIT, 0BSD) for long-term survivability.

Inspirations

• Uxn VM
• Plan 9
• Permacomputing wiki
• Handmade Network
• Dusk OS
• Dis VM
• Lox
• Lua
• Lisp
• C
• Fortran
• Zig

• Retro systems like:

  • N64
  • PlayStation 1
  • Macintosh Classic (System 7)
  • Windows 95