From 690c6009419f6f07ee6166d01932330c3096c615 Mon Sep 17 00:00:00 2001
From: me <me@alloca.space>
Date: Thu, 25 Dec 2025 00:44:18 +0200
Subject: [PATCH] readme

---
 games/basic.ayin |  41 +++++++++++++++++
 readme.md        | 111 +++++++++++++++++++++++++++++++++++------------
 2 files changed, 124 insertions(+), 28 deletions(-)
 create mode 100644 games/basic.ayin

diff --git a/games/basic.ayin b/games/basic.ayin
new file mode 100644
index 0000000..f8de173
--- /dev/null
+++ b/games/basic.ayin
@@ -0,0 +1,41 @@
+let migrate = fn(state) {
+    state
+}
+
+let setup = fn() {
+  return {
+    .color: {
+	  .r: 0,
+	  .g: 0,
+	  .b: 100,
+	},
+  }
+}
+
+let update = fn(state, input) {
+  let x = if input.gamepad1.dpad.up { 1 } else { 0 } + if input.gamepad1.dpad.down { -1 } else { 0 }
+
+  let new_blue = state.color.b + x
+
+  state.color.b = min(255, max(0, new_blue))
+}
+
+let draw = fn(state) {
+  frame_clear(state.color.r, state.color.g, state.color.b)
+}
+
+let min = fn(a,b) {
+  if a < b {
+    a
+  } else {
+    b
+  }
+}
+
+let max = fn(a,b) {
+  if a < b {
+    b
+  } else {
+    a
+  }
+}
diff --git a/readme.md b/readme.md
index 192d721..0109468 100644
--- a/readme.md
+++ b/readme.md
@@ -1,46 +1,99 @@
-Ayin
-----
+Ayin 👁️‍🗨️
+-------
 
+Programming language and games in 1 week inspired by Langjam Gamejam.
 
-- Tiny, procedural, gamedev
-- only user input is controller input
-- Live code reload
-- int, float, string, char, bool
-- arrays and objects
-- variables and functions
+## Main ideas
+
+- Tiny procedural language specifically for gamedev
+- Wrapped by a game framework
+- Only user input is controller input (or specific keyboard keys)
+- Basic types: int, float, string, char, bool, objects, arrays, first-class functions
 - if, loop, break, return
-- function calls
-- first class functions
+- ✨Live code reload✨
 
-```
-let setup = fn() {
-  return {
-    .player: { .position: { .x: 10, .y: 20 }, },
-  }
-}
-
-let update = fn(state, events) {
-  let new = 100
-  state.player.position.x = new
-  state
-}
-
-let draw = fn(frame, state) {
-  frame_clear(0,0,0)
-}
+## Basic example
 
+```rs
 let migrate = fn(state) {
     state
 }
+
+let setup = fn() {
+  return {
+    .color: {
+	  .r: 0,
+	  .g: 0,
+	  .b: 100,
+	},
+  }
+}
+
+let update = fn(state, input) {
+  let x = if input.gamepad1.dpad.up { 1 } else { 0 } + if input.gamepad1.dpad.down { -1 } else { 0 }
+
+  let new_blue = state.color.b + x
+
+  state.color.b = min(255, max(0, new_blue))
+}
+
+let draw = fn(state) {
+  frame_clear(state.color.r, state.color.g, state.color.b)
+}
+
+let min = fn(a,b) {
+  if a < b {
+    a
+  } else {
+    b
+  }
+}
+
+let max = fn(a,b) {
+  if a < b {
+    b
+  } else {
+    a
+  }
+}
 ```
 
-- dynamic software updating could occur every frame
-- user might be required to migrate the state (migrate function is hashed and only applied on updates when it is changed)
+
+
+## Program interface
+
+A program is consists of 4 functions.
+
+- `let setup = fn() -> state` - create a state object for your program. Runs at the start of the program.
+- `let update = fn(state, input)` - update the state using user inputs at each game loop cycle.
+- `let draw = fn(state)` - draw the state to the screen at the end of each game loop cycle.
+- `let migrate = fn(state) -> state'` - update the game state to a new start, runs on live reloading.
+
+### Live reloading
+
+- Live code reloading watches the file for changes and updates the code between game loop cycles while keeping the state.
+- The `migrate` function is used to migrate the state value for when the structure of the state changes.
 
 ## Build instructions
 
+### Non-web
+
+To run There-she-is:
+
+```
+make run
+```
+
+On Fedora, required for hot code reloading:
+
+```
+sudo dnf install systemd-devel
+```
+
 ### WASM
 
+Requires to build for wasm:
+
 ```
 rustup target add wasm32-unknown-unknown
 ```
@@ -48,3 +101,5 @@ rustup target add wasm32-unknown-unknown
 ```
 make wasm
 ```
+
+Go to `html/` and start a web server.