152 lines
4.6 KiB
Org Mode
152 lines
4.6 KiB
Org Mode
#+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:
|
||
|
||
#+ATTR_HTML: :align center
|
||
#+ATTR_ORG: :align center
|
||
[[./docs/logo.svg]]
|
||
|
||
* 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
|