From e0ef0ed1dbc58d4c55f1394f689eed9c0897b299 Mon Sep 17 00:00:00 2001
From: luigi-rosso <luigi-rosso@users.noreply.github.com>
Date: Sun, 5 Jul 2026 20:13:49 +0000
Subject: [PATCH] Update scripting API documentation

---
 scripting/api-reference/gpu/gpu-buffer.mdx | 12 ++--
 scripting/api-reference/mat4/mat4.mdx      | 33 ++++++++++
 scripting/api-reference/vector/vector.mdx  | 70 +++++++++++++++++++++-
 3 files changed, 109 insertions(+), 6 deletions(-)

diff --git a/scripting/api-reference/gpu/gpu-buffer.mdx b/scripting/api-reference/gpu/gpu-buffer.mdx
index c85d09bc..8edc82bd 100644
--- a/scripting/api-reference/gpu/gpu-buffer.mdx
+++ b/scripting/api-reference/gpu/gpu-buffer.mdx
@@ -27,15 +27,19 @@ new(desc: GPUBufferDesc) -> GPUBuffer
 
 ### `write`
 
-{/* function write(self, data: buffer, offset: number?): () */}
+{/* function write(self, data: buffer, offset: number?, srcOffset: number?, byteLength: number?): () */}
 <div class="signature">
 ```lua
-write(data: buffer, offset: number?) -> ()
+write(data: buffer, offset: number?, srcOffset: number?, byteLength: number?) -> ()
 ```
 </div>
 
 Copy CPU data into the buffer.
-@param data   Source bytes.
-@param offset Byte offset into the GPU buffer (default 0).
+@param data       Source bytes.
+@param offset     Byte offset into the GPU buffer (default 0).
+@param srcOffset  Byte offset into `data` to copy from (default 0).
+@param byteLength Bytes to copy (default: the rest of `data` from
+`srcOffset`). Lets a script upload a prefix of an
+oversized staging buffer without slicing it.
 
 
diff --git a/scripting/api-reference/mat4/mat4.mdx b/scripting/api-reference/mat4/mat4.mdx
index 8bcbd410..54c71b0f 100644
--- a/scripting/api-reference/mat4/mat4.mdx
+++ b/scripting/api-reference/mat4/mat4.mdx
@@ -195,6 +195,39 @@ local proj = Mat4.perspectiveReverseZ(math.rad(60), 16 / 9, 0.1)
 ```
 
 
+### `lookAt`
+
+{/* lookAt: (eye: Vector, center: Vector, up: Vector) -> Mat4 */}
+<div class="signature">
+```lua
+lookAt(eye: Vector, center: Vector, up: Vector) -> Mat4
+```
+</div>
+
+Creates a right-handed view matrix looking from `eye` toward
+`center` (GLM convention). `up` need not be normalized.
+```lua
+local view = Mat4.lookAt(Vector.xyz(0, 2, 5), Vector.origin(), Vector.xyz(0, 1, 0))
+```
+
+
+### `ortho`
+
+{/* ortho: (left: number, right: number, bottom: number, top: number, near: number, far: number) -> Mat4 */}
+<div class="signature">
+```lua
+ortho(left: number, right: number, bottom: number, top: number, near: number, far: number) -> Mat4
+```
+</div>
+
+Creates a right-handed orthographic projection matrix that maps z to
+the [0, 1] NDC depth range (matching `Mat4.perspective`), e.g. for
+shadow-map cascades or 2D overlays.
+```lua
+local proj = Mat4.ortho(-10, 10, -10, 10, 0.1, 100)
+```
+
+
 ### `multiply`
 
 {/* multiply: (output: Mat4, a: Mat4, b: Mat4) -> Mat4 */}
diff --git a/scripting/api-reference/vector/vector.mdx b/scripting/api-reference/vector/vector.mdx
index 8b0e2d45..eee30897 100644
--- a/scripting/api-reference/vector/vector.mdx
+++ b/scripting/api-reference/vector/vector.mdx
@@ -2,8 +2,10 @@
 title: Vector
 ---
 
-Represents a vector with up to three components. 2D APIs use only
-`x`/`y`; 3D APIs (e.g. `Mat4:transformPoint`) also populate `z`.
+Represents a vector with three components. Vectors created with
+`Vector.xy` have z = 0. All magnitude and interpolation operations
+(`length`, `dot`, `distance`, `normalized`, `lerp`, ...) use all three
+components; with z = 0 they behave exactly as 2D math.
 
 
 ## Fields
@@ -53,6 +55,21 @@ local v = Vector.xy(5, -2)  -- 5 -2
 ```
 
 
+### `xyz`
+
+{/* xyz: (x:number, y:number, z:number) -> Vector */}
+<div class="signature">
+```lua
+xyz(x: number, y: number, z: number) -> Vector
+```
+</div>
+
+Creates a vector with the specified x, y and z components.
+```lua
+local v = Vector.xyz(1, 2, 3)
+```
+
+
 ### `origin`
 
 {/* origin: () -> Vector */}
@@ -68,6 +85,21 @@ local origin = Vector.origin()  -- 0 0
 ```
 
 
+### `cross3`
+
+{/* cross3: (a: Vector, b: Vector) -> Vector */}
+<div class="signature">
+```lua
+cross3(a: Vector, b: Vector) -> Vector
+```
+</div>
+
+Returns the 3D cross product of two vectors.
+```lua
+local z = Vector.cross3(Vector.xyz(1,0,0), Vector.xyz(0,1,0))  -- 0 0 1
+```
+
+
 ### `scaleAndAdd`
 
 {/* scaleAndAdd: (a: Vector, b: Vector, scale: number) -> Vector */}
@@ -466,3 +498,37 @@ local p = a:lerp(b, 0.5)  -- 5 0
 ```
 
 
+### `writeToBuffer`
+
+{/* function writeToBuffer(self, buf: buffer, byteOffset: number): () */}
+<div class="signature">
+```lua
+writeToBuffer(buf: buffer, byteOffset: number) -> ()
+```
+</div>
+
+Writes x, y, z as 12 bytes (three float32) into the buffer at
+`byteOffset`.
+```lua
+local buf = buffer.create(12)
+Vector.xyz(1, 2, 3):writeToBuffer(buf, 0)
+```
+
+
+### `writeVec4`
+
+{/* function writeVec4(self, buf: buffer, byteOffset: number, w: number): () */}
+<div class="signature">
+```lua
+writeVec4(buf: buffer, byteOffset: number, w: number) -> ()
+```
+</div>
+
+Writes x, y, z, w as 16 bytes (four float32) into the buffer at
+`byteOffset`, matching a vec4 uniform-buffer slot.
+```lua
+local ubo = buffer.create(16)
+lightDir:writeVec4(ubo, 0, 0)  -- w = 0 for a direction
+```
+
+