update readme, spec, example

README.org

@@ -4,16 +4,88 @@
 :PROPERTIES:
 :CUSTOM_ID: zongors-universe-machine
 :END:
-The universe machine is a Virtual Machine that is intended to create 3D
-environments (Universes) for video games and/or generic 3d modeling jobs
 
-It is inspired by [[https://wiki.xxiivv.com/site/uxn.html][uxn]],
-[[https://web.archive.org/web/20210913164515/https://www.oocities.org/connorbd/varaq/index.html][var'aq]],
-[[https://www.zachtronics.com/tis-100/][TIS-100]],
-[[https://github.com/LMP88959/PL3D-KC][the kings crook engine by EMMIR]],
-[[http://duskos.org/][Dusk os]],
-[[https://www.inferno-os.org/][Inferno]], and
-[[https://plan9.io/plan9/][Plan9]].
+* Overview
+  ZTL is a lightweight, portable programming language for permacomputing, game preservation, and indie game development.
+  Built in **C99** for cross-platform compatibility (desktop, microcontrollers, and web via Emscripten).
+  Designed for simplicity, performance, and creative exploration.
+  It is inspired by [[https://wiki.xxiivv.com/site/uxn.html][uxn]], [[http://duskos.org/][Dusk OS]], [[https://lua.org][Lua]], [[https://en.wikipedia.org/wiki/Lisp_(programming_language)][Lisp]], [[https://en.wikipedia.org/wiki/C_(programming_language)][C]], and [[https://ziglang.org/][Zig]].
 
-The authors main implementation of ZUM in written in ZTL/C and uses the
-[[https://www.libsdl.org/][SDL2]] library as this implementations backend to do drawing, sound, and other things.
+* Key Features
+
+** Core Philosophy
+  - Simple, portable, lightweight syntax inspired by C.
+  - Targets permacomputing, game world preservation, rapid prototyping, and indie games.
+  - No macros or object hierarchies—prioritizes clarity and explicit behavior.
+
+** Engine & Tooling
+  - Integrated 2D/3D rendering system:
+    - Immediate-mode canvas-based 3D rendering with low-poly 5th–6th gen console aesthetics.
+    - 2D overlays styled after ImGui.
+    - [[https://www.libsdl.org/][SDL2]] backend for input, audio, and cross-platform compatibility.
+  - Tree-walk interpreter + stack-based bytecode VM:
+    - 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
+  - Dynamically typed with optional type hints in function signatures.
+  - Unified =real= type (=f64= by default) with =byte= for interop (u8, i32, f32, etc.).
+  - 3D math primitives: =vec=, =mat=, =quat=, and more.
+  - Strings with interpolation, =split=, =replace=, =trim=, etc.
+  - Error handling:
+    - Go-style explicit errors.
+    - Null coalescing (=??=) and null checks (=?.=).
+  - Lightweight coroutines with event-loop-driven multitasking.
+  - FFI via C-defined "native functions" (examples provided in VM).
+
+** Modularity & Ecosystem
+  - Unified table type (like Lua) for lists, maps, and tuples.
+  - Standard library: math, networking, 3D rendering, minimal GUI.
+  - =use= keyword for modular code organization via file-based namespaces.
+
+* Technical Details
+
+** VM Architecture
+   - Stack-based bytecode interpreter written in C99.
+   - Portable to new systems, microcontrollers, and web via Emscripten.
+
+** Memory Management
+   - Reference counting for globally scoped objects.
+   - =weak= keyword to avoid cyclical references.
+   - Arena allocators for short-lived, scoped memory (e.g., function-local objects).
+
+** Rendering & I/O
+   - SDL2-based abstraction for input, audio, and rendering.
+   - Immediate-mode 3D canvas with 2D overlay support.
+
+* Planned Projects
+
+1. **Code Editor with Terminal Emulator**
+   - Built-in development tooling.
+2. **3D Chat Room**
+   - Multiplayer cube avatars navigating a shared low-poly world.
+
+* Community & Collaboration
+
+- Website: [[https://yourwebsite.org/permalang][https://alfrescocavern.com/ztl]]
+- License: GPLv3
+- Chat: Not yet
+
+* Roadmap
+
+- [ ] MVP: Core VM, REPL, and SDL2 integration.
+- [ ] 3D rendering pipeline + ImGui-style GUI.
+- [ ] Standard library and FFI examples.
+- [ ] Emacs/Vim tooling + website launch.
+
+* Motivation
+
+ztl 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).
+
+* Contributing
+  Contributions welcome! Join the community or submit PRs on GitHub/GitLab/yourrepo.

docs/SPECIFICATION.org

@@ -132,6 +132,8 @@ The following is a list of global operators and their effect:
   - comment
 - ??
   - unwrap or
+- .?
+  - null check or return error
 - +
   - addition
 - -
@@ -153,8 +155,6 @@ The following is a list of global operators and their effect:
   - greater than or equals
 - <=
   - less than or equals
-- |>
-  - curry a function into another function (like haskell shove)
 - .
   - accessor
 - ++

docs/project-syntax-example/src/client.ztl

@@ -20,23 +20,25 @@ fn main (argc real, argv str[]) {
    let universe = Universe();
    let canvas = Canvas();
    canvas.append(Button("logout", fn () {
-      window.close = true;
-   }))
+      me.logout();
+      window.send("close");
+   }));
    splitbox.left.append(universe);
    splitbox.right.append(canvas);
 
-   while ( not window.should_close() ) {
-      me.update();
+   universe.append(Grid(30, 1.0));
+   universe.append(Cube(player.pos, (0.5, 0.5, 0.5), me.appearance), player_behavior);
+   universe.listen("login", fn () {
+       let p = m.data as Player;
+       if (!p) return;
+       universe.append(Cube(p.pos, (0.5, 0.5, 0.5), p.apperance), player_behavior);
+   });
 
-      universe.draw_grid(30, 1.0);
-      universe.draw_cube(me.pos, (0.5, 0.5, 0.5), me.apperance);
-
-      for (player in players) {
-         universe.draw_cube(player.pos, (0.5, 0.5, 0.5), player.apperance);
-      }
-   } 
-
-   me.logout();
-   window.close();
+   window.run();
    exits("Client Closed Successfully");
 }
+
+
+fn player_behavior(Message m) {
+
+}