# Script Helpers
## 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.
{% hint style="info" %}
If debugMode is on it will draw a line ti visualise the raycast being done
{% endhint %}
**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.
{% hint style="info" %}
Delays the checking of netID to local ID but stops FiveM network entity warnings
{% endhint %}
**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())
```
***
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://jixelpatterns.gitbook.io/docs/dependency/jim_bridge/script-helpers.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.