update readme
This commit is contained in:
parent
d57456d7b0
commit
18badca050
192
README.org
192
README.org
|
|
@ -1,93 +1,151 @@
|
||||||
#+OPTIONS: toc:nil
|
#+OPTIONS: toc:nil
|
||||||
|
|
||||||
* Reality Engine
|
* Reality Engine
|
||||||
|
#+DESCRIPTION: A sustainable, portable virtual machine and programming language for constrained systems and game preservation.
|
||||||
:PROPERTIES:
|
:PROPERTIES:
|
||||||
:CUSTOM_ID: zongors-universe-machine
|
:CUSTOM_ID: zongors-universe-machine
|
||||||
:END:
|
:END:
|
||||||
|
|
||||||
|
#+ATTR_HTML: :align center
|
||||||
|
#+ATTR_ORG: :align center
|
||||||
|
[[./docs/logo.svg]]
|
||||||
|
|
||||||
* Overview
|
* 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
|
- Constrained systems (e.g., microcontrollers, retro consoles)
|
||||||
- Simple, portable, lightweight, permacomputing oriented
|
- Portable environments (e.g., Emscripten/Web)
|
||||||
- Targets retro hardware, game world preservation, rapid prototyping, and indie games.
|
- Permacomputing principles (e.g., long-term survivability, sustainability, zero dynamic allocation)
|
||||||
- No macros or object hierarchies—prioritizes clarity and explicit behavior.
|
|
||||||
- C/Zig like syntax. Lisp/Lua like development workflow.
|
|
||||||
|
|
||||||
** Engine & Tooling
|
* Key Design Goals
|
||||||
- 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.
|
|
||||||
|
|
||||||
** Language Design
|
- Written in portable **C89**
|
||||||
- Strongly typed but with a friendly 'let' syntax.
|
- No dynamic memory: **no malloc/free**
|
||||||
- =real= type (f32).
|
- Designed for **cross-platform** reproducibility
|
||||||
- =int= for integer numbers (i32).
|
- Inspired by **Uxn**, but more accessible than Forth-based stacks
|
||||||
- =nat= for unsigned integer numbers (u32).
|
- Built-in **3D primitive support** for game developers
|
||||||
- =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).
|
|
||||||
|
|
||||||
** Modularity & Ecosystem
|
* VM Architecture
|
||||||
- Fortran-like arrays.
|
|
||||||
- Standard library: math, networking, 3D rendering, minimal GUI.
|
|
||||||
- =use= keyword for modular code organization via file-based namespaces.
|
|
||||||
|
|
||||||
* Technical Details
|
**CISC-like instruction format:**
|
||||||
|
|
||||||
** VM Architecture
|
- 1-byte opcode
|
||||||
- register based bytecode interpreter written in C89.
|
- 3-byte operand
|
||||||
- Portable to new systems, microcontrollers, and web via Emscripten.
|
- **Register-based** rather than stack-based
|
||||||
|
|
||||||
** Memory Management
|
**Register Set:**
|
||||||
- Frame scoped arena allocators
|
|
||||||
|
|
||||||
** Rendering & I/O
|
- Default: 32 general-purpose registers (may vary depending on L1/L2/L3 cache sizes)
|
||||||
- SDL2-based abstraction for input, audio, and rendering.
|
- Always-initialized: Zero is a valid value; zero-initialized objects are always valid.
|
||||||
- Immediate-mode 3D canvas with 2D overlay support.
|
- Concept: *ZII* → Zero Is Initialization
|
||||||
|
|
||||||
* Planned Projects
|
**Memory Model:**
|
||||||
|
|
||||||
1. **Code Editor with Terminal Emulator**
|
- Static memory
|
||||||
- Built-in development tooling.
|
- Memory is managed via *frame-based arenas*:
|
||||||
2. **3D Chat Room**
|
- function scopes defines a memory *frame*
|
||||||
- Multiplayer cube avatars navigating a shared low-poly world.
|
- "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/]]
|
- Stub values: Blocks of zeroed memory
|
||||||
- License: MIT
|
- On failure, return a pointer to the zeroed stub
|
||||||
- Chat: Not yet
|
- Stubs are automatically cleared at the end of the frame
|
||||||
|
|
||||||
* Roadmap
|
* Language Features (ZREL)
|
||||||
|
|
||||||
- [ ] MVP: Core VM, REPL, and SDL2 integration.
|
**Core Types:**
|
||||||
- [ ] 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
|
|
||||||
|
|
||||||
* 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:
|
**Array Semantics:**
|
||||||
- Game jams (rapid prototyping + 3D engine).
|
|
||||||
- Indie games (5th/6th-gen aesthetics).
|
|
||||||
- Permacomputing (low-resource, sustainable code).
|
|
||||||
- Education (simple VM/language design).
|
|
||||||
|
|
||||||
|
- 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
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,38 @@
|
||||||
|
<svg xmlns="http://www.w3.org/2000/svg" width="140" height="160" font-family="serif" font-size="20">
|
||||||
|
<!-- Left bracket -->
|
||||||
|
<text x="5" y="25">[</text>
|
||||||
|
<!--
|
||||||
|
<text x="5" y="65">[</text>
|
||||||
|
<text x="5" y="105">[</text>
|
||||||
|
<text x="5" y="145">[</text>
|
||||||
|
-->
|
||||||
|
|
||||||
|
<!-- Right bracket -->
|
||||||
|
<!--
|
||||||
|
<text x="125" y="25">]</text>
|
||||||
|
<text x="125" y="65">]</text>
|
||||||
|
<text x="125" y="105">]</text>
|
||||||
|
-->
|
||||||
|
<text x="125" y="145">]</text>
|
||||||
|
|
||||||
|
<!-- Matrix content -->
|
||||||
|
<text x="35" y="25">ᛉ</text>
|
||||||
|
<text x="65" y="25">.</text>
|
||||||
|
<text x="95" y="25">.</text>
|
||||||
|
<text x="115" y="25">.</text>
|
||||||
|
|
||||||
|
<text x="35" y="65">.</text>
|
||||||
|
<text x="65" y="65">ᚱ</text>
|
||||||
|
<text x="95" y="65">.</text>
|
||||||
|
<text x="115" y="65">.</text>
|
||||||
|
|
||||||
|
<text x="35" y="105">.</text>
|
||||||
|
<text x="65" y="105">.</text>
|
||||||
|
<text x="95" y="105">ᛇ</text>
|
||||||
|
<text x="115" y="105">.</text>
|
||||||
|
|
||||||
|
<text x="35" y="145">.</text>
|
||||||
|
<text x="65" y="145">.</text>
|
||||||
|
<text x="95" y="145">.</text>
|
||||||
|
<text x="115" y="145" text-anchor="middle">ᛚ</text>
|
||||||
|
</svg>
|
||||||
|
After Width: | Height: | Size: 1011 B |
Loading…
Reference in New Issue