IO Reference

Module defined in lua/common/jbeam/io.lua. Handles reading, parsing, and caching of .jbeam files. Provides part lookup by name and slot type.

---

Exports

Functions

M.onExtensionLoaded()

Initializes the module by getting a reference to core_modmanager for mod metadata enrichment.

• Returns: self (module table, for chaining)

M.onFileChanged(filename, type)

Invalidates the file cache entry for a changed .jbeam file. Global caches remain stale until next startLoading.

• Parameters:
  • filename - string - Path to the changed file
  • type - string - Type of change
• Returns: nil

M.startLoading(directories)

Scans directories for .jbeam files, parses them into cache (if not already cached), and rebuilds global lookup tables (partFileMap, partSlotMap, partNameMap).

• Parameters:
  • directories - table - Array of directory paths to scan (e.g. {"/vehicles/pickup/", "/vehicles/common/"})
• Returns: table - IO context: { preloadedDirs = directories }

M.finishLoading()

Cleanup hook called after loading completes. Currently a no-op (cache clearing commented out).

• Returns: nil

M.getPart(ioCtx, partName)

Retrieves a decoded part table by name from the file cache, searching through preloaded directories.

• Parameters:
  • ioCtx - table - IO context from startLoading
  • partName - string - Name of the part to retrieve
• Returns: table, string - Decoded part data and JBeam filename

M.getMainPartName(ioCtx)

Returns the first part registered under the "main" slot type.

• Parameters:
  • ioCtx - table - IO context from startLoading
• Returns: string - Name of the main part

M.getAvailableParts(ioCtx)

Returns a map of all part names to their description metadata across all preloaded directories.

• Parameters:
  • ioCtx - table - IO context from startLoading
• Returns: table - {partName → partDesc} where partDesc has description, authors, isAuxiliary, slotInfoUi

M.getAvailableSlotNameMap(ioCtx)

DEPRECATED - Not compatible with slots2. Returns a map of slot types to arrays of part names that fit each slot.

• Parameters:
  • ioCtx - table - IO context from startLoading
• Returns: table - {slotType → {partName, ...}}

M.getAvailablePartNamesForSlot(ioCtx, slotType)

Returns an array of part names that fit a specific slot type. Wrapper around getAvailableSlotNameMap.

• Parameters:
  • ioCtx - table - IO context
  • slotType - string - Slot type to query
• Returns: table - Array of part name strings

M.getCompatiblePartNamesForSlot(ioCtx, slotDef, slotMap)

Returns compatible part names for a slot definition, supporting both slots v1 (type) and slots v2 (allowTypes/denyTypes).

• Parameters:
  • ioCtx - table - IO context
  • slotDef - table - Slot definition with type or allowTypes/denyTypes
  • slotMap - table|nil - Optional pre-computed slot map from getAvailableSlotNameMap
• Returns: table, table - suitablePartNames array, unsuitablePartNames array (entries are {partName = string, reason = string} tables)

M.getLastStartLoadingStats()

Returns statistics from the last startLoading call.

• Returns: table - { total = number, cachedHits = number }

Internal Notes

• File cache (fileCache) maps filename → parsed cache entry. Parts are stored as stringBuffer.encoded blobs for efficient copying.
• Three derived caches: partFileMap (part→file), partSlotMap (slot→parts), partNameMap (part→description).
• All caches are namespaced by vehicle directory (e.g. /vehicles/pickup/).
• Slot processing happens during parse: both slots (v1) and slots2 (v2) are handled, with v1 auto-upgraded to v2 format internally.
• Mod manager enrichment (modName) only happens on the game engine side.