Skip to content
MTA:SA Neon Documentation

engineLoadCOL

Client-side
NEON EXTENSIONRuntime collision generation

A standard MTA API with Neon behavior

Loads a collision model from a .col file as in standard MTA, or builds one from a Lua collision table.

Syntax

col|false engineLoadCOL(string|table collision)

Arguments

collisionstring|table

A .col file path or raw data for the standard path, or a collision table of spheres, boxes and meshes for the Neon path.

Table keys

Shapes

spherestableoptional

Array of {position = {x,y,z}, radius = n, material = 0-178}. Radius must be greater than zero.

boxestableoptional

Array of {position = {x,y,z}, size = {x,y,z}, material = 0-178}. position is the centre and size is the full extent, not half-extents.

meshestableoptional

Array of {vertices = flat xyz triplets, indices = flat zero-based triangle triplets, material = 0-178}.

Returns

A col element, or false when no resource context exists or the collision could not be built.

Ownership and lifecycle

A generated col element behaves like any other MTA col element: it is parented to the calling resource, applied to models with engineReplaceCOL, and released when destroyed or when the resource stops. Rebuilding its data re-applies the new collision to every model it was already replaced into.

Important behavior
  • Passing anything other than a table falls through to the unchanged standard MTA behavior, so existing resources are unaffected.
  • The returned element is an ordinary col element. Apply it with engineReplaceCOL and destroy it as usual.
  • A malformed table raises a Lua error naming the exact path, such as spheres[2].radius must be finite.

Example

local col = engineLoadCOL({
    boxes = { { position = { 0, 0, 0 }, size = { 4, 0.4, 2.5 }, material = 1 } },
})
engineReplaceCOL(col, engineRequestModel("object", 980))

Where this comes from

SOURCECLuaRuntimeCollisionDefs.cppClient/mods/deathmatch/logic/luadefs/CLuaRuntimeCollisionDefs.cpp INTRODUCED / EXTENDEDaba2101e9Read the commit and why the change was made TEST RESOURCE runtime-collision-wall-demo test-resources/runtime-collision-wall-demo
RELATED NEON APIS

Continue exploring

Read the system guide →
engineSetCOLData Rebuilds an existing col element's collision from a Lua table and re-applies it to every model it already replaced. setPedEnterVehicle Extends MTA's authoritative vehicle-entry lifecycle with a verified native passenger-entry task after server confirmation. setPedExitVehicle Extends MTA's authoritative vehicle-exit lifecycle with a verified native leave-car task on the syncer.

← Back to the Neon Lua API · How Runtime collision generation works →