299 lines
8.7 KiB
Org Mode
299 lines
8.7 KiB
Org Mode
#+TITLE: The Reality Engine
|
|
#+AUTHOR: Zongor
|
|
#+EMAIL: archive@undar-lang.org
|
|
#+DATE: [2025-04-05]
|
|
#+LANGUAGE: en
|
|
#+OPTIONS: H:4 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
|
|
#+STARTUP: align fold nodlcheck hidestars oddeven lognotestate
|
|
#+TAGS: { TODO(t) NEXT(n) DONE(d) | HOLD(h) WAITING(w) CANCELLED(c) }
|
|
#+PROPERTY: header-args :tangle-mode (identity #o0644)
|
|
|
|
#+BEGIN_SRC
|
|
[ᚢ · · ·
|
|
· ᚱ · ·
|
|
· · ᛋ ·
|
|
· · · ᚾ]
|
|
#+END_SRC
|
|
|
|
The =Reality Engine= is a register-based virtual machine designed to render not just graphics, but persistent, inspectable, reproducible computational worlds.
|
|
|
|
It is:
|
|
- Written in **C89** for maximum portability
|
|
- **No dynamic allocation** - memory is static, frame-managed, zero-initialized
|
|
- **Deterministic by design** - identical input -> identical output
|
|
- **Self-inspectable** - symbol table, memory, and state are always accessible
|
|
- Inspired by Uxn, Dis VM, Dusk OS, and Plan 9
|
|
|
|
**VM Architecture**
|
|
|
|
| Feature | Specification |
|
|
|--------------------+---------------------------------------------|
|
|
| Instruction Format | 1-byte opcode, 3-byte operand (CISC-like) |
|
|
| Register Set | 32 general-purpose registers (R0-R31) |
|
|
| Initialization | **ZII**: Zero Is Initialization |
|
|
| Memory Model | Frame-based arenas (function scope = frame) |
|
|
| Heap Behavior | Copy-on-write; allocations append to frame |
|
|
| Frame Exit | Pointer resets on return (stack-GC style) |
|
|
| Error Handling | Returns stub pointers to zeroed memory |
|
|
|
|
This ensures:
|
|
- No =malloc=, no =free=, no GC
|
|
- Predictable memory use
|
|
- Perfect reproducibility
|
|
- Safe failure modes
|
|
|
|
* Undâr
|
|
|
|
Undâr is a permacomputing oriented, statically-typed language with **first-class arrays**, **immediate-mode semantics**, and **symbolic clarity**
|
|
- =Constrained systems=: microcontrollers, retro consoles (PS1, N64, Mac Classic)
|
|
- =Portable environments=: Web (Emscripten), embedded, CLI Tui
|
|
- =Permacomputing=: long-term survivability, sustainability, minimalism
|
|
- =3D world-building=: built-in primitives for PS1/N64-style rendering
|
|
- =Live development=: hot reloading, REPL, shadowing, symbol versioning
|
|
|
|
It runs on the =Reality Engine=, a minimal C89 VM inspired by Uxn, Plan 9, and Forth - but built for =spatial software=, =deterministic execution=, and =software that lasts=.
|
|
|
|
Sċieppan is a minimal lisp inpsired by sectorlisp.
|
|
You can view some examples in the =.lisp= files in =/test=
|
|
|
|
**Core Types**
|
|
|
|
| Type | Description |
|
|
|--------+-------------------------------------------|
|
|
| =int= | 32-bit signed integer |
|
|
| =nat= | 32-bit natural number |
|
|
| =real= | Float/Q16.16 fixed-point real number |
|
|
| =str= | 4-byte packed string or fat pointer |
|
|
| =bool= | Compile-time flag |
|
|
| =ref= | Reference prefix for passing by reference |
|
|
|
|
**Array Semantics (Fortran-Style)**
|
|
|
|
Arrays are **first-class values**:
|
|
|
|
#+BEGIN_SRC ul
|
|
real[3] pos = [1.0, 2.0, 3.0];
|
|
real[3][3] mat = identity(3);
|
|
real[3] result = mat * pos; ! compiler generates matrix-vector multiply
|
|
#+END_SRC
|
|
|
|
- Row-major order
|
|
- Fat pointers for slices and strings
|
|
- No =vec3=/=mat4x4= structs needed - math is generated
|
|
- Supports composition, slicing, element-wise ops
|
|
|
|
**Boolean/Enum Strategy**
|
|
|
|
Flags are compiled into **parallel arrays** (like =MultiArrayList=):
|
|
|
|
#+BEGIN_SRC ul
|
|
bool[] player_alive;
|
|
real[3][] player_pos;
|
|
str[] player_name;
|
|
#+END_SRC
|
|
|
|
This enables:
|
|
- Cache-friendly data layout
|
|
- No polymorphism tax
|
|
- High-performance iteration
|
|
|
|
* Plex: The Form of Being
|
|
|
|
A =plex= is a **Platonic form** - a structured definition of a kind of being in your program.
|
|
|
|
#+BEGIN_SRC ul
|
|
plex Player {
|
|
str name;
|
|
real[3] pos;
|
|
|
|
init(str name, real[3] pos) {
|
|
this.name = name;
|
|
this.pos = pos;
|
|
}
|
|
update() {}
|
|
logout() {}
|
|
}
|
|
#+END_SRC
|
|
|
|
- Not a class: no inheritance, no vtables
|
|
- Methods are functions with implicit =this= argument
|
|
- Instances are **atoms**
|
|
- A plex defines what a thing is. An atom is its instance.
|
|
|
|
* Graphics & Devices
|
|
|
|
**Memory-Mapped I/O**
|
|
|
|
Devices are memory-mapped:
|
|
- SDL surface -> direct memory access
|
|
- GPU registers -> memory addresses
|
|
- All rendering done by writing to memory
|
|
|
|
**Texture System**
|
|
- Default format: RGB332 (1 byte per pixel)
|
|
- Tile sizes: 8x8 to 32x32
|
|
- Automatic mipmapping for textures >128px
|
|
- Manual override available
|
|
|
|
**Immediate Mode GUI**
|
|
- Function calls are equivelent to redraws
|
|
- Child calls define spacial location in code as well as the UI
|
|
|
|
**3D Primitives**
|
|
Built-in support for:
|
|
- =Cube(pos, size)=
|
|
- =Plane(pos, radius)=
|
|
- =Model(mesh, texture)=
|
|
- Simple PS1/N64-style rendering pipeline
|
|
|
|
No shaders, no pipelines - just direct manipulation of memory and math.
|
|
|
|
* Tunnels: Unified I/O (Plan 9 / 9P-Inspired)
|
|
|
|
A =Tunnel= unifies:
|
|
- Files
|
|
- Sockets
|
|
- Web APIs
|
|
- Devices
|
|
- Databases
|
|
|
|
#+BEGIN_SRC ul
|
|
Tunnel server = Tunnel("tcp://localhost:25565");
|
|
if (server.attach(auth)) {
|
|
Player[] players = server.read("players");
|
|
server.write("me", me.update());
|
|
server.clunk();
|
|
}
|
|
#+END_SRC
|
|
|
|
**Tunnel Operations**
|
|
|
|
| Op | Meaning |
|
|
|------------+-----------------------|
|
|
| =.attach()= | Authenticate and open |
|
|
| =.open()= | Open resource |
|
|
| =.read()= | Transfer data |
|
|
| =.write()= | Transfer data |
|
|
| =.walk()= | Navigate hierarchy |
|
|
| =.flush()= | Cancel long operation |
|
|
| =.clunk()= | Close connection |
|
|
| =.stat()= | Get metadata |
|
|
| =.version()= | Get protocol version |
|
|
|
|
Tunnels make I/O **uniform, composable, and archival**.
|
|
|
|
**Live Coding Features**
|
|
- REPL-style interaction: inspect memory, call functions, test logic
|
|
|
|
* Getting Started
|
|
|
|
**Build the Reality Engine**
|
|
|
|
#+BEGIN_SRC sh
|
|
git clone https://git.alfrescocavern.com/zongor/reality-engine.git
|
|
cd reality-engine
|
|
make
|
|
./zre client.ul
|
|
#+END_SRC
|
|
|
|
**Sample Program: =hello.ul=**
|
|
|
|
#+BEGIN_SRC ul
|
|
function main(int argc, str[] argv) {
|
|
str name = argc > 1 ? argv[1] : "World";
|
|
print("Hello, {name}!");
|
|
exits("Done");
|
|
}
|
|
#+END_SRC
|
|
|
|
Run it:
|
|
|
|
#+BEGIN_SRC sh
|
|
./zre hello.ul Alice
|
|
# Output: Hello, Alice!
|
|
#+END_SRC
|
|
|
|
* Example: 3D Client (=client.ul=)
|
|
|
|
#+BEGIN_SRC ul
|
|
use "common.ul";
|
|
|
|
function main(int argc, str[] argv) {
|
|
nat w = 800, h = 450;
|
|
Player me(argv[1], [0.0, 1.0, 2.0], PURPLE);
|
|
|
|
bool running = true;
|
|
while (running) {
|
|
window("Client", w, h) {
|
|
splitbox(parent.size, 0.25) {
|
|
canvas() {
|
|
if (button("Logout")) {
|
|
me.logout();
|
|
running = false;
|
|
}
|
|
}
|
|
}
|
|
splitbox(parent.size, 0.75) {
|
|
canvas() {
|
|
model(Floor([0, 0, 0], 30));
|
|
me.update();
|
|
model(Cube(me.pos, [0.5,0.5,0.5], me.color));
|
|
if (Player[] others = me.server.read("players")) {
|
|
for (p in others) {
|
|
model(Cube(p.pos, [0.5,0.5,0.5], p.color));
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
exits("Client Closed Successfully");
|
|
}
|
|
#+END_SRC
|
|
|
|
* Future & Preservation
|
|
|
|
**Goals**
|
|
- Run on hardware from **1980 to 2080+**
|
|
- Be **hand-readable in 3024**
|
|
- Preserve digital art and games **forever**
|
|
|
|
**Preservation Plan**
|
|
- Text-based source: no binary blobs
|
|
- Versioned plexes: forward/backward compatibility
|
|
- Self-documenting syntax: just enough magic
|
|
- Open standard: no vendor lock-in
|
|
- Archive formats: =.ul=, =.ubin=, =.uatom=
|
|
|
|
* License
|
|
|
|
**MIT-0** - No restrictions, no warranty.
|
|
|
|
* Inspirations
|
|
|
|
- [[https://wiki.xxiivv.com/site/uxn.html][Uxn]] - Minimalism, elegance
|
|
- [[https://plan9.io/][Plan 9]] / 9P - Unified I/O, Tunnels
|
|
- [[https://forth-standard.org/][Forth]] - Shadowing, interactivity, immediacy
|
|
- [[https://en.wikipedia.org/wiki/Lisp_(programming_language)][Lisp]] - Live coding, REPL, introspection
|
|
- [[https://fortran-lang.org/][Fortran]] - Array semantics, scientific clarity
|
|
- [[https://en.wikipedia.org/wiki/C_(programming_language)][C]] / [[https://ziglang.org/][Zig]] - Control, minimalism
|
|
- [[https://lua.org][Lua]] - Languages can be portable and expressive without being complicated.
|
|
- [[https://www.craftinginterpreters.com/the-lox-language.html][Lox]] - Small languages are not impossible to create
|
|
- [[https://www.permacomputing.net][Permacomputing wiki]] - Sustainability, longevity
|
|
- [[http://duskos.org/][Dusk OS]] - Languages can survive the test of time.
|
|
- [[https://doc.cat-v.org/inferno/4th_edition/dis_VM_specification][Dis VM]] - CISC VM structure
|
|
- Retro Systems - N64, PS1, Mac Classic, Windows 95 - proof that beauty needs no bloat
|
|
|
|
* Join the Effort
|
|
|
|
The Reality Engine is a community project. We welcome:
|
|
- Port developers (Web, Game Boy, etc.)
|
|
- Artists and game designers
|
|
- Archivists and historians
|
|
|
|
* Contact
|
|
- Website: https://undar-lang.org
|
|
- Email: archive@undar-lang.org
|
|
- Repository: https://git.alfrescocavern.com/zongor/reality-engine.git
|
|
|