Global Utility Functions Catalog

-- Read a JSON file and return a Lua table (utils.lua:478)
local data = jsonReadFile("path/to/file.json")
-- Returns nil if file doesn't exist or can't be parsed

-- Write a Lua table to JSON (utils.lua:460)
jsonWriteFile("path/to/file.json", myTable, true)
-- Args: filename, obj, pretty (bool), numberPrecision, atomicWrite
-- pretty=true for human-readable output
-- atomicWrite=true writes to .tmp first then renames (crash-safe)

-- Encode/decode without file I/O
local str = jsonEncode(myTable)
local str = jsonEncodePretty(myTable)
local tbl = jsonDecode(jsonString, sourceLabel)

-- Check if table is empty (utils.lua:591)
tableIsEmpty(tbl)  -- Returns true if nil, not a table, or has no entries

-- Get table size (SLOW - iterates all elements) (utils.lua:696)
tableSize(tbl)  -- Works with both arrays and dicts

-- Get keys as array (utils.lua:596)
local keys = tableKeys(tbl)

-- Get keys sorted (utils.lua:619)
local keys = tableKeysSorted(tbl)

-- Values as lookup dict (utils.lua:626)
local lookup = tableValuesAsLookupDict(tbl)  -- {val1=1, val2=1, ...}

-- Check if table contains a value (utils.lua:748)
tableContains(t, element)  -- Non-recursive, returns bool

-- Case-insensitive version (utils.lua:753)
tableContainsCaseInsensitive(t, element)

-- Find the key for a value (utils.lua:744)
local key = tableFindKey(t, element)

-- Find index in array (utils.lua:764)
local idx = arrayFindValueIndex(t, val)  -- Returns index or false

-- Deep copy (recursive, handles metatables) (utils.lua:844)
local copy = deepcopy(myTable)

-- Shallow copy (one level only) (utils.lua:830)
local copy = shallowcopy(myTable)

-- Merge src into dst (overwrites) (utils.lua:644)
tableMerge(dst, src)

-- Recursive merge (deep) (utils.lua:653)
tableMergeRecursive(dst, src)

-- Recursive merge that concatenates arrays instead of overwriting (utils.lua:665)
tableMergeRecursiveArray(dst, src)

-- Append src array to dst array (utils.lua:635)
arrayConcat(dst, src)

-- Shuffle array in-place (Fisher-Yates) (utils.lua:776)
arrayShuffle(array)

-- Reverse array in-place (utils.lua:784)
arrayReverse(array)

-- Create a read-only table (utils.lua:706)
local ro = tableReadOnly(myTable)  -- Errors on write attempts

-- Dump value to string (human-readable) (utils.lua:106)
dumps(value)       -- Returns string representation
dumps(a, b, c)     -- Multiple values

-- Dump with depth limit (utils.lua:134)
dumpsz(obj, depth)

-- Serialize to evaluable Lua string (utils.lua:1264)
local str = serialize(value)

-- Serialize/deserialize for VM reload
serializePackages(reason)    -- Saves extension state for Ctrl+L reload

-- Log a message (main.lua:30, wraps C++ Lua:log)
log(level, tag, message, ...)

-- Levels:
--   "A" - Always (print replacement)
--   "D" - Debug
--   "I" - Info
--   "W" - Warning
--   "E" - Error

-- Read entire file as string
local content = readFile(filename)  -- Returns nil if not found

-- Filesystem operations (C++ FS binding)
FS:fileExists(path)
FS:directoryExists(path)
FS:directoryCreate(path)
FS:findFiles(dir, pattern, depth, includeFiles, includeDirs)
FS:hashFile(path)
FS:getFileRealPath(path)      -- Resolve VFS path to disk path
FS:stat(path)                  -- File metadata
FS:renameFile(src, dst)
FS:isMounted(path)
FS:mountList(list)
FS:unmount(path)

-- Re-require a module (force reload) (luaCore.lua:21)
rerequire(moduleName)

-- Detect global variable writes (debug tool, called in main.lua init)
detectGlobalWrites()

-- vec3 (aliased as Point3F)
local v = vec3(x, y, z)
v:length()
v:normalized()
v:dot(other)
v:cross(other)
v:distance(other)

-- quat
local q = quat(x, y, z, w)

-- Common math
clamp(value, min, max)
lerp(a, b, t)
sign(x)
round(x)

-- String extensions
string.startswith(str, prefix)
string.endswith(str, suffix)
string.split(str, delimregex)  -- regex-based delimiter

-- Global functions
split(str, delim, nMax)  -- plain delimiter split
trim(str)                -- trim whitespace