better documentation layout

- seperated the 2000+ lines in ReadMe.md into seperate files. - useful if things expand - better readability for users - more organised layout
2026-08-17 05:56:02 +01:00 · 2025-05-16 14:28:41 +01:00
parent 520758b355
commit 451e4cbbdb
29 changed files with 1690 additions and 1719 deletions
--- a/documentation/helper_functions/helpers.md
+++ b/documentation/helper_functions/helpers.md
@@ -0,0 +1,177 @@
+### helpers.lua
+This utility module provides functions for resource checks, debugging, formatting, coordinate math, vector calculations, progress bars, and drawing tools.
+
+- **isStarted(script)**
+  - Returns `true` if a resource is started.
+  - **Example:**
+    ```lua
+    if isStarted("myResource") then print("Resource is running") end
+    ```
+
+- **getScript()**
+  - Caches and returns the name of the current resource.
+  - Easier than typing `GetCurrentResourceName()` over and over
+  - **Example:**
+    ```lua
+    print("Current script:", getScript())
+    ```
+
+- **isServer()**
+  - Returns true if running on the server.
+  - This was mainly made becuase `IsDuplicityVersion()` kept confusing me
+  - **Example:**
+    ```lua
+    if isServer() then print("Server-side!") end
+    ```
+
+- **debugPrint(...)** / **eventPrint(...)**
+  - Prints messages with debug context if debugMode is enabled.
+  - **Example:**
+    ```lua
+    debugPrint("Loaded object:", objName)
+    ```
+
+- **jsonPrint(table)**
+  - Pretty-prints a table with colorized JSON if debugMode is enabled.
+  - **Example:**
+    ```lua
+    jsonPrint(myData)
+    ```
+
+- **keyGen()**
+  - Generates a 3-character unique ID.
+  - Good grabbing randomly generated strings
+  - **Example:**
+    ```lua
+    print("Generated Key:", keyGen())
+    ```
+
+- **cv(amount)**
+  - Comma-separates a number (e.g., `1000000` to `1,000,000`).
+  - **Example:**
+    ```lua
+    print(cv(1000000)) -- "1,000,000"
+    ```
+
+- **formatCoord(vec)**
+  - Outputs a formatted string from vector types.
+  - Compacts and adds console colours to the vector to be printed
+  - **Example:**
+    ```lua
+    print(formatCoord(vector3(123.45, 678.9, 10.0)))
+    ```
+
+- **getCenterOfZones(coords)**
+  - Returns average center position of a vector3 list.
+  - A few use cases, but I used it to see how well spaced blips were together
+  - **Example:**
+    ```lua
+    local center = getCenterOfZones({vector3(0,0,0), vector3(10,10,0)})
+    ```
+
+- **countTable(tbl)**
+  - Returns the number of entries in a table.
+  - Simple function to print how many "entires" are in a table
+  - **Example:**
+    ```lua
+    print(countTable({a=1,b=2,c=3})) -- 3
+    ```
+
+- **pairsByKeys(tbl)**
+  - Iterator for sorted keys.
+  - **Example:**
+    ```lua
+    for k, v in pairsByKeys(myTable) do print(k, v) end
+    ```
+
+- **concatenateText(tbl)**
+  - Joins string table entries with newlines.
+  - **Example:**
+    ```lua
+    print(concatenateText({"Line 1", "Line 2"}))
+    ```
+
+- **RotationToDirection(rot)**
+  - Converts a heading vector to a directional vector.
+  - **Example:**
+    ```lua
+    local dir = RotationToDirection(rotation)
+    ```
+
+- **basicBar(percent)**
+  - Returns a bar like `████░░░░░` at 50%.
+  - Basically a progress bar but as a string, I use this in drawTexts when progressbars aren't able to be used
+  - **Example:**
+    ```lua
+    print(basicBar(50))
+    ```
+
+- **normalizeVector(vec)**
+  - Returns a normalized version of a vector3.
+  - **Example:**
+    ```lua
+    local norm = normalizeVector(vector3(3,4,0))
+    ```
+
+- **drawLine(start, end, color)** / **drawSphere(pos, color)**
+  - Debug drawing helpers.
+  - Stays visible for more than one frame
+  - **Example:**
+    ```lua
+    drawLine(vector3(0,0,0), vector3(10,10,10), vector4(255,0,0,255))
+    drawSphere(vector3(5,5,5), vector4(0,255,0,255))
+    ```
+
+- **PerformRaycast(start, end, entity?, flags?)**
+  - Raycast with material detection. Returns ray hit data.
+  - **Example:**
+    ```lua
+    local hit, hitPos, material = PerformRaycast(startVec, endVec, playerPed, 1)
+    if hit == 1 then
+        print("Hit at position:", hitPos)
+        print("Material:", material)
+    end
+    ```
+
+- **adjustForGround(coords)**
+  - Adjusts a z-coordinate to ground height.
+  - **Example:**
+    ```lua
+    coords = adjustForGround(vector3(100, 200, 300))
+    ```
+
+- **ensureNetToVeh(id)** / **ensureNetToEnt(id)**
+  - Resolves net ID to entity safely.
+  - **Example:**
+    ```lua
+    local veh = ensureNetToVeh(netId)
+    ```
+
+- **sendLog(text)** / **sendServerLog(data)**
+  - Logging helpers, includes player name, coords, script source.
+  - **Example:**
+    ```lua
+    sendLog("Suspicious activity detected")
+    ```
+
+- **GetGroundMaterialAtPosition(coords)**
+  - Returns the material hash + readable name from the surface below coords.
+  - **Example:**
+    ```lua
+    local hash, name = GetGroundMaterialAtPosition(vector3(0,0,0))
+    ```
+
+- **GetPropDimensions(model)**
+  - Loads a model and returns width, depth, height.
+  - I use this to parse a model to create a box target instead of entity target when creating distProps/distPeds
+  - **Example:**
+    ```lua
+    local w,d,h = GetPropDimensions("prop_barrel_01a")
+    ```
+
+- **GetEntityForwardVector(entity)**
+  - Returns the forward direction vector based on entity heading.
+  - **Example:**
+    ```lua
+    local fwd = GetEntityForwardVector(PlayerPedId())
+    ```
--- a/documentation/helper_functions/loaders.md
+++ b/documentation/helper_functions/loaders.md
@@ -0,0 +1,89 @@
+### loaders.lua
+This module provides loading utilities for common asset types such as models, animations, texture dictionaries, and audio banks. It also provides animation and sound helpers.
+
+- **loadModel(model)**
+  - Loads a model into memory if valid and not already loaded.
+  - **Example:**
+    ```lua
+    loadModel('prop_chair_01a')
+    ```
+
+- **unloadModel(model)**
+  - Unloads a model from memory.
+  - **Example:**
+    ```lua
+    unloadModel('prop_chair_01a')
+    ```
+
+- **loadAnimDict(animDict)**
+  - Loads an animation dictionary into memory.
+  - **Example:**
+    ```lua
+    loadAnimDict('amb@world_human_hang_out_street@male_c@base')
+    ```
+
+- **unloadAnimDict(animDict)**
+  - Removes an animation dictionary from memory.
+  - **Example:**
+    ```lua
+    unloadAnimDict('amb@world_human_hang_out_street@male_c@base')
+    ```
+
+- **loadPtfxDict(ptFxName)**
+  - Loads a particle effect (ptfx) dictionary.
+  - **Example:**
+    ```lua
+    loadPtfxDict('core')
+    ```
+
+- **unloadPtfxDict(dict)**
+  - Unloads a particle effect dictionary from memory.
+  - **Example:**
+    ```lua
+    unloadPtfxDict('core')
+    ```
+
+- **loadTextureDict(dict)**
+  - Loads a streamed texture dictionary.
+  - **Example:**
+    ```lua
+    loadTextureDict('commonmenu')
+    ```
+
+- **loadScriptBank(bank)**
+  - Loads a script audio bank.
+  - Returns true on success.
+  - **Example:**
+    ```lua
+    local success = loadScriptBank('DLC_HEISTS_GENERAL_FRONTEND_SOUNDS')
+    ```
+
+- **loadAmbientBank(bank)**
+  - Loads an ambient audio bank.
+  - Returns true on success.
+  - **Example:**
+    ```lua
+    local success = loadAmbientBank('AMB_REVERB_GENERIC')
+    ```
+
+- **playAnim(animDict, animName, duration?, flag?, ped?, speed?)**
+  - Plays an animation on a ped.
+  - Loads the dictionary if not already loaded.
+  - **Example:**
+    ```lua
+    playAnim('amb@world_human_hang_out_street@male_c@base', 'base', 5000, 1, PlayerPedId(), 1.0)
+    ```
+
+- **stopAnim(animDict, animName, ped?)**
+  - Stops an animation and unloads the dictionary.
+  - **Example:**
+    ```lua
+    stopAnim('amb@world_human_hang_out_street@male_c@base', 'base', PlayerPedId())
+    ```
+
+- **playGameSound(audioBank, soundSet, soundRef, coords, synced, range?)**
+  - Plays a game sound from a coordinate or entity.
+  - **Example:**
+    ```lua
+    playGameSound('DLC_HEIST_HACKING_SNAKE_SOUNDS', 'Beep', vector3(0, 0, 0), false, 15.0)
+    ```