jim_bridge/documentation/helper_functions/helpers.md

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:

    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:

    print("Current script:", getScript())
    

• isServer()

  • Returns true if running on the server.
  • This was mainly made becuase IsDuplicityVersion() kept confusing me
  • Example:

    if isServer() then print("Server-side!") end
    

• debugPrint(...) / eventPrint(...)

  • Prints messages with debug context if debugMode is enabled.
  • Example:

    debugPrint("Loaded object:", objName)
    

• jsonPrint(table)

  • Pretty-prints a table with colorized JSON if debugMode is enabled.
  • Example:

    jsonPrint(myData)
    

• keyGen()

  • Generates a 3-character unique ID.
  • Good grabbing randomly generated strings
  • Example:

    print("Generated Key:", keyGen())
    

• cv(amount)

  • Comma-separates a number (e.g., 1000000 to 1,000,000).
  • Example:

    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:

    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:

    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:

    print(countTable({a=1,b=2,c=3})) -- 3
    

• pairsByKeys(tbl)

  • Iterator for sorted keys.
  • Example:

    for k, v in pairsByKeys(myTable) do print(k, v) end
    

• concatenateText(tbl)

  • Joins string table entries with newlines.
  • Example:

    print(concatenateText({"Line 1", "Line 2"}))
    

• RotationToDirection(rot)

  • Converts a heading vector to a directional vector.
  • Example:

    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:

    print(basicBar(50))
    

• normalizeVector(vec)

  • Returns a normalized version of a vector3.
  • Example:

    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:

    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:

    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:

    coords = adjustForGround(vector3(100, 200, 300))
    

• ensureNetToVeh(id) / ensureNetToEnt(id)

  • Resolves net ID to entity safely.
  • Example:

    local veh = ensureNetToVeh(netId)
    

• sendLog(text) / sendServerLog(data)

  • Logging helpers, includes player name, coords, script source.
  • Example:

    sendLog("Suspicious activity detected")
    

• GetGroundMaterialAtPosition(coords)

  • Returns the material hash + readable name from the surface below coords.
  • Example:

    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:

    local w,d,h = GetPropDimensions("prop_barrel_01a")
    

• GetEntityForwardVector(entity)

  • Returns the forward direction vector based on entity heading.
  • Example:

    local fwd = GetEntityForwardVector(PlayerPedId())