tw.utils

Side: Shared + Client

General-purpose utility functions.

Shared Functions

tw.utils.to_table(value, key?) -> table

Wraps a non-table value into a table. If value is already a table, returns it as-is.

Parameter	Type	Default	Description
value	any	—	Value to wrap
key	string?	—	Key name to use when wrapping (creates {[key] = value})

Returns: table

tw.utils.to_table("hello")          -- {"hello"}
tw.utils.to_table("hello", "name")  -- {name = "hello"}
tw.utils.to_table({a = 1})          -- {a = 1} (unchanged)

---

tw.utils.fallback(value, default) -> any

Returns value if it is non-nil, otherwise returns default.

Parameter	Type	Description
value	any	Value to check
default	any	Fallback value if value is nil

Returns: any

local name = tw.utils.fallback(Config.Name, "Default")
local count = tw.utils.fallback(Config.Count, 10)

Client Functions

tw.utils.load_asset(name, wait_loaded?)

Loads an asset by name. Automatically detects the asset type (model, animation dictionary, or texture dictionary) and loads it accordingly.

Parameter	Type	Default	Description
name	string	—	Asset name
wait_loaded	boolean?	—	If true, blocks until the asset is fully loaded

tw.utils.load_asset("a_m_m_rancher_01", true)

---

tw.utils.release_asset(name)

Releases a previously loaded asset.

Parameter	Type	Description
name	string	Asset name to release

tw.utils.release_asset("a_m_m_rancher_01")

---

tw.utils.waiter(condition, max_duration?, poll_interval?) -> boolean

Waits while a condition is true. This is the inverse of tw.waiter.exec (which waits until a condition is true).

Parameter	Type	Default	Description
condition	function	—	Function that returns true to keep waiting
max_duration	integer?	—	Maximum wait time in ms (nil = wait forever)
poll_interval	integer?	—	Time between checks in ms

Returns: boolean — true if the condition became false, false if timed out.

-- Wait while the player is in a vehicle (max 10 seconds)
local exited = tw.utils.waiter(function()
    return IsPedInAnyVehicle(tw.player.ped, false)
end, 10000)

if exited then
    print("Player left the vehicle")
else
    print("Timed out")
end

---

tw.utils.screen_to_world(distance?, flags?, ignore_entity?, mouse_x?, mouse_y?) -> hit, end_coords, surface_normal, entity_hit

Casts a ray from screen coordinates into the 3D world. Useful for placement systems and mouse-based interactions.

Parameter	Type	Default	Description
distance	number?	—	Maximum ray distance
flags	integer?	—	Raycast flags
ignore_entity	integer?	—	Entity to ignore in the raycast
mouse_x	number?	—	Screen X coordinate (0.0 to 1.0). Defaults to screen center.
mouse_y	number?	—	Screen Y coordinate (0.0 to 1.0). Defaults to screen center.

Returns:

Return	Type	Description
hit	boolean	Whether the ray hit something
end_coords	vector3	World position of the hit point
surface_normal	vector3	Surface normal at the hit point
entity_hit	integer	Entity handle that was hit (0 if none)

local hit, coords, normal, entity = tw.utils.screen_to_world(100.0)

if hit then
    print("Hit at:", coords)
    if entity ~= 0 then
        print("Hit entity:", entity)
    end
end

Examples

Safe config access with fallbacks

local duration = tw.utils.fallback(Config.Duration, 5000)
local jobs = tw.utils.to_table(Config.AllowedJob)
-- Config.AllowedJob can be a string or a table, both work

Load and release assets

tw.utils.load_asset("p_axe02x", true)
-- use the model...
tw.utils.release_asset("p_axe02x")

Object placement with screen-to-world

CreateThread(function()
    while placing do
        local hit, coords = tw.utils.screen_to_world(50.0)
        if hit then
            -- move preview object to coords
            SetEntityCoords(preview, coords.x, coords.y, coords.z)
        end
        Wait(0)
    end
end)

Notes

• to_table is useful for config values that can be either a single value or a list.
• fallback only checks for nil — it does not replace false or other falsy values.
• waiter yields the current thread. It will block until the condition is false or the timeout expires.
• screen_to_world uses a raycast from the camera. If no mouse_x/mouse_y is provided, it casts from the screen center.