Livery Editor

Main livery editor controller - manages setup, teardown, saving, and update loop for the dynamic decal painting system.

Overview

ui_liveryEditor is the top-level controller for the vehicle livery/painting system. It initializes the dynamic decals API, manages the editor lifecycle (setup → edit → save → deactivate), and provides the main update loop.

Extension path: lua/ge/extensions/ui/liveryEditor.lua

Dependencies: editor_api_dynamicDecals, ui_liveryEditor_resources

Exports (M)

Function/Field	Signature	Description
`setup`	`(liveryPath?)`	Initializes the editor, optionally loading a saved livery.
`deactivate`	`()`	Tears down the editor and restores vehicle controls.
`save`	`(filename)`	Exports the current livery skin and creates a save file.
`setDecalTexture`	`(texturePath)`	Sets the active decal color texture.
`useSurfaceNormal`	`(enable)`	Toggles surface-normal-aligned decal projection.
`useMousePosition`	`(enable)`	Toggles mouse-position-based decal placement.
`onUpdate`	`(dtReal, dtSim, dtRaw)`	Frame update - runs API update and handles save loading.
`requestSettingsData`	`()`	Sends current settings to UI via guihook.

State Fields

Field	Description
`M.isRunning`	True while the editor is active.
`M.initialized`	True after first setup.
`M.saveName`	Current save filename.
`M.savePath`	Path to loaded livery.
`M.saveLoaded`	True after livery data has been loaded.
`M.isAddingLayer`	True during layer addition mode.
`M.dependencies`	`{"editor_api_dynamicDecals", "ui_liveryEditor_resources"}` - decal API and resources.

Internals

Setup Flow

M.setup = function(liveryPath)
  api.setLayerNameBuildString("@type { - @colormap}")
  api.setup()
  core_vehicle_partmgmt.setSkin("dynamicTextures")
  extensions.editor_dynamicDecalsTool.doApiUpdate = false
  api.setEnabled(true)
  -- Initialize all ui_liveryEditor_* sub-modules
  -- Disable vehicle controls
  toggleVehicleControls(false)
  M.useSurfaceNormal(true)
  showDecalCursor(false)
  guihooks.trigger("liveryEditor_SetupSuccess", {initialized})
end

Save/Load

-- Save current work
M.save = function(filename)
  api.exportSkin(vehicleObj.jbeam, filename)
  uiUserDataApi.createSaveFile(filename)
end

-- Load is deferred by saveLoadWaitTime (1 second)
-- to ensure the dynamic texture skin is ready

Deactivation

Restores the vehicle to the saved skin, clears the layer stack, re-enables vehicle controls, and resets all state.

Update Loop

The onUpdate function runs every frame while active:

Decrements saveLoadWaitTime
Calls api.onUpdate_() to process decal rendering
After wait expires, loads the saved livery (if any)

Vehicle Control Toggle

local function toggleVehicleControls(enable)
  scenetree.findObject("VehicleCommonActionMap"):setEnabled(enable)
  scenetree.findObject("VehicleSpecificActionMap"):setEnabled(enable)
end

How It Works

UI opens livery editor → calls M.setup(liveryPath)
Dynamic decals API is initialized and vehicle skin set to "dynamicTextures"
Sub-modules (camera, controls, layers) are initialized
After 1-second delay, existing livery is loaded or new one started
User edits decals/layers through sub-module APIs
M.save(filename) exports the skin; M.deactivate() cleans up

Additional Exports

The following exports are available but not yet documented in detail:

M.onUpdate
M.requestSettingsData
M.saveLoadWaitTime
M.setDecalTexture
M.useMousePosition

Main livery editor controller - manages setup, teardown, saving, and update loop for the dynamic decal painting system.

Overview

Extension path: lua/ge/extensions/ui/liveryEditor.lua

Dependencies: editor_api_dynamicDecals, ui_liveryEditor_resources

Exports (M)

Function/Field	Signature	Description
`setup`	`(liveryPath?)`	Initializes the editor, optionally loading a saved livery.
`deactivate`	`()`	Tears down the editor and restores vehicle controls.
`save`	`(filename)`	Exports the current livery skin and creates a save file.
`setDecalTexture`	`(texturePath)`	Sets the active decal color texture.
`useSurfaceNormal`	`(enable)`	Toggles surface-normal-aligned decal projection.
`useMousePosition`	`(enable)`	Toggles mouse-position-based decal placement.
`onUpdate`	`(dtReal, dtSim, dtRaw)`	Frame update - runs API update and handles save loading.
`requestSettingsData`	`()`	Sends current settings to UI via guihook.

State Fields

Field	Description
`M.isRunning`	True while the editor is active.
`M.initialized`	True after first setup.
`M.saveName`	Current save filename.
`M.savePath`	Path to loaded livery.
`M.saveLoaded`	True after livery data has been loaded.
`M.isAddingLayer`	True during layer addition mode.
`M.dependencies`	`{"editor_api_dynamicDecals", "ui_liveryEditor_resources"}` - decal API and resources.

Internals

Setup Flow

M.setup = function(liveryPath)
  api.setLayerNameBuildString("@type { - @colormap}")
  api.setup()
  core_vehicle_partmgmt.setSkin("dynamicTextures")
  extensions.editor_dynamicDecalsTool.doApiUpdate = false
  api.setEnabled(true)
  -- Initialize all ui_liveryEditor_* sub-modules
  -- Disable vehicle controls
  toggleVehicleControls(false)
  M.useSurfaceNormal(true)
  showDecalCursor(false)
  guihooks.trigger("liveryEditor_SetupSuccess", {initialized})
end

Save/Load

-- Save current work
M.save = function(filename)
  api.exportSkin(vehicleObj.jbeam, filename)
  uiUserDataApi.createSaveFile(filename)
end

-- Load is deferred by saveLoadWaitTime (1 second)
-- to ensure the dynamic texture skin is ready

Deactivation

Restores the vehicle to the saved skin, clears the layer stack, re-enables vehicle controls, and resets all state.

Update Loop

The onUpdate function runs every frame while active:

Decrements saveLoadWaitTime
Calls api.onUpdate_() to process decal rendering
After wait expires, loads the saved livery (if any)

Vehicle Control Toggle

local function toggleVehicleControls(enable)
  scenetree.findObject("VehicleCommonActionMap"):setEnabled(enable)
  scenetree.findObject("VehicleSpecificActionMap"):setEnabled(enable)
end

How It Works

UI opens livery editor → calls M.setup(liveryPath)
Dynamic decals API is initialized and vehicle skin set to "dynamicTextures"
Sub-modules (camera, controls, layers) are initialized
After 1-second delay, existing livery is loaded or new one started
User edits decals/layers through sub-module APIs
M.save(filename) exports the skin; M.deactivate() cleans up

Additional Exports

The following exports are available but not yet documented in detail:

M.onUpdate
M.requestSettingsData
M.saveLoadWaitTime
M.setDecalTexture
M.useMousePosition

Livery Editor

Overview

Exports (M)

State Fields

Internals

Setup Flow

Save/Load

Deactivation

Update Loop

Vehicle Control Toggle

How It Works

Additional Exports

On this page

Livery Editor

Overview

Exports (M)

State Fields

Internals

Setup Flow

Save/Load

Deactivation

Update Loop

Vehicle Control Toggle

How It Works

Additional Exports

On this page