From 8b78935772bb3093d3d743c951cbe98d5023ea95 Mon Sep 17 00:00:00 2001
From: RadsammyT <radsammyt@gmail.com>
Date: Tue, 16 Jun 2026 23:45:36 -0400
Subject: [PATCH] more example.lua documentation

---
 res/example.lua | 45 +++++++++++++++++++++++++++++++++++++--------
 1 file changed, 37 insertions(+), 8 deletions(-)

diff --git a/res/example.lua b/res/example.lua
index e6ede2f..36de8ff 100644
--- a/res/example.lua
+++ b/res/example.lua
@@ -9,19 +9,38 @@
 --	putCell(byte, fg, bg, x, y) -- Draw a cell. 
 --      All arguments to this function are integers, and 
 --      must be in the unsigned 32-bit integer range: 0 to 2^32-1.
+--      If an argument cannot be converted to this range, it will throw
+--      an error.
+--
+--      For reference, the XY coordinates (0,0) draw a cell on the top-left 
+--      of the terminal, where the positive-X axis moves right and the
+--      positive-Y axis moves down.
 --
 --      For arguments fg and bg: they are colors in the format
 --      0xSSRRGGBB, where SS is for styling. See your
 --      config.ini for more details.
 --
+--      For the byte argument, you may use string.byte to fill this argument.
+--
 --  clock() -- The time, in microseconds.
 -- }
 --
--- A function named `draw()` must be declared in the script. This is ran every frame.
+-- A function named `draw()` must be declared in the script. This is ran every
+-- frame.
+--
+-- In addition to the base library, you are also given the following standard
+-- libraries:
+-- 	bit (A library exclusive to LuaJIT, see https://bitop.luajit.org/api.html)
+--	math
+--	string
+--	table
+--
+--	The std libraries io and debug are NOT included.
 -- 
 -- ]]
 
--- You should probably copy FPS and FPS_COUNT into any future LuaJIT animations you create.
+-- You should probably copy FPS and FPS_COUNT into any future LuaJIT animations
+-- you create.
 local FPS_COUNT = 40
 local function FPS()
 	return (1/FPS_COUNT)*1000000
@@ -53,17 +72,27 @@ local timer = ly.clock()
 
 function draw()
 	-- Rather than progressing the animation by frame, do it based on
-	-- seconds, via ly.clock(). In this timeframe, you can update the animation state.
+	-- seconds, via ly.clock(). In this timeframe, you can update the animation
+	-- state.
 	-- DO NOT DRAW CELLS IN THIS TIMEFRAME. You will get flickering.
 
-	if timer + FPS() < ly.clock() then -- if this check passes, we can update the animation
+	-- if this check passes, we can update the animation
+	if timer + FPS() < ly.clock() then 
 		for i, v in ipairs(squares) do
 			v.x = v.x + v.vx
 			v.y = v.y + v.vy
-			if v.x == 0 then v.vx = 1; v.color = math.random(0xFFFFFF) end
-			if v.x + SQUARE_WIDTH >= ly.width-1 then v.vx = -1; v.color = math.random(0xFFFFFF) end
-			if v.y == 0 then v.vy = 1; v.color = math.random(0xFFFFFF) end
-			if v.y + SQUARE_HEIGHT >= ly.height-1 then v.vy = -1; v.color = math.random(0xFFFFFF) end
+			if v.x == 0 then 
+				v.vx = 1; v.color = math.random(0xFFFFFF)
+			end
+			if v.x + SQUARE_WIDTH >= ly.width-1 then
+				v.vx = -1; v.color = math.random(0xFFFFFF)
+			end
+			if v.y == 0 then 
+				v.vy = 1; v.color = math.random(0xFFFFFF)
+			end
+			if v.y + SQUARE_HEIGHT >= ly.height-1 then
+				v.vy = -1; v.color = math.random(0xFFFFFF) 
+			end
 		end
 		timer = ly.clock()
 	end