Livery Files

Manages livery save files - listing, creating, renaming, and deleting `.dynDecals.json` files.

Manages livery save files - listing, creating, renaming, and deleting .dynDecals.json files.

Overview

ui_liveryEditor_userData provides CRUD operations for livery save files stored in settings/dynamicDecals/. It handles filename validation, file system operations, and notifies the UI when the file list changes.

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

Exports (M)

Function	Signature	Description
`requestUpdatedData`	`()`	Triggers `LiverySaveFilesUpdated` with the current save file list.
`saveFileExists`	`(filename) → bool`	Checks if a save file exists by name.
`getSaveFiles`	`() → file[]`	Returns all save files with metadata (name, location, dates, size).
`createSaveFile`	`(filename) → path/false`	Validates filename and saves the layer stack. Returns the file path.
`renameFile`	`(filename, newFilename) → bool`	Renames an existing save file.
`deleteSaveFile`	`(filename) → bool`	Deletes a save file.
`getFilename`	`(file) → string`	Extracts the display name from a full file path.

Internals

File Constants

local saveDir = "settings/dynamicDecals/"
local FILENAME_PATTERN = "^[a-zA-Z0-9_-]+$"
local dynDecalsExtension = ".dynDecals.json"

Save File Format

Each file entry returned by getSaveFiles():

{
  name = "mySkin",                              -- display name (no extension)
  location = "settings/dynamicDecals/mySkin.dynDecals.json",
  created = 1703275200,                         -- unix timestamp
  modified = 1703275200,                        -- unix timestamp
  fileSize = 4096                               -- bytes
}

Filename Validation

Only alphanumeric characters, hyphens, and underscores are allowed:

if not string.match(filename, "^[a-zA-Z0-9_-]+$") then
  log("W", "", "Cannot create invalid filename: " .. filename)
  return false
end

File Operations

Create: api.saveLayerStackToFile(path) serialises the current layer stack
Rename: FS:renameFile(oldPath, newPath) - returns 0 on success
Delete: FS:removeFile(path)

All mutations trigger LiverySaveFilesUpdated to refresh the UI file browser.

How It Works

The save directory is scanned for *.dynDecals.json files via FS:findFiles
Each file's stats (creation time, mod time, size) are read via FS:stat
Creating a save validates the filename pattern, then serialises the layer stack
Rename and delete operations validate file existence before proceeding
UI is notified after every mutation

Example Usage

local userData = extensions.ui_liveryEditor_userData

-- List all saves
local files = userData.getSaveFiles()
for _, f in ipairs(files) do
  print(f.name, f.modified)
end

-- Create a new save
local path = userData.createSaveFile("myRacingLivery")

-- Rename
userData.renameFile("myRacingLivery", "myRacingLivery_v2")

-- Delete
userData.deleteSaveFile("myRacingLivery_v2")

Additional Exports

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

M.createSaveFile
M.deleteSaveFile
M.getFilename
M.getSaveFiles
M.renameFile
M.requestUpdatedData
M.saveFileExists

Overview

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

Exports (M)

Function	Signature	Description
`requestUpdatedData`	`()`	Triggers `LiverySaveFilesUpdated` with the current save file list.
`saveFileExists`	`(filename) → bool`	Checks if a save file exists by name.
`getSaveFiles`	`() → file[]`	Returns all save files with metadata (name, location, dates, size).
`createSaveFile`	`(filename) → path/false`	Validates filename and saves the layer stack. Returns the file path.
`renameFile`	`(filename, newFilename) → bool`	Renames an existing save file.
`deleteSaveFile`	`(filename) → bool`	Deletes a save file.
`getFilename`	`(file) → string`	Extracts the display name from a full file path.

Internals

File Constants

local saveDir = "settings/dynamicDecals/"
local FILENAME_PATTERN = "^[a-zA-Z0-9_-]+$"
local dynDecalsExtension = ".dynDecals.json"

Save File Format

Each file entry returned by getSaveFiles():

{
  name = "mySkin",                              -- display name (no extension)
  location = "settings/dynamicDecals/mySkin.dynDecals.json",
  created = 1703275200,                         -- unix timestamp
  modified = 1703275200,                        -- unix timestamp
  fileSize = 4096                               -- bytes
}

Filename Validation

Only alphanumeric characters, hyphens, and underscores are allowed:

if not string.match(filename, "^[a-zA-Z0-9_-]+$") then
  log("W", "", "Cannot create invalid filename: " .. filename)
  return false
end

File Operations

Create: api.saveLayerStackToFile(path) serialises the current layer stack
Rename: FS:renameFile(oldPath, newPath) - returns 0 on success
Delete: FS:removeFile(path)

All mutations trigger LiverySaveFilesUpdated to refresh the UI file browser.

How It Works

The save directory is scanned for *.dynDecals.json files via FS:findFiles
Each file's stats (creation time, mod time, size) are read via FS:stat
Creating a save validates the filename pattern, then serialises the layer stack
Rename and delete operations validate file existence before proceeding
UI is notified after every mutation

Example Usage

local userData = extensions.ui_liveryEditor_userData

-- List all saves
local files = userData.getSaveFiles()
for _, f in ipairs(files) do
  print(f.name, f.modified)
end

-- Create a new save
local path = userData.createSaveFile("myRacingLivery")

-- Rename
userData.renameFile("myRacingLivery", "myRacingLivery_v2")

-- Delete
userData.deleteSaveFile("myRacingLivery_v2")

Additional Exports

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

M.createSaveFile
M.deleteSaveFile
M.getFilename
M.getSaveFiles
M.renameFile
M.requestUpdatedData
M.saveFileExists

Livery Files

Overview

Exports (M)

Internals

File Constants

Save File Format

Filename Validation

File Operations

How It Works

Example Usage

Additional Exports

See Also

On this page

Livery Files

Overview

Exports (M)

Internals

File Constants

Save File Format

Filename Validation

File Operations

How It Works

Example Usage

Additional Exports

See Also

On this page