#+OPTIONS: toc:nil

* Reality Engine
#+DESCRIPTION: A sustainable, portable virtual machine and programming language for constrained systems and game preservation.
:PROPERTIES:
:CUSTOM_ID: zongors-universe-machine
:END:

#+begin_src 
[ ᛉ  .  .  .
  .  ᚱ  .  .
  .  .  ᛇ  .
  .  .  .  ᛚ]
#+end_src 

* 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

- [X] 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
- [[https://wiki.xxiivv.com/site/uxn.html][Uxn VM]]
- [[https://plan9.io/][Plan 9]]
- [[https://www.permacomputing.net][Permacomputing wiki]]
- [[https://handmade.network][Handmade Network]]
- [[http://duskos.org/][Dusk OS]]
- [[https://doc.cat-v.org/inferno/4th_edition/dis_VM_specification][Dis VM]]
- [[https://www.craftinginterpreters.com/the-lox-language.html][Lox]]
- [[https://lua.org][Lua]]
- [[https://en.wikipedia.org/wiki/Lisp_(programming_language)][Lisp]]
- [[https://en.wikipedia.org/wiki/C_(programming_language)][C]]
- [[https://fortran-lang.org/][Fortran]]
- [[https://ziglang.org/][Zig]]
- Retro systems like:
  - N64
  - PlayStation 1
  - Macintosh Classic (System 7)
  - Windows 95