diff --git a/README.org b/README.org index e4fc833..39c7499 100644 --- a/README.org +++ b/README.org @@ -1,93 +1,151 @@ #+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 is a lightweight, portable programming language for permacomputing, game preservation, and indie game development inspired by [[https://wiki.xxiivv.com/site/uxn.html][uxn]], [[http://duskos.org/][Dusk OS]], and [[https://doc.cat-v.org/inferno/4th_edition/dis_VM_specification][Dis VM]]. - - Built in **C89** for cross-platform compatibility (desktop, microcontrollers, and web via Emscripten). - - Designed for simplicity, performance, and creative exploration. - - Reality Engine Language (ZRL) is a C-like, imperitve, data oriented language inspired by [[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]], and [[https://ziglang.org/][Zig]]. -* Key Features +Reality Engine Language (ZREL) and the Reality Engine Virtual Machine (VM) are designed for: -** Core Philosophy - - Simple, portable, lightweight, permacomputing oriented - - Targets retro hardware, game world preservation, rapid prototyping, and indie games. - - No macros or object hierarchies—prioritizes clarity and explicit behavior. - - C/Zig like syntax. Lisp/Lua like development workflow. +- Constrained systems (e.g., microcontrollers, retro consoles) +- Portable environments (e.g., Emscripten/Web) +- Permacomputing principles (e.g., long-term survivability, sustainability, zero dynamic allocation) -** Engine & Tooling - - Integrated 2D/3D rendering system: - - Immediate-mode canvas-based 3D rendering with low-poly 5th-6th gen console aesthetics. - - 2D canvas styled after ImGui and Raylib. - - [[https://www.libsdl.org/][SDL2]] backend for input, audio, and cross-platform compatibility. - - Tree-walk interpreter: - - Compile bytecode to files for performance. - - REPL with hot-code reloading for rapid iteration. - - Emacs major mode included; Vim, VSCode, and Lite XL support planned. +* Key Design Goals -** Language Design - - Strongly typed but with a friendly 'let' syntax. - - =real= type (f32). - - =int= for integer numbers (i32). - - =nat= for unsigned integer numbers (u32). - - =byte= arrays for interop (u8, i64, etc.). - - =str= Strings with interpolation, =split=, =replace=, =trim=, etc. - - Error handling: - - try-catch - - Null coalescing (=??=) and null checks (=?.=). - - Fortran style array operations. - - Lightweight coroutines with event-loop-driven multitasking. - - FFI via C-defined "system calls" (examples provided in VM). +- 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 -** Modularity & Ecosystem - - Fortran-like arrays. - - Standard library: math, networking, 3D rendering, minimal GUI. - - =use= keyword for modular code organization via file-based namespaces. +* VM Architecture -* Technical Details +**CISC-like instruction format:** -** VM Architecture - - register based bytecode interpreter written in C89. - - Portable to new systems, microcontrollers, and web via Emscripten. +- 1-byte opcode +- 3-byte operand +- **Register-based** rather than stack-based -** Memory Management - - Frame scoped arena allocators +**Register Set:** -** Rendering & I/O - - SDL2-based abstraction for input, audio, and rendering. - - Immediate-mode 3D canvas with 2D overlay support. +- 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 -* Planned Projects +**Memory Model:** -1. **Code Editor with Terminal Emulator** - - Built-in development tooling. -2. **3D Chat Room** - - Multiplayer cube avatars navigating a shared low-poly world. +- 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** -* Community & Collaboration +**Error Handling:** -- Website: [[https://alfrescocavern.com/][https://alfrescocavern.com/]] -- License: MIT -- Chat: Not yet +- 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 -* Roadmap +* Language Features (ZREL) -- [ ] MVP: Core VM, REPL, and SDL2 integration. -- [ ] 3D rendering pipeline + ImGui-style GUI. -- [ ] Standard library and FFI examples. -- [ ] Emacs/Vim tooling + website launch. -- [ ] Fixed point for numbers for microcontrollers/retro computers without fpu -- [ ] Custom renderer without SDL for portability +**Core Types:** -* Motivation +- `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) -ZRL bridges retro-inspired creativity with modern portability for: -- Game jams (rapid prototyping + 3D engine). -- Indie games (5th/6th-gen aesthetics). -- Permacomputing (low-resource, sustainable code). -- Education (simple VM/language design). +**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 diff --git a/docs/logo.svg b/docs/logo.svg new file mode 100644 index 0000000..d4a45c4 --- /dev/null +++ b/docs/logo.svg @@ -0,0 +1,38 @@ + + + [ + + + + + ] + + + ᛉ + . + . + . + + . + ᚱ + . + . + + . + . + ᛇ + . + + . + . + . + ᛚ +