Utils Reference

Module defined in lua/common/jbeam/utils.lua. Provides low-level construction utilities for adding nodes, beams, and rotators to vehicle data, plus node transform operations (rotate/offset/move).

---

Exports

Functions

M.increaseMax(vehicle, name)

Increments and returns the next available ID counter for a given section name.

• Parameters:
  • vehicle - table - Vehicle data with maxIDs table
  • name - string - Section name (e.g. "nodes", "beams")
• Returns: number - The ID before increment (0-based)

M.addNodeWithOptions(vehicle, pos, ntype, options)

Adds a new node to the vehicle with specified options.

• Parameters:
  • vehicle - table - Vehicle data
  • pos - vec3 - Position vector
  • ntype - number - Node type (0=normal, 1=fixed, 2=non-collidable)
  • options - table - Options to deep-copy onto the node
• Returns: number - CID of the newly added node

M.addNode(vehicle, pos, ntype)

Convenience wrapper for addNodeWithOptions using vehicle.options as default options.

• Parameters:
  • vehicle - table - Vehicle data
  • pos - vec3 - Position vector
  • ntype - number - Node type
• Returns: number - CID of the newly added node

M.addBeamWithOptions(vehicle, id1, id2, beamType, options, id3)

Adds a beam connecting two (or three) nodes. Validates node existence. If id3 is provided, beam type is forced to BEAM_LBEAM.

• Parameters:
  • vehicle - table - Vehicle data
  • id1 - number|nil - First node ID (falls back to options.id1)
  • id2 - number|nil - Second node ID (falls back to options.id2)
  • beamType - number - Beam type constant (0=normal, 1=anisotropic, 2=bounded, 3=pressured, 4=lbeam, 6=hydro, 7=support)
  • options - table - Options to deep-copy onto the beam
  • id3 - number|nil - Optional third node (forces LBEAM type)
• Returns: table - The created beam object

M.addBeam(vehicle, id1, id2)

Convenience wrapper for addBeamWithOptions using NORMALTYPE and vehicle.options.

• Parameters:
  • vehicle - table - Vehicle data
  • id1 - number - First node ID
  • id2 - number - Second node ID
• Returns: table - The created beam object

M.addRotator(vehicle, wheelKey, wheel)

Configures a rotator (powered wheel hub) by collecting nodes from _group_nodes and _rotatorGroup_nodes into the wheel's nodes array. Sets default frictionCoef to 1.

• Parameters:
  • vehicle - table - Vehicle data
  • wheelKey - any - Wheel identifier (unused in body)
  • wheel - table - Wheel/rotator data with _group_nodes, _rotatorGroup_nodes
• Returns: nil

M.getPosAfterNodeRotateOffsetMove(jbeamData, x, y, z)

Applies node transform operations (nodeRotate, nodeOffset, nodeMove) to a position. Uses matrix math when rotations are present, simple addition for offsets/moves only. Caches the transform matrix.

• Parameters:
  • jbeamData - table - Row data containing nodeRotate##, nodeOffset##, nodeMove## entries
  • x - number - X position
  • y - number - Y position
  • z - number - Z position
• Returns: number, number, number - Transformed x, y, z

M.getFlexbodyPosRotAfterNodeRotateOffsetMove(jbeamData, x, y, z, rx, ry, rz)

Like getPosAfterNodeRotateOffsetMove but also transforms rotation (Euler angles). Used for flexbody positioning.

• Parameters:
  • jbeamData - table - Row data with node transforms
  • x, y, z - number - Position
  • rx, ry, rz - number - Rotation in degrees
• Returns: number, number, number - Transformed x, y, z position

M.getPosRotBeforeNodeRotateOffsetMove(jbeamData, x, y, z, rx, ry, rz)

Inverse of transform operations - given a final position/rotation, computes the original position before transforms were applied. Tries positive, zero, and negative X signs to find the correct solution.

• Parameters:
  • jbeamData - table - Row data with node transforms
  • x, y, z - number - Final position
  • rx, ry, rz - number - Final rotation in degrees
• Returns: number×6 - Original x,y,z,rx,ry,rz

Variables

M.ignoreSections

• Type: table
• Description: Set of section names to skip during processing
• Expected structure: {maxIDs = true, options = true}

Internal Notes

• Node transforms are numbered: nodeRotate0, nodeOffset1, nodeMove2, etc. Applied in index order.
• Each transform has {x, y, z} and optionally {px, py, pz} (rotation pivot point).
• nodeOffset respects X-axis sign (for mirroring left/right sides).
• Transform cache (cacheOpsMat) avoids recomputing when the same transforms are reused across nodes.
• ignoreNodeOffset flag on jbeamData disables offset processing.

---

See Also

• ExpressionParser Reference - Related reference
• Groups Reference - Related reference
• Interaction Reference - Related reference
• Common Libraries Overview - Guide