Variables Reference

Module defined in lua/common/jbeam/variables.lua. Handles JBeam variable system: collecting, scoping, resolving, and applying $variable references and $=expression evaluations across the part tree.

---

Exports

Functions

M.getAllVariables(rootPart, unifyJournal, vehicleConfig)

Collects and resolves all variables across parts respecting slot scoping. Processes root variables first, then traverses the unify journal to build scoped variable maps per part. Evaluates $= expressions within variable definitions. Merges with user config overrides from vehicleConfig.vars.

• Parameters:
  • rootPart - table - The main/root part data
  • unifyJournal - table - Array of unify operations from slot system
  • vehicleConfig - table - Vehicle config (may contain vars overrides)
• Returns: table - Sanitized variable map {$name → value}

M.processComponents(rootPart, unifyJournal, vehicleConfig, vars)

Processes component redirects ($>>path.to.component) in unify journal entries (pre-order). Applies variables with $= evaluation only (assignEqualsOnly mode) before component resolution.

• Parameters:
  • rootPart - table - Root part data
  • unifyJournal - table - Pre-order unify journal (unifyJournalC)
  • vehicleConfig - table - Vehicle configuration
  • vars - table - Resolved variables map
• Returns: boolean - true

M.processParts(rootPart, unifyJournal, vehicleConfig, vars)

Applies variable substitutions to all parts in the unify journal (post-order). Replaces $variable references and evaluates $= expressions using scoped variables.

• Parameters:
  • rootPart - table - Root part data
  • unifyJournal - table - Post-order unify journal
  • vehicleConfig - table - Vehicle configuration
  • vars - table - Resolved variables map
• Returns: table - Final variables map

M.postProcessVariables(vehicle, allVariables)

Stores resolved variables into vehicle.variables as a name-keyed dictionary (transforms from the indexed array format). Does NOT process $>> or $= - those are handled earlier in processParts and processComponents.

• Parameters:
  • vehicle - table - Unified vehicle data
  • allVariables - table - All resolved variables (keyed by $name)
• Returns: nil

M.cleanup(vehicle)

Strips function values from vehicle.components (recursively) and removes hidden variables (hidden = true) from vehicle.variables. Does NOT delete these sections entirely.

• Parameters:
  • vehicle - table - Vehicle data
• Returns: boolean - true

Internal Notes

• Variable scoping: Variables defined in a parent part's slot options are available to child parts. Children can override parent variables.
• Slot variables (slotDef.variables): resolved iteratively against parent scope (up to 400 iterations for circular dependencies).
• Variable types: $varName for direct substitution, $=expr for expression evaluation, $>>path for component redirects, $.name for prefix/suffix expansion.
• Sanitization: variable values that are tables with .val field are unwrapped; min/max/default constraints are enforced.
• Config overrides: vehicleConfig.vars can override any variable value, with sanitization re-applied.
• $+, $<, $> prefixed keys are merge modifiers handled by the slot system, not the variable system.
• Debug mode (debugParts) can dump parts to disk for manual inspection.