#+TITLE: A Language for Enduring Realities
#+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

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 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 bytecode assembler that is inspired by Webassemblys WAT format.
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= | 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 {
  version 1;
  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** - persistent, versioned, serializable
- Stored in the internal graph

> *"A plex defines what a thing is. An atom is its instance in that reality."*

* Versioning & Shadowing (Forth-Inspired)

When you redefine a =plex=, the old version is **shadowed but preserved** - unless explicitly discarded.

#+BEGIN_SRC ul
plex Counter { version 1; nat value; inc() { value += 1; } }
plex Counter { version 2; nat value; inc() { value += 2; } }  ! shadows v1

Counter c1 = Counter();        ! uses v2 (latest)
Counter c2 = Counter.v1();     ! uses v1 - still available

discard Counter.v1;            ! optional: free memory
#+END_SRC

Internally, plex versions form a **linked version chain**:
- =head= -> latest version
- =tail= -> oldest retained version
- =migrate(obj, Counter)= -> converts data layout
- =versions(Counter)= -> list available versions

This enables:
- Non-destructive evolution
- Safe refactoring
- Historical reproducibility
- Code archaeology

* 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**.

* Development Environment

 supports **live coding** and **temporal development**:

**Live Coding Features**
- Hot module reloading: inject code while VM runs
- REPL-style interaction: inspect memory, call functions, test logic
- Shadowing: redefine =plex=es without restarting
- Symbol table manipulation: runtime introspection and patching

**Final Binaries**
- Are **snapshots** of:
  - Memory state
  - Symbol table
  - Version chains
- Can be saved, restored, or archived as =.zbin= files
- Are fully deterministic and reproducible

* 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