server/server - Level Loading & Game Server

Reference for server/server.lua. Manages level loading, mission lifecycle, physics initialization, and the loading screen. Despite the name, this is a local "server" - BeamNG runs a client-server architecture even in single-player.

Exports

Internals

Level Loading Pipeline (createGameActual)

1. Init: Enable loading screen, set $loadingLevel, normalize path, call clientPreStartMission.
2. Datablocks: Initialize physics world, load particle data, audio profiles, player data, managed datablocks.
3. Materials: End any existing mission, create LevelLoadingGroup, load all .cs and .json material files from level directory.
4. Objects: Load level objects from main/ folder (scenetree format) or legacy .mis file. Create MissionCleanup group.
5. AI Map: Trigger map.onMissionLoaded() for navgraph building.
6. Decals: Load main.decals.json if present.
7. Physics: Start physics simulation.
8. Spawn: Spawn camera and player vehicle.
9. Fadeout: Transition from loading screen to gameplay.

endMission(profiler?)

Tears down the current level:

• Calls clientEndMission
• Stops audio channels
• Clears decals
• Deletes all objects in MissionGroup
• Cleans up MissionCleanup, LevelLoadingGroup
• Resets mission path

destroy(profiler?)

Full server shutdown:

• Ends mission
• Destroys physics world
• Deletes all datablocks
• Increments session counter
• Clears levelLoaded and gameConnection globals

Command Line Patching

patchLoadingContext(ldgCtx) supports -levelOffset X Y Z to apply a global translation matrix to the level during loading.

How It Works

createGame wraps the actual loading in a loading screen request via core_gamestate. The loading screen ensures UI shows progress while the heavy work runs. After loading, fadeoutLoadingScreen fires clientPostStartMission and clientStartMission hooks, then disables the loading screen.

-- Load a level
server.createGame('/levels/west_coast_usa/info.json')

-- With custom loading callback
server.createGame('/levels/gridmap/info.json', function()
  -- Custom setup before fadeout
  server.fadeoutLoadingScreen()
end)

-- Destroy current level
server.destroy()

Exported Variables

• loadingProgress - Exported variable - initialized as loadingProgress