extensions Reference

Module defined in lua/common/extensions.lua. The core extension/module management system for BeamNG. Handles loading, unloading, dependency resolution, hook dispatch, serialization, and virtual extension proxies.

---

Exports

Functions

M.load(...)

Loads one or more extensions by name or path. Triggers onExtensionLoaded on fresh loads.

• Parameters:
  • ... - string|table - Extension names or arrays of names

M.unload(extName)

Unloads an extension and any extensions that depend on it. Calls onExtensionUnloaded on each.

• Parameters:
  • extName - string|table - Extension name or extension table with __extensionName__

M.reload(extPath)

Unloads then reloads an extension from disk (cache is cleared).

• Parameters:
  • extPath - string - Extension name/path

M.refresh(extName)

Re-registers an already-loaded extension without reloading from disk.

• Parameters:
  • extName - string - Extension name
• Returns: table|false - Refreshed module or false on failure

M.unloadExcept(...)

Unloads all extensions EXCEPT those in the provided list (and their dependencies).

• Parameters:
  • ... - table - Arrays of extension names to keep

M.hook(funcName, ...)

Dispatches a hook call to all loaded extensions that implement funcName. Uses cached function lists for performance.

• Parameters:
  • funcName - string - Hook/function name (e.g., "onUpdate", "onVehicleSpawned")
  • ... - any - Arguments forwarded to each extension's function

M.hookNotify(func, ...)

Like hook but also fires any registered completion callbacks for the hook.

• Parameters:
  • func - string - Hook name
  • ... - any - Arguments

M.hookExcept(exceptionList, func, ...)

Dispatches a hook to all extensions except those in the exception list.

• Parameters:
  • exceptionList - table - Array of extension paths to skip
  • func - string - Hook name
  • ... - any - Arguments

M.hookUpdate(funcName)

Invalidates the cached function list for a hook, forcing rebuild on next call.

• Parameters:
  • funcName - string - Hook name to invalidate

M.isExtensionLoaded(extName)

Checks if an extension is currently loaded.

• Parameters:
  • extName - string - Extension name
• Returns: boolean

M.loadModulesInDirectory(directory, excludeSubdirectories)

Discovers and loads all .lua files in a directory.

• Parameters:
  • directory - string - Directory path to scan
  • excludeSubdirectories - table|nil - Array of subdirectory patterns to skip

M.loadAtRoot(extPath, rootName)

Loads an extension from a file path but registers it under a custom root namespace.

• Parameters:
  • extPath - string - File path to the extension
  • rootName - string - Root namespace prefix (empty string for global root)
• Returns: string, table - Extension name and module table

M.setCompletedCallback(funcName, callback)

Registers a callback to fire after the next hookNotify dispatch of funcName.

• Parameters:
  • funcName - string - Hook name
  • callback - function - Callback to invoke

M.getSerializationData(reason)

Serializes all loaded extensions' state (calls onSerialize on each).

• Parameters:
  • reason - string|nil - Reason for serialization (default: "reload")
• Returns: table - Serialized state data

M.deserialize(data, filter)

Restores extensions from serialized data. Reloads modules and calls onDeserialize/onDeserialized.

• Parameters:
  • data - table - Previously serialized state
  • filter - string|nil - Optional extension name to exclusively deserialize

M.disableSerialization(...)

Excludes extensions from being serialized during Lua VM reloads.

• Parameters:
  • ... - string|table - Extension names to exclude

M.getLoadedExtensionsNames(excludeVirtual)

Returns sorted list of all loaded extension names.

• Parameters:
  • excludeVirtual - boolean|nil - Whether to exclude virtual extensions
• Returns: table - Sorted array of extension names

M.luaPathToExtName(filepath)

Converts a file path like "core/vehicles/manager" to extension name "core_vehicles_manager".

• Parameters:
  • filepath - string - Lua module path
• Returns: string - Extension name

M.extNameToLuaPath(extName)

Converts extension name back to Lua module path.

• Parameters:
  • extName - string - Extension name
• Returns: string - Lua path

M.addModulePath(directory)

Adds a directory to package.path for module resolution.

• Parameters:
  • directory - string - Directory to add

M.saveModulePath() / M.restoreModulePath()

Save/restore package.path around temporary modifications.

M.setProfiler(p) / M.wrapAllExtensionsForProfiler()

Performance profiling integration. Sets a profiler object or wraps all extension functions with profiler calls.

M.printExtensions()

Logs all loaded extensions and their dependencies.

M.printHooks(funcName)

Prints which extensions implement a given hook function.

• Parameters:
  • funcName - string - Hook name to check

M.loadModule(extName) (deprecated)

Deprecated wrapper for M.load(). Logs a warning.

M.reloadModule(modulePath) (deprecated)

Deprecated wrapper for M.reload(). Logs a warning.

M.unloadModule(extName) (deprecated)

Deprecated wrapper for M.unload(). Logs a warning.

M.use(key)

Loads an extension by key and returns it. Convenience for load(key); return M[key].

Global Functions

newExtensionProxy(parentExtension, identifierPrefix)

Creates a virtual extension proxy for forwarding hooks to OOP/class instances.

• Parameters:
  • parentExtension - table|nil - Parent extension module
  • identifierPrefix - string|nil - Prefix for the virtual extension name
• Returns: ExtensionProxy - Proxy object

ExtensionProxy Methods

proxy:submitEventSinks(hookableTablesInstances, dependencies)

Registers class instances whose on* methods should receive extension hooks.

• Parameters:
  • hookableTablesInstances - table - Array of objects with on* methods
  • dependencies - table|nil - Extension dependencies

proxy:destroy()

Removes the virtual extension proxy from the extension system.

Variables

M.onDeserialized / M.onDeserialize / M.onSerialize

• Type: function (nop)
• Description: Placeholder hooks for the extensions module itself

Internal Notes

• Extension names use underscores to replace path separators: core/vehicles/manager → core_vehicles_manager
• Double underscores escape literal underscores in paths
• Dependencies are resolved topologically; cyclic dependencies are force-resolved with a warning
• Hook dispatch has two modes: profiled (default in non-shipping builds) and fast
• The metatable __index on M auto-loads extensions on first access
• Virtual extensions are created by newExtensionProxy and are not serialized or disk-loaded
• Deprecated function names are auto-patched: onLoad → onExtensionLoaded, init → onExtensionLoaded, etc.