particles Reference

Module defined in lua/common/particles.lua. Manages particle material data and lookup tables for collision-based particle effects (e.g., tire smoke, sparks, debris).

---

Exports

Functions

M.getMaterialByID(mats, i)

Retrieves a material definition by its index.

• Parameters:
  • mats - table - Materials array
  • i - number|nil - Material index
• Returns: table - Material data for the given ID

M.getMaterialIDByName(mats, s)

Finds a material index by name; returns a safe fallback if not found.

• Parameters:
  • mats - table - Materials array
  • s - string - Material name
• Returns: number - Material index (falls back to min(3, #mats) if not found)

M.getOrAddMaterialIDByName(mats, s)

Finds a material index by name, creating a temporary definition if not found.

• Parameters:
  • mats - table - Materials array
  • s - string - Material name
• Returns: number - Material index (newly created if not found)

M.getMaterialsParticlesTable()

Returns the full materials and material-pair-to-particles mapping tables.

• Returns: table, table - materials array and materialsMap lookup table

Internal Notes

• Materials and particle definitions are loaded from lua/common/particles.json at require time
• The materialsMap key is materialID1 * 10000 + materialID2 with IDs sorted so the larger is first
• Each particle definition has dynamically compiled comparison functions from expressions like "X > 5" where X is replaced with the actual field value
• Comparison fields: perpendicularVel, slipVel - expressions evaluate against runtime collision data
• Material definitions include: name, colorR, colorG, colorB, dynamic flag