From f4cf1a457a594ba3fa87960eb3994b1f7851e1f6 Mon Sep 17 00:00:00 2001 From: zongor Date: Sat, 24 May 2025 23:27:01 -0400 Subject: [PATCH] update readme, spec, example --- README.org | 94 +++++++++++++++++++--- docs/SPECIFICATION.org | 4 +- docs/project-syntax-example/src/client.ztl | 30 +++---- 3 files changed, 101 insertions(+), 27 deletions(-) diff --git a/README.org b/README.org index 4c19853..53510ab 100644 --- a/README.org +++ b/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. diff --git a/docs/SPECIFICATION.org b/docs/SPECIFICATION.org index eb98fd0..48dce7f 100644 --- a/docs/SPECIFICATION.org +++ b/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 - ++ diff --git a/docs/project-syntax-example/src/client.ztl b/docs/project-syntax-example/src/client.ztl index ea80be7..0133f28 100644 --- a/docs/project-syntax-example/src/client.ztl +++ b/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) { + +}