This documentation provides a reference for recognized plugin data types and built-in functions in the Particle System Plugin Lua Scripting API.

Functions listings display:

  • the name of the function
  • the parameter / argument list (if any), along with expected value types
  • the returned values (if any)
  • the raised warnings or errors (if any)

    • For parameter listings, a convention is used where some parameters are in square brackets: [param], this indicates that the argument is optional and not needed.

    If the parameter is followed by a value with equals sign: [param=value], this indicates the default value of the optional argument.

    More functions may be added with new releases and this documentation will be update accordingly.

    Plugin data types

    ColorRGB Data type representing a 24-bit (8-bit/8-bit/8-bit) RGB color.
    Vector3D Data type representing a 3D cartesian vector.
    RotVector Data type comprised of a set of XYZ euler angles for representing a rotation.
    ScaleVector Data type comprised of a set of XYZ scale values for representing a mesh scale.
    Module Data type representing a module context.
    NodeAttachment Data type representing the particle tethering settings of a particle group.
    ParticleGroup Data type representing particle groups in the Particle System Plugin.
    SpriteParticle Data type representing sprite particles in the Particle System Plugin.
    MeshParticle Data type representing mesh particles in the Particle System Plugin.
    ItemInfo Data type representing the moveable object infos exposed from the game.
    StaticInfo Data type representing the static object infos exposed from the game.

    Plugin interface functions

    checkPartLimit (group) Checks if the particle group's particle limit (if set) was reached yet.
    createColor (r, g, b) Creates a new ColorRGB object.
    createColorHSV (hue[, sat=1.0[, val=1.0]]) Creates a new ColorRGB object from Hue, Saturation and Value.
    createGroup (init, update) Creates a new ParticleGroup object with a given init and update function.
    createMeshPart (group) Creates a new MeshParticle object of given particle group.
    createModule () Creates a new Module context object in the module script.
    createPerlinNoise ([seed]) Creates a new PerlinNoise generator object.
    createSimplexNoise ([seed]) Creates a new SimplexNoise generator object.
    createSpritePart (group) Creates a new SpriteParticle object of given particle group.
    createVector (x, y, z) Creates a new Vector3D object
    invokeInit (group) Invokes the init function of specified particle group.
    killParts (group) Kills all currently active particles of the given particle group.
    print (value[, ...]) Outputs the listing of values to the plugin logger.
    require (module) Imports the requested module Lua script from modulescripts folder.
    setLogLevel (logLevel) Sets the Logging level (lowest permitted rank of Logger message).

    Randomizing functions

    randomFloat (min, max) Generates a random floating-point number value between [min, max].
    randomInt (min, max) Generates a random integer number value between [min, max].
    randomNegate (x) Returns the input x or its negative -x with a 50/50 chance.
    randomSpherePoint (radius) Generates a random vector (point) on a 3D sphere of a given radius, centered at origin.

    Procedural noise functions

    noise (gen, scale, x[, y[, z[, w]]]) Takes a noise generator object and produces a pseudo-random scalar noise output.
    noiseCurl (gen, scale, x, y[, z]) Takes a noise generator object and produces a pseudo-random curl vector.
    noiseCurlTime (gen, scale, time, x, y[, z]) Takes a noise generator object and produces a pseudo-random curl vector that changes over time.

    Particle functions

    partAbsPos (part) Calculates the absolute position of the particle in world coordinates instead of relative coordinates.
    partAnimate (part, start, end[, frameRate=1]) Animates the particle by cycling over part.spriteIndex (SpriteParticle) or part.meshIndex (meshParticle).
    partAttach (part, index[, mesh=-1]) Manually tethers the particle to a certain moveable and mesh (sets the part.emitterIndex and part.emitterNode).
    partAttractToItem (part, index, radius, strength) Attracts the particle towards a specified moveable.
    partAvoidRoomGeometry (part, wallMargin, floorMargin, strength) Makes the particle repel from room geometry (walls, floors and ceilings).
    partCollidedItem (part, index, radius) Tests if the particle collided with a specified moveable item.
    partCollideFloors (part, rebound[, margin=0.0[, accurate=false]]) Tests if the particle collided with a floor or ceiling.
    partCollideWalls (part, rebound) Tests if the particle collided with a wall.
    partDetach (part) Manually detaches the particle to from its tethering moveable and mesh (resets the part.emitterIndex and part.emitterNode to default).
    partFollow (part, target, maxSpeed, outerDist, minDist) Makes the particle follow a Vector3D target, while maintaining a minimum spherical distance away from the target.
    partHoming (part, targetIndex, targetMesh, turnSpeed[, accel=0.0[, predict=false]]) Makes the particle home onto a moveable target (similarly to a projectile).
    partKill (part) Immediately kills (and deactivates) the particle instance.
    partLimitSpeed (part, maxSpeed) Limits the maximum speed at which the particle can travel.
    partWind (part, strength) Applies in-game wind speed cumulatively to particle's velocity.
    meshShatter (part) Like partKill, but shatters the mesh of the mesh particle upon killing the instance.

    Game interactions

    activateTriggers (x, y, z, room[, heavy=false[, flags]]) Activates in-level triggers of the sector at coordinates (x, y, z, room).
    findNearestItem (pos, radius[, slots]) Finds the closest moveable item to a position within a given radius, from an (optional) list of slots.
    getCeilingHeight (x, y, z, room) Calculates the in-level ceiling height at coordinates (x, y, z, room).
    getFloorHeight (x, y, z, room) Calculates the in-level floor height at coordinates (x, y, z, room).
    getFloorNormal (x, y, z, room) Calculates the unit normal vector of the floor surface at coordinates (x, y, z, room).
    getGameTick () Gets the current game tick value.
    getItemInfo (index) Gets the ItemInfo object of the given moveable index.
    getItemJointPosition (index, mesh, xOffset, yOffset, zOffset) Gets the joint position of a specified mesh of a moveable.
    getItemJointRotation (index, mesh) Gets the joint rotation of a specified mesh of a moveable.
    getItemJointPosRot (index, mesh, xOffset, yOffset, zOffset) Fused function that combines getItemJointPosition and getItemJointRotation.
    getItemRoom (index) Gets the current room index of the given moveable.
    getItemsBySlot (slot) Retrieves a table of moveable indices belonging to a specific slot in current level.
    getLaraIndex () Gets Lara's moveable index.
    getLaraTargetIndex () Gets the index of enemy currently aimed at by Lara.
    getRoomFlags (room) Gets the special room flags (properties) of a given room.
    getRoomIndex (mapID) Converts the levelmap room ID to the proper tomb4 room index.
    getRoomStatics (room[, slots]) Retrieves a table of StaticInfo objects placed in a given room.
    getStatic (staticID) Gets the StaticInfo object of a given NG static ID.
    getTombIndex (ngID) Converts the NG script ID of a moveable to the proper tomb4 item index.
    getWaterDepth (x, y, z, room) Calculates the water depth at coordinates (x, y, z, room).
    getWaterHeight (x, y, z, room) Calculates the water surface height at coordinates (x, y, z, room).
    laraBurn () Sets Lara on fire.
    soundEffect (sfx[, pos=nil[, flags]]) Plays a specified sound effect.
    testCollisionSpheres (index, pos, radius) An advanced function for testing collision of a sphere against the mesh spheres of a moveable.
    testWall (x, y, z, room) Tests if there is a wall at coordinates (x, y, z, room)
    triggerDynamicLight (x, y, z, intensity, red, green, blue) Triggers a dynamic light at the given (x, y, z) coordinates for one game tick.
    triggerShockwave (x, y, z, innerRad, outerRad, speed, life, red, green, blue, xRot, flags) Triggers a shockwave effect at the given (x, y, z) coordinates.

    TRNG interactions

    getSelectedItem () Gets the tomb4 moveable index of the current Selected Item.
    performTriggerGroup (id) Executes a TriggerGroup from the current level.
    setSelectedItem (index) Sets the tomb4 moveable index as the current Selected Item / Found Item index.

    Math-related functions

    abs (x) Calculates the absolute value of x.
    acos (x) Calculates the inverse-cosine of x.
    asin (x) Calculates the inverse-sine of x.
    atan (x) Calculates the inverse-tangent of x.
    atan2 (y, x) Calculates the two-component (y, x) inverse-tangent.
    cbrt (x) Calculates the cubic root of x (∛x).
    ceil (x) Calculates the ceiling of x (⌈x⌉).
    clamp (x, min, max) Clamps the value of x to the range [min, max].
    cos (x) Calculates the cosine of x.
    degToRad (x) Converts value expressed in degrees to value expressed in radians.
    distance (vec1, vec2) Calculates the Euclidean (shortest) distance between two Vector3D objects.
    distCompare (vec1, vec2, dist) Compares the Euclidean (shortest) distance between two Vector3D objects against a given distance threshold.
    exp (x) Calculates the exponential of x (ex).
    floor (x) Calculates the floor of x (⌊x⌋).
    fmod (x, y) Calculates the floating point remainder of x / y.
    lerp (a, b, t) Linearly interpolates between the values [a, b] based on factor t.
    lerpInverse (a, b, x) Calculates the linear interpolating factor t based on the value of x between the values [a, b].
    log (x) Calculates the natural logarithm of x (for positive x values).
    radToDeg (x) Converts value expressed in radians to value expressed in degrees.
    remap (x, oldMin, oldMax, newMin, newMax) Linearly remaps the value x from the original range [oldMin, oldMax] to the new range [newMin, newMax].
    rotateVectorByAngles (vec, x, y, z) Rotates a Vector3D object by a set of Euler angles (x, y, z).
    rotateVectorByAxisAngle (vec, axis, theta) Rotates a Vector3D object by an axis vector and angle theta.
    rotFromVector (vec) Creates a RotVector object from a direction vector.
    round (x) Rounds the floating-point number x to the nearest integer.
    sin (x) Calculates the sine of x.
    smoothStep (x) Calculates the SmoothStep of x (3x2 - 2x3; 0 ≤ x ≤ 1)
    sphericalToCartesian (r, theta, phi) Converts a set of spherical coordinates (r, θ, φ) to cartesian coordinates (x, y, z).
    sqrt (x) Calculates the square root of x (√x, for non-negative x values).
    tan (x) Calculates the tangent of x.
    vectorCross (u, v) Calculates the vector cross product between the vectors u and v (u ⨯ v).
    vectorDot (u, v) Calculates the vector dot product between the vectors u and v (u ⋅ v).
    vectorLength (v) Calculates the length of vector v (|v|).
    vectorNormalize (v) Calculates the normalized (unit) vector from vector v (v/|v|).
    wrapAngle (x) Wraps the angle x to the range [-π, π].

    Miscellaneous functions

    hasAllFlags (checkedValue, testFlags) Tests for the occurence of all specified flags in a given integer value.
    hasAnyFlag (checkedValue, testFlags) Tests for the occurence of any specified flags in a given integer value.
    interval (interval[, delay=0]) Tests for the occurence of a specific game tick interval.


    Plugin data types

    ColorRGB
    Data type representing a 24-bit (8-bit/8-bit/8-bit) RGB color.

    Fields:

    • r number the Red color component [0, 255] (default 0)
    • g number the Green color component [0, 255] (default 0)
    • b number the Blue color component [0, 255] (default 0)
    Vector3D
    Data type representing a 3D cartesian vector.

    Fields:

    • x number the X coordinate (default 0.0)
    • y number the Y coordinate (default 0.0)
    • z number the Z coordinate (default 0.0)
    RotVector
    Data type comprised of a set of XYZ euler angles for representing a rotation.

    Fields:

    • x number the X angle (radians) [0, 2π] (default 0.0)
    • y number the Y angle (radians) [0, 2π] (default 0.0)
    • z number the Z angle (radians) [0, 2π] (default 0.0)
    ScaleVector
    Data type comprised of a set of XYZ scale values for representing a mesh scale.

    Fields:

    • x number the X scale (default 1.0)
    • y number the Y scale (default 1.0)
    • z number the Z scale (default 1.0)
    Module
    Data type representing a module context object. Created through createModule function. Only one such object may exist per module file and is returned when importing a module with require.

    Fields:

    • groups table the particle groups table of the module (only ParticleGroup values accepted)
    • params table the parameters table of the module (bool, int, number or string values accepted)
    • save table the savegame table of the module (bool, int, number or nil values accepted)
    NodeAttachment
    Data type representing the particle tethering settings of a particle group.

    Fields:

    • cutoff int the duration for the tethering (default 0; set NO_CUTOFF for indefinite tethering)
    • random int the randomization for the cutoff duration (default 0)
    • tetherType int the tethering type assigned for the group (default TETHER_ROTATING)
    ParticleGroup
    Data type representing particle groups in the Particle System Plugin.

    Fields:

    • attach NodeAttachment the particle tethering settings for the group
    • autoTrigger bool the auto-triggering setting for the group init function (default true)
    • blendMode int the blending mode of the group (sprite particles only) (default BLEND_COLORADD)
    • drawMode int the drawing mode of the group (sprite particles only) (default DRAW_SPRITE)
    • ignorePerspective bool setting to ignore perspective (depth) when drawing sprite particles (default false)
    • immortal bool the immortality setting of the group particles (default false)
    • lightMode int the lighting mode of the group (sprite particles only) (default LIGHT_STATIC)
    • partCount int the current count of active particles for the group (read-only)
    • partLimit int the particle limit setting for the group (default 0; i.e. no limit)
    • saved bool the setting for savegame persistence of the group particles (default false)
    • screenSpace bool the screen-space setting of the group (default false)
    • spriteSlot int the sprite texture slot used by sprite particles (default SLOT_DEFAULT_SPRITES)
    SpriteParticle
    Data type representing sprite particles in the Particle System Plugin.

    Fields:

    • accel Vector3D the acceleration vector
    • data table the extra data table of the particle (bool, int, number or nil values accepted)
    • emitterIndex int the tomb4 emitter item index (default -1)
    • emitterNode int the mesh index of the emitting node; set only after setting emitterIndex (default -1)
    • lifeCounter int the life counter, counting down the life span of the particle [0, 32767] (default 0)
    • lifeSpan int the life span of the particle [0, 32767] (default 0)
    • pos Vector3D the position vector
    • roomIndex int the tomb4 room index of the particle; necessary if the particle uses collision functions (default 0)
    • t number the t-parameter value [0.0, 1.0] (read-only)
    • vel Vector3D the velocity vector

    • spriteIndex int the sprite texture index for particle appearance (default 0)
    • colCust ColorRGB the current color of particle
    • colStart ColorRGB the starting color of particle
    • colEnd ColorRGB the ending color of particle
    • fadeIn int the fade-in duration of the particle [0, 32767] (default 0)
    • fadeOut int the fade-out duration of the particle [0, 32767] (default 0)
    • rot number the billboard rotation of the particle (radians, default 0.0)
    • rotVel number the billboard angular velocity of the particle (radians, default 0.0)
    • rot3D RotVector the 3D sprite rotation of the particle
    • rotVel3D RotVector the 3D sprite angular velocity of the particle
    • sizeCust int the current size of the particle [0, 65535]
    • sizeStart int the starting size of the particle [0, 65535]
    • sizeEnd int the ending size of the particle [0, 65535]
    • sizeRatio number the width/height ratio of the particle [-1.0, 1.0]
    MeshParticle
    Data type representing mesh particles in the Particle System Plugin.

    Fields:

    • accel Vector3D the acceleration vector
    • data table the extra data table of the particle (bool, int, number or nil values accepted)
    • emitterIndex int the tomb4 emitter item index (default -1)
    • emitterNode int the mesh index of the emitting node; set only after setting emitterIndex (default -1)
    • lifeCounter int the life counter, counting down the life span of the particle [0, 32767] (default 0)
    • lifeSpan int the life span of the particle [0, 32767] (default 0)
    • pos Vector3D the position vector
    • roomIndex int the tomb4 room index of the particle; necessary if the particle uses collision functions (default 0)
    • t number the t-parameter value [0.0, 1.0] (read-only)
    • vel Vector3D the velocity vector

    • object int the moveable object slot to which meshIndex refers to
    • meshIndex int the index of mesh to take for the mesh particle appearance
    • rot RotVector the 3D mesh rotation
    • rotVel RotVector the 3D mesh angular velocity
    • scale ScaleVector the XYZ scale of the mesh
    • transparency int the alpha transparency of the mesh
    • tint ColorRGB the tint of the mesh (if statically-lit)
    ItemInfo
    Data type representing the moveable object infos exposed from the game. Can be obtained with getItemInfo.

    Fields:

    • animNumber int the current animation number of the item
    • frameNumber int the frame number relative to current animNumber
    • currentAnimState int the current anim state number of the item
    • goalAnimState int the goal anim state number of the item
    • speed int the horizontal speed of the item
    • fallSpeed int the vertical speed of the item
    • floorDistance int the distance to the floor (read-only, only used for certain slots)
    • hitPoints int the hit points (health) of the item
    • itemFlag1 int a numeric field used for various purposes in certain slots
    • itemFlag2 int a numeric field used for various purposes in certain slots
    • itemFlag3 int a numeric field used for various purposes in certain slots
    • itemFlag4 int a numeric field used for various purposes in certain slots
    • meshBits int the visibility bit-flags of meshes in the item (read-only)
    • meshes int the count of meshes in the item's moveable slot (read-only)
    • ocbNumber int the OCB number set for the item
    • pos Vector3D the XYZ coordinates of the item
    • roomIndex int the tomb4 room index of the item (read-only)
    • rot RotVector the XYZ rotation angles of the item
    • slot int the moveable slot number of the item (read-only)
    • tombIndex int the tomb4 moveable index of the item (read-only)
    • triggered bool activation / triggering status of the item (read-only)
      • true if item is triggered or active
      • false if item is untriggered, dead or inactive
    StaticInfo
    Data type representing the static object infos exposed from the game. Single StaticInfo is returned by getStatic, while getRoomStatics returns a table of StaticInfo.

    Fields:

    • ocbFlags int the OCB / flags of the static (read-only)
    • pos Vector3D the XYZ coordinates of the static (read-only)
    • rot RotVector rotation of the static (only Y rotation, read-only)
    • slot int the static slot number of the static (read-only)
    • tint ColorRGB the color-tint of the static (read-only)

    Plugin interface functions

    checkPartLimit (group)
    Checks if the particle group's particle limit (if set) was reached yet. Used when managing particle effects with limited spawn counts.

    Parameters:

    Returns:

      bool true if limit not reached yet (or group.partLimit not set for group); false if limit reached
    createColor (r, g, b)
    Creates a new ColorRGB object.

    Parameters:

    • r int the Red value [0, 255]
    • g int the Green value [0, 255]
    • b int the Blue value [0, 255]

    Returns:

      ColorRGB the ColorRGB object
    createColorHSV (hue[, sat=1.0[, val=1.0]])
    Creates a new ColorRGB object from Hue, Saturation and Value.

    Parameters:

    • hue number the Hue value [0.0, 360.0]
    • sat number the Saturation value [0.0, 1.0] (default 1.0)
    • val number the Value (intensity) value [0.0, 1.0] (default 1.0)

    Returns:

      ColorRGB the ColorRGB object
    createGroup (init, update)
    Creates a new ParticleGroup object with a given init and update function. Can only be called in the module-loading phase.

    Parameters:

    • init optional func the initialization function; pass nil if no init function desired
    • update optional func the update function; pass nil if no update function desired

    Returns:

      ParticleGroup the ParticleGroup object
    createMeshPart (group)
    Creates a new MeshParticle object of given particle group. Can only be called in the init phase or update phase.

    Parameters:

    Returns:

      optional MeshParticle the MeshParticle object; nil if particle Limit reached

    Raises:

    [WARN] if group.partLimit was set and limit was exceeded
    createModule ()
    Creates a new Module context object in the module script. Can only be called in the module-loading phase. Only one Module context can exist in a single module file.

    Returns:

      Module the Module context object

    Raises:

    [ERROR] if Module object was already created
    createPerlinNoise ([seed])
    Creates a new PerlinNoise generator object. Can only be called in the module-loading phase.

    Parameters:

    • seed int the seed to initialize the noise generator with (optional)

    Returns:

      PerlinNoise the PerlinNoise generator object

    See also:

    createSimplexNoise ([seed])
    Creates a new SimplexNoise generator object. Can only be called in the module-loading phase.

    Parameters:

    • seed int the seed to initialize the noise generator with (optional)

    Returns:

      SimplexNoise the SimplexNoise generator object

    See also:

    createSpritePart (group)
    Creates a new SpriteParticle object of given particle group. Can only be called in the init phase or update phase.

    Parameters:

    Returns:

      optional SpriteParticle the SpriteParticle object; nil if particle Limit reached

    Raises:

    [WARN] if group.partLimit was set and limit was exceeded
    createVector (x, y, z)
    Creates a new Vector3D object

    Parameters:

    • x number the vector's X component
    • y number the vector's Y component
    • z number the vector's Z component

    Returns:

      Vector3D the Vector3D object
    invokeInit (group)
    Invokes the init function of specified particle group. Can only be used for groups with auto-triggering set to false.

    Parameters:

    • group ParticleGroup the group of which to manually invoke (call) the init function

    Raises:

    [ERROR] if the group.autoTrigger is set to true
    killParts (group)
    Kills all currently active particles of the given particle group.

    Parameters:

    • group ParticleGroup the group of which to kill (clear) all active particles
    print (value[, ...])
    Outputs the listing of values to the plugin logger. Will appear as a message with [DEBUG] tag.

    Parameters:

    • value bool, number or string
    • ... additional values (optional)
    require (module)
    Imports the requested module Lua script from modulescripts folder. Can only be called in the level-loading phase (i.e. inside a level script). The modulescripts folder should be present in the working directory of the TRLE project.

    Parameters:

    • module string the name of the module file to import (e.g. snow.lua → "snow")

    Returns:

      optional Module the module context object associated with the module script (if not present, returns nil).

    Raises:

    [ERROR] if the requested module is not found in the modulescripts folder (or the folder is missing).
    setLogLevel (logLevel)
    Sets the Logging level (lowest permitted rank of Logger message). Can only be called in the level-loading phase (i.e. inside a level script).

    Parameters:

    • logLevel int the desired LOG_ constant to set

    Randomizing functions

    randomFloat (min, max)
    Generates a random floating-point number value between [min, max].

    Parameters:

    • min number the lower bound of the range
    • max number the upper bound of the range

    Returns:

      number the random float number between [min, max]
    randomInt (min, max)
    Generates a random integer number value between [min, max].

    Parameters:

    • min int the lower bound of the range
    • max int the upper bound of the range (inclusive)

    Returns:

      int the random integer between [min, max]
    randomNegate (x)
    Returns the input x or its negative -x with a 50/50 chance.

    Parameters:

    • x number the input number

    Returns:

      number the randomly negated output
    randomSpherePoint (radius)
    Generates a random vector (point) on a 3D sphere of a given radius, centered at origin.

    Parameters:

    • radius number the sphere's radius

    Returns:

      Vector3D the random vector from origin point (0, 0, 0)

    Procedural noise functions

    noise (gen, scale, x[, y[, z[, w]]])
    Takes a noise generator object and produces a pseudo-random scalar noise output. Noise values can be generated from up to 4 separate numerical inputs (x, y, z, w).

    Parameters:

    • gen PerlinNoise or SimplexNoise the noise generator object
    • scale number the domain scale factor (larger means smaller oscillation frequency)
    • x number the first input
    • y number the second input (optional)
    • z number the third input (optional)
    • w number the fourth input (optional)

    Returns:

      number scalar noise value in the approximate range [-1.0, 1.0]
    noiseCurl (gen, scale, x, y[, z])
    Takes a noise generator object and produces a pseudo-random curl vector. Useful for simulating fluid-like dynamics. Noise values can be generated from 2 up to 3 separate numerical inputs (x, y, z), generating a curl vector.

    Parameters:

    • gen PerlinNoise or SimplexNoise the noise generator object
    • scale number the domain scale factor (larger means smaller oscillation frequency)
    • x number the first input
    • y number the second input
    • z number the third input (optional)

    Returns:

      Vector3D curl vector; if only x, y inputs are given, generates a vector with zero Z component (x, y, 0.0), otherwise generates a full 3D vector (x, y, z)
    noiseCurlTime (gen, scale, time, x, y[, z])
    Takes a noise generator object and produces a pseudo-random curl vector that changes over time. Useful for simulating fluid-like dynamics. Noise values can be generated from 2 up to 3 separate numerical inputs (x, y, z), generating a curl vector.

    Parameters:

    • gen PerlinNoise or SimplexNoise the noise generator object
    • scale number the domain scale factor (larger means smaller oscillation frequency)
    • time number the time component (e.g. derived from getGameTick())
    • x number the first input
    • y number the second input
    • z number the third input (optional)

    Returns:

      Vector3D curl vector; if only x, y inputs are given, generates a vector with zero Z component (x, y, 0.0), otherwise generates a full 3D vector (x, y, z)

    Particle functions

    partAbsPos (part)
    Calculates the absolute position of the particle in world coordinates instead of relative coordinates. If the particle is not tethered to any moveable, returns vector identical to part.pos.

    Parameters:

    Returns:

      Vector3D the absolute position of the particle
    partAnimate (part, start, end[, frameRate=1])
    Animates the particle by cycling over part.spriteIndex (SpriteParticle) or part.meshIndex (meshParticle).

    Parameters:

    • part SpriteParticle or MeshParticle the particle instance
    • start int the start of the animation range
    • end int the end of the animation range
    • frameRate int the framerate; if positive it means the number of ticks for the animation "frame", if negative, it means the number of animation cycles (loops) to complete (default 1)
    partAttach (part, index[, mesh=-1])
    Manually tethers the particle to a certain moveable and mesh (sets the part.emitterIndex and part.emitterNode).

    Parameters:

    • part SpriteParticle or MeshParticle the particle instance
    • index int the tomb4 item index to attach to
    • mesh int the mesh to attach to (default -1)

    Raises:

    [ERROR] if moveable with given index is not found
    partAttractToItem (part, index, radius, strength)
    Attracts the particle towards a specified moveable. Not applicable to screen-space particles or tethered particles.

    Parameters:

    • part SpriteParticle or MeshParticle the particle instance
    • index int the tomb4 item index
    • radius number the radius around the moveable where the attraction effect occurs
    • strength number the strength of the attraction (negative for repulsion)

    Raises:

    [ERROR] if moveable with given index is not found
    partAvoidRoomGeometry (part, wallMargin, floorMargin, strength)
    Makes the particle repel from room geometry (walls, floors and ceilings). Not applicable to screen-space particles or tethered particles.

    Parameters:

    • part SpriteParticle or MeshParticle the particle instance
    • wallMargin int the margin from which to repel from walls
    • floorMargin int the margin from which to repel from floors (and ceilings)
    • strength number the strength of the repulsion (positive for attraction)
    partCollidedItem (part, index, radius)
    Tests if the particle collided with a specified moveable item. This is a simple, fast collision check against the item's bounding box, sufficient for most purposes. See testCollisionSpheres for a more sophisticated collision detection. Not applicable to screen-space particles.

    Parameters:

    • part SpriteParticle or MeshParticle the particle instance
    • index int the tomb4 item index
    • radius number the spherical radius around the particle test with bounding box

    Returns:

      bool true if collision with moveable occured; false otherwise

    Raises:

    [ERROR] if moveable with given index is not found
    partCollideFloors (part, rebound[, margin=0.0[, accurate=false]])
    Tests if the particle collided with a floor or ceiling. If a collision occured, will bounce the particle off the surface. Not applicable to screen-space particles or tethered particles.

    Parameters:

    • part SpriteParticle or MeshParticle the particle instance
    • rebound number the rebound factor (bounciness) [0.0, 1.0]
    • margin number the margin of collision, or the 'radius' of the particle (default 0.0)
    • accurate bool controls if the collision is geometrically correct, respecting slopes (default false)

    Returns:

      bool true if collision with surface occured (and particle is reflected); false otherwise
    partCollideWalls (part, rebound)
    Tests if the particle collided with a wall. If a collision occured, will bounce the particle off the wall (reflect the velocity). Not applicable to screen-space particles or tethered particles.

    Parameters:

    Returns:

      bool true if collision with wall occured (and particle is reflected); false otherwise
    partDetach (part)
    Manually detaches the particle to from its tethering moveable and mesh (resets the part.emitterIndex and part.emitterNode to default).

    Parameters:

    partFollow (part, target, maxSpeed, outerDist, minDist)
    Makes the particle follow a Vector3D target, while maintaining a minimum spherical distance away from the target. Not applicable to screen-space particles or tethered particles.

    Parameters:

    • part SpriteParticle or MeshParticle the particle instance
    • target Vector3D the target position to follow
    • maxSpeed number the maximum speed with which the particle will follow the target
    • outerDist number the first distance threshold (where particle starts to slow)
    • minDist number the minimum distance which the particle will not cross (by itself)
    partHoming (part, targetIndex, targetMesh, turnSpeed[, accel=0.0[, predict=false]])
    Makes the particle home onto a moveable target (similarly to a projectile). Not applicable to screen-space particles or tethered particles.

    Parameters:

    • part SpriteParticle or MeshParticle the particle instance
    • targetIndex int the tomb4 item index of the target moveable
    • targetMesh optional int the targeted mesh or nil (no mesh)
    • turnSpeed number the turning speed of particle [0.0, 1.0]
    • accel number the speed up of particle per tick (default 0.0)
    • predict bool if set to true, predicts the position of moving targets (default false)

    Raises:

    [ERROR] if moveable with given index is not found
    partKill (part)
    Immediately kills (and deactivates) the particle instance. Use this function instead of manually setting part.lifeCounter to 0.

    Parameters:

    partLimitSpeed (part, maxSpeed)
    Limits the maximum speed at which the particle can travel. Useful to prevents excessive speeds (e.g. when velocity is accumulated via acceleration or otherwise).

    Parameters:

    partWind (part, strength)
    Applies in-game wind speed cumulatively to particle's velocity. Only works in outside rooms, where wind is active. Not applicable to screen-space particles or tethered particles.

    Parameters:

    • part SpriteParticle or MeshParticle the particle instance
    • strength number the influence the wind has over the particle [0.0, 1.0]
    meshShatter (part)
    Like partKill, but shatters the mesh of the mesh particle upon killing the instance.

    Parameters:

    Raises:

    [ERROR] if part is a SpriteParticle

    Game interactions

    activateTriggers (x, y, z, room[, heavy=false[, flags]])
    Activates in-level triggers of the sector at coordinates (x, y, z, room).

    Parameters:

    • x int the X coordinate
    • y int the Y coordinate
    • z int the Z coordinate
    • room int the 'room' coordinate (tomb4 room index)
    • heavy bool activate heavy triggers (default false)
    • flags int use trigger flags (optional)
    findNearestItem (pos, radius[, slots])
    Finds the closest moveable item to a position within a given radius, from an (optional) list of slots.

    Parameters:

    • pos Vector3D the position to start searching from
    • radius number the maximum search radius (in units) away from pos
    • slots {int,...} table of slot indices / SLOT_ constants (optional)

    Returns:

      optional int tomb4 index of nearest moveable item matching criteria; nil if no item found
    getCeilingHeight (x, y, z, room)
    Calculates the in-level ceiling height at coordinates (x, y, z, room).

    Parameters:

    • x int the X coordinate
    • y int the Y coordinate
    • z int the Z coordinate
    • room int the 'room' coordinate (tomb4 room index)

    Returns:

      optional int the ceiling height at the given coordinates; nil if sector is a wall
    getFloorHeight (x, y, z, room)
    Calculates the in-level floor height at coordinates (x, y, z, room).

    Parameters:

    • x int the X coordinate
    • y int the Y coordinate
    • z int the Z coordinate
    • room int the 'room' coordinate (tomb4 room index)

    Returns:

      optional int the floor height at the given coordinates; nil if sector is a wall
    getFloorNormal (x, y, z, room)
    Calculates the unit normal vector of the floor surface at coordinates (x, y, z, room).

    Parameters:

    • x int the X coordinate
    • y int the Y coordinate
    • z int the Z coordinate
    • room int the 'room' coordinate (tomb4 room index)

    Returns:

      optional Vector3D the normal vector at the given coordinates; nil if sector is a wall
    getGameTick ()
    Gets the current game tick value. 30 ticks = 1 second.

    Returns:

      int the game tick value
    getItemInfo (index)
    Gets the ItemInfo object of the given moveable index.

    Parameters:

    • index int the tomb4 item index

    Returns:

      ItemInfo the associated ItemInfo object

    Raises:

    [ERROR] if moveable with given index is not found
    getItemJointPosition (index, mesh, xOffset, yOffset, zOffset)
    Gets the joint position of a specified mesh of a moveable.

    Parameters:

    • index int the tomb4 item index
    • mesh int the mesh/joint index
    • xOffset optional int the X positional offset
    • yOffset optional int the Y positional offset
    • zOffset optional int the Z positional offset

    Returns:

      Vector3D the position vector of the joint

    Raises:

    [ERROR] if moveable with given index is not found
    getItemJointRotation (index, mesh)
    Gets the joint rotation of a specified mesh of a moveable.

    Parameters:

    • index int the tomb4 item index
    • mesh int the mesh/joint index

    Returns:

      RotVector the rotation vector of the joint

    Raises:

    [ERROR] if moveable with given index is not found
    getItemJointPosRot (index, mesh, xOffset, yOffset, zOffset)
    Fused function that combines getItemJointPosition and getItemJointRotation. Slightly faster than calling these separate functions individually. Returns the position and rotation (two values).

    Parameters:

    • index int the tomb4 item index
    • mesh int the mesh/joint index
    • xOffset optional int the X positional offset
    • yOffset optional int the Y positional offset
    • zOffset optional int the Z positional offset

    Returns:

    1. Vector3D the position vector of the joint
    2. RotVector the rotation vector of the joint

    Raises:

    [ERROR] if moveable with given index is not found
    getItemRoom (index)
    Gets the current room index of the given moveable.

    Parameters:

    • index int the tomb4 item index

    Returns:

      int the moveable's room index

    Raises:

    [ERROR] if moveable with given index is not found
    getItemsBySlot (slot)
    Retrieves a table of moveable indices belonging to a specific slot in current level.

    Parameters:

    • slot int the slot index / SLOT_ constant

    Returns:

      {int,...} table of tomb4 moveable indices
    getLaraIndex ()
    Gets Lara's moveable index.

    Returns:

      int tomb4 index of Lara
    getLaraTargetIndex ()
    Gets the index of enemy currently aimed at by Lara. Only works with Aiming settings set to 'Automatic'.

    Returns:

      optional int tomb4 index of aimed enemy; nil if no enemy is targeted
    getRoomFlags (room)
    Gets the special room flags (properties) of a given room.

    Parameters:

    • room int the tomb4 room index

    Returns:

      int bit-flags of the room properties (flags can be tested with hasAllFlags or hasAnyFlag)
    getRoomIndex (mapID)
    Converts the levelmap room ID to the proper tomb4 room index. Use this function to convert editor room IDs when a tomb4 room index is expected.

    Parameters:

    • mapID int the levelmap room ID

    Returns:

      int tomb4 room index of room
    getRoomStatics (room[, slots])
    Retrieves a table of StaticInfo objects placed in a given room. An optional table of specific static slots can be provided, otherwise all statics will be gathered.

    Parameters:

    • room int the tomb4 room index
    • slots {int,...} table of static slots / SLOT_constants (optional)

    Returns:

      {StaticInfo,...} table of StaticInfo objects
    getStatic (staticID)
    Gets the StaticInfo object of a given NG static ID.

    Parameters:

    • staticID int the NG static ID

    Returns:

      StaticInfo the associated StaticInfo object

    Raises:

    [ERROR] if static with given NG ID is not found
    getTombIndex (ngID)
    Converts the NG script ID of a moveable to the proper tomb4 item index. Use this function to convert editor moveable IDs when a tomb4 item index is expected.

    Parameters:

    • ngID int the levelmap moveable ID

    Returns:

      int the tomb4 item index

    Raises:

    [ERROR] if moveable with given NG ID is not found
    getWaterDepth (x, y, z, room)
    Calculates the water depth at coordinates (x, y, z, room).

    Parameters:

    • x int the X coordinate
    • y int the Y coordinate
    • z int the Z coordinate
    • room int the 'room' coordinate (tomb4 room index)

    Returns:

      optional int the water depth at the given coordinates; nil if sector is a wall
    getWaterHeight (x, y, z, room)
    Calculates the water surface height at coordinates (x, y, z, room).

    Parameters:

    • x int the X coordinate
    • y int the Y coordinate
    • z int the Z coordinate
    • room int the 'room' coordinate (tomb4 room index)

    Returns:

      optional int the water surface height at the given coordinates; nil if no water room or sector is a wall
    laraBurn ()
    Sets Lara on fire.
    soundEffect (sfx[, pos=nil[, flags]])
    Plays a specified sound effect. If nil is passed for pos, plays the sound globally.

    Parameters:

    • sfx int sound effect ID number
    • pos Vector3D the coordinates for the sound location or nil (default nil)
    • flags int the flags for the sound effect (optional)
    testCollisionSpheres (index, pos, radius)
    An advanced function for testing collision of a sphere against the mesh spheres of a moveable. This function is more complex to use. See partCollidedItem for a simpler particle collision function.

    Parameters:

    • index int the tomb4 item index
    • pos Vector3D the position of the testing sphere
    • radius number the radius of the testing sphere

    Returns:

      int bit-flags of meshes with which the testing sphere has detected a collision (test with hasAllFlags or hasAnyFlag)

    Raises:

    [ERROR] if moveable with given index is not found
    testWall (x, y, z, room)
    Tests if there is a wall at coordinates (x, y, z, room)

    Parameters:

    • x int the X coordinate
    • y int the Y coordinate
    • z int the Z coordinate
    • room int the 'room' coordinate (tomb4 room index)

    Returns:

      bool true if there is a wall/block, false if there is free space (no wall)
    triggerDynamicLight (x, y, z, intensity, red, green, blue)
    Triggers a dynamic light at the given (x, y, z) coordinates for one game tick. Needs continuous calling to produce a longer-lasting light effect. Contributes to dynamic light limits.

    Parameters:

    • x int the X coordinate
    • y int the Y coordinate
    • z int the Z coordinate
    • intensity int the intensity / strength of light
    • red int the Red value [0, 255]
    • green int the Green value [0, 255]
    • blue int the Blue value [0, 255]
    triggerShockwave (x, y, z, innerRad, outerRad, speed, life, red, green, blue, xRot, flags)
    Triggers a shockwave effect at the given (x, y, z) coordinates.

    Parameters:

    • x int the X coordinate
    • y int the Y coordinate
    • z int the Z coordinate
    • innerRad int the inner ring radius
    • outerRad int the outer ring radius
    • speed int the ring scaling speed (can be negative)
    • life int the duration of the effect (ticks)
    • red int the Red value [0, 255]
    • green int the Green value [0, 255]
    • blue int the Blue value [0, 255]
    • xRot number the X rotation of the effect (radians)
    • flags int the special shockwave flags (e.g. damage)

    TRNG interactions

    getSelectedItem ()
    Gets the tomb4 moveable index of the current Selected Item. Can be used to apply Lua effects to moveables obtained with some TRNG feature (e.g. set by TRNG Action 54).

    Returns:

      int the tomb4 moveable index of Selected Item
    performTriggerGroup (id)
    Executes a TriggerGroup from the current level. If the TriggerGroup has any Condition triggers, it will return the boolean result of the conditions (all condition must pass for the final result to be true).

    Parameters:

    • id int the TriggerGroup ID number [1, 9999]

    Returns:

      bool the execution status of the TG (always true if no Condition triggers)
    setSelectedItem (index)
    Sets the tomb4 moveable index as the current Selected Item / Found Item index. Can be used to apply TRNG features to moveables obtained through Lua scripts (e.g. by redirecting with TGROUP_USE_FOUND_ITEM_INDEX in a TriggerGroup executed with performTriggerGroup).

    Parameters:

    • index int the tomb4 moveable index

    Raises:

    [ERROR] if moveable with given index is not found

    Math-related functions

    abs (x)
    Calculates the absolute value of x.

    Parameters:

    • x number the input number

    Returns:

      number the absolute value of x
    acos (x)
    Calculates the inverse-cosine of x.

    Parameters:

    • x number the input cosine value; must be in the range [-1.0, 1.0]

    Returns:

      number the angle (radians) for given cosine value

    Raises:

    [ERROR] undefined (NaN) for x outside of [-1.0, 1.0]
    asin (x)
    Calculates the inverse-sine of x.

    Parameters:

    • x number the input sine value; must be in the range [-1.0, 1.0]

    Returns:

      number the angle (radians) for given sine value

    Raises:

    [ERROR] undefined (NaN) for x outside of [-1.0, 1.0]
    atan (x)
    Calculates the inverse-tangent of x.

    Parameters:

    • x number the input tangent value;

    Returns:

      number the angle (radians) for given tangent value
    atan2 (y, x)
    Calculates the two-component (y, x) inverse-tangent.

    Parameters:

    • y number the y component
    • x number the x component

    Returns:

      number the angle (radians) for given (y, x) components
    cbrt (x)
    Calculates the cubic root of x (∛x).

    Parameters:

    • x number the input x

    Returns:

      number the cubic root value
    ceil (x)
    Calculates the ceiling of x (⌈x⌉).

    Parameters:

    • x number the input x

    Returns:

      number the ceiling value (rounding up to nearest integer)
    clamp (x, min, max)
    Clamps the value of x to the range [min, max].

    Parameters:

    • x number the input x
    • min number the lower bound
    • max number the upper bound

    Returns:

      number the clamped value
    cos (x)
    Calculates the cosine of x.

    Parameters:

    • x number the input x (radians)

    Returns:

      number the cosine value
    degToRad (x)
    Converts value expressed in degrees to value expressed in radians.

    Parameters:

    • x number the input number (degrees)

    Returns:

      number the converted output (radians)
    distance (vec1, vec2)
    Calculates the Euclidean (shortest) distance between two Vector3D objects. If you need to quickly compare the distance without its exact value, see distCompare.

    Parameters:

    Returns:

      number the computed distance
    distCompare (vec1, vec2, dist)
    Compares the Euclidean (shortest) distance between two Vector3D objects against a given distance threshold. Faster than the distance function, if you are not interested in the actual distance value, but need to check if it's within, equal to or beyond the threshold.

    Parameters:

    • vec1 Vector3D the first vector
    • vec2 Vector3D the second vector
    • dist number the distance threshold

    Returns:

      int returns:
      • -1 if actual distance is smaller than threshold
      • 0 if they are equal
      • 1 if actual distance is larger than threshold
    exp (x)
    Calculates the exponential of x (ex).

    Parameters:

    • x number the input x

    Returns:

      number the exponential value
    floor (x)
    Calculates the floor of x (⌊x⌋).

    Parameters:

    • x number the input x

    Returns:

      number the floor value (rounding down to nearest integer)
    fmod (x, y)
    Calculates the floating point remainder of x / y.

    Parameters:

    • x number the dividend x
    • y number the divisor y, y ≠ 0

    Returns:

      number the remainder of x / y

    Raises:

    [ERROR] undefined (NaN) for y = 0
    lerp (a, b, t)
    Linearly interpolates between the values [a, b] based on factor t.

    Parameters:

    • a number the lower bound of value range
    • b number the upper bound of value range
    • t number the interpolating factor [0.0, 1.0]

    Returns:

      number the interpolated value (a * (1 - t) + b * t)
    lerpInverse (a, b, x)
    Calculates the linear interpolating factor t based on the value of x between the values [a, b].

    Parameters:

    • a number the lower bound of value range
    • b number the upper bound of value range
    • x number the value between [a, b]

    Returns:

      number the resulting interpolating factor t [0.0, 1.0]
    log (x)
    Calculates the natural logarithm of x (for positive x values).

    Parameters:

    • x number the input x, x > 0

    Returns:

      number the natural logarithm value

    Raises:

    [ERROR] undefined (NaN) for x ≤ 0
    radToDeg (x)
    Converts value expressed in radians to value expressed in degrees.

    Parameters:

    • x number the input number (radians)

    Returns:

      number the converted output (degrees)
    remap (x, oldMin, oldMax, newMin, newMax)
    Linearly remaps the value x from the original range [oldMin, oldMax] to the new range [newMin, newMax]. Output equivalent to:
    lerp(newMin, newMax, lerpInverse(oldMin, oldMax, x)).

    Parameters:

    • x number the value to remap from [oldMin, oldMax] range to [newMin, newMax] range
    • oldMin number the lower bound of the original range
    • oldMax number the upper bound of the original range
    • newMin number the lower bound of the new range
    • newMax number the upper bound of the new range

    Returns:

      number the value of x remapped from [oldMin, oldMax] to [newMin, newMax]
    rotateVectorByAngles (vec, x, y, z)
    Rotates a Vector3D object by a set of Euler angles (x, y, z). Rotation is performed in YXZ order.

    Parameters:

    • vec Vector3D the input vector
    • x number the X Euler angle (radians)
    • y number the Y Euler angle (radians)
    • z number the Z Euler angle (radians)

    Returns:

      Vector3D the rotated vector
    rotateVectorByAxisAngle (vec, axis, theta)
    Rotates a Vector3D object by an axis vector and angle theta.

    Parameters:

    • vec Vector3D the input vector
    • axis Vector3D the rotation axis
    • theta number the rotation angle (radians)

    Returns:

      Vector3D the rotated vector
    rotFromVector (vec)
    Creates a RotVector object from a direction vector. Outputs the X and Y angles, with the Z angle set to 0.

    Parameters:

    • vec Vector3D the input direction vector

    Returns:

      RotVector the RotVector object
    round (x)
    Rounds the floating-point number x to the nearest integer.

    Parameters:

    • x number the input float number x

    Returns:

      int the rounded integer
    sin (x)
    Calculates the sine of x.

    Parameters:

    • x number the input x (radians)

    Returns:

      number the sine value
    smoothStep (x)
    Calculates the SmoothStep of x (3x2 - 2x3; 0 ≤ x ≤ 1)

    Parameters:

    • x number the input x [0.0, 1.0]

    Returns:

      number the SmoothStep value enclosed to [0.0, 1.0]
    sphericalToCartesian (r, theta, phi)
    Converts a set of spherical coordinates (r, θ, φ) to cartesian coordinates (x, y, z). To quickly generate a random direction on a sphere of given radius, see randomSpherePoint.

    Parameters:

    • r number the radius value
    • theta number the θ angle (radians) [0, 2π]
    • phi number the φ angle (radians) [-π/2, π/2]

    Returns:

      Vector3D the Vector3D object containing XYZ cartesian coordinates
    sqrt (x)
    Calculates the square root of x (√x, for non-negative x values).

    Parameters:

    • x number the input x, x ≥ 0

    Returns:

      number the square root value

    Raises:

    [ERROR] undefined (NaN) for x < 0
    tan (x)
    Calculates the tangent of x.

    Parameters:

    • x number the input x (radians). x ≠ (π/2 + k) for any integer k

    Returns:

      number the tangent value

    Raises:

    [ERROR] undefined (NaN) for x = (π/2 + k) for any integer k
    vectorCross (u, v)
    Calculates the vector cross product between the vectors u and v (u ⨯ v).

    Parameters:

    Returns:

      Vector3D the cross product between u and v
    vectorDot (u, v)
    Calculates the vector dot product between the vectors u and v (u ⋅ v).

    Parameters:

    Returns:

      number the dot product between u and v
    vectorLength (v)
    Calculates the length of vector v (|v|).

    Parameters:

    Returns:

      number the length of vector v
    vectorNormalize (v)
    Calculates the normalized (unit) vector from vector v (v/|v|).

    Parameters:

    Returns:

      Vector3D the normalized vector v̂
    wrapAngle (x)
    Wraps the angle x to the range [-π, π].

    Parameters:

    • x number the input x (radians)

    Returns:

      number the wrapped angle in range [-π, π]

    Miscellaneous functions

    hasAllFlags (checkedValue, testFlags)
    Tests for the occurence of all specified flags in a given integer value.

    Parameters:

    • checkedValue int the value against which to compare the test flags
    • testFlags int flags to test for; use the 'plus' operator to combine several flags e.g. FLAG1 + FLAG2 + FLAG3

    Returns:

      bool true if all of testFlags occured within checkedValue; false if at least one flag is missing
    hasAnyFlag (checkedValue, testFlags)
    Tests for the occurence of any specified flags in a given integer value.

    Parameters:

    • checkedValue int the value against which to compare the test flags
    • testFlags int flags to test for; use the 'plus' operator to combine several flags e.g. FLAG1 + FLAG2 + FLAG3

    Returns:

      bool true if at least one flag occured within checkedValue; false none of testFlags is present
    interval (interval[, delay=0])
    Tests for the occurence of a specific game tick interval. Can be used as a shorthand for getGameTick with modulo operator.

    Parameters:

    • interval int the interval value; must be greater or equal to 1
    • delay int the delay of the interval; in the range [0, interval] (default 0)

    Returns:

      bool true if the current game tick is on the interval; false otherwise

    Raises:

    [ERROR] if interval is smaller than 1
generated by LDoc 1.5.0 Last updated 2026-01-02 18:46:05