Skip to content
MTA:SA Neon Documentation

engineSetCOLData

Client-side
NEON APIRuntime collision generation

Available in Neon, not standard MTA

Rebuilds an existing col element's collision from a Lua table and re-applies it to every model it already replaced.

Syntax

bool engineSetCOLData(col theCol, table collision)

Arguments

theColcol

A col element, including one created by engineLoadCOL from a table.

collisiontable

Collision table of spheres, boxes and meshes.

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

true when the new collision was built and applied; false when the element has no loaded collision or the rebuild failed.

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
  • This is the reason to generate collision rather than ship a .col: the new shape lands immediately on objects that are already streamed in.
  • Rebuild only when the shape actually changes. Keep a signature of the current dimensions and skip identical frames when the shape is driven by held keys or continuous input.
  • The previous collision model is destroyed after the replacement succeeds.

Example

-- Make the same wall taller without creating a new element
engineSetCOLData(col, {
    boxes = { { position = { 0, 0, 0 }, size = { 4, 0.4, 3 }, material = 1 } },
})

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 →
engineLoadCOL Loads a collision model from a .col file as in standard MTA, or builds one from a Lua collision table. engineSetRadarMapTile Registers or replaces a resource-owned TXD in one cell of Neon's sparse 40 × 40 native radar grid. engineResetRadarMapTile Removes a radar tile owned by the calling resource and restores the native ocean fallback.

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