Edit Mode State Machine

Edit mode state machine for the livery editor - manages layer application, reapplication, selection, and undo within an editing session.

Overview

ui_liveryEditor_editMode controls the state machine for applying, reapplying, and managing decal layers during an active livery editing session. It tracks applied layers, handles cursor properties, and provides save/cancel operations.

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

Note: This file is entirely commented out in the current codebase, indicating it is either deprecated, in development, or being refactored. The documented API reflects the commented implementation.

Commented API

State Fields

Field	Type	Description
`active`	boolean	Whether edit mode is currently active.
`applyActive`	boolean	Whether a new decal application is pending.
`reapplyActive`	boolean	Whether reapplying an existing layer.
`allowApply`	boolean	Whether apply action is permitted.
`activeLayerUid`	string	UID of the currently selected layer.
`appliedLayers`	table	List of layer UIDs applied in this session.
`isDuplicateActiveLayer`	boolean	Flag during layer duplication.

Core Functions

Function	Description
`activate()`	Enters edit mode, pushes action map, starts apply request.
`deactivate()`	Exits edit mode, clears state, pops action map.
`apply()`	Applies current decal if allowed.
`onApply(layer)`	Callback after decal application - handles continuous/single apply.
`requestApply()`	Starts a new apply operation.
`cancelRequestApply()`	Cancels pending apply.
`requestReapply()`	Begins reapplying an existing layer (disables original).
`cancelReapply()`	Cancels reapply, re-enables original layer.
`saveChanges(params)`	Finalizes applied layers, optionally grouping them.
`cancelChanges()`	Removes all applied layers and resets state.

Layer Management

Function	Description
`setActiveLayer(uid)`	Selects a layer, updates highlighting and UI.
`setActiveLayerDirection(dir)`	Navigates between applied layers (+1/-1).
`duplicateActiveLayer()`	Creates a copy of the active layer.
`removeAppliedLayer(uid)`	Removes a layer and updates applied list.
`getActiveLayer()`	Returns the current active layer data.
`toggleHighlightActive()`	Toggles decal highlighting on the active layer.

Internals

State Machine Flow

deactivate → activate → requestApply → apply → onApply
                                                  ↓
                                        (continuous) → cursor stays active
                                        (single)    → setActiveLayer → edit/reapply
                                                  ↓
                                        requestReapply → apply → onApply → setActiveLayer
                                                  ↓
                                        saveChanges / cancelChanges → deactivate

Continuous vs Single Apply

When api.isUseMousePos() is true (mouse projection), apply is continuous - each click adds a decal and the cursor stays active. In cursor mode, apply is single-shot and selects the new layer.

Layer Grouping

saveChanges({grouped = true}) creates a linked set and moves all applied layers into it:

local group = api.addLinkedSet()
for k, v in ipairs(M.appliedLayers) do
  api.moveLayer(lastPos, nil, index, group.uid)
end

Hooks

Hook	Description
`liveryEditor_OnLayerAdded`	Tracks new layers, handles reapply replacement.
`liveryEditor_onLayersUpdated`	Updates highlighting when layers change.
`liveryEditor_editMode_onStateChanged`	Broadcasts state changes to other modules.

How It Works

User enters edit mode → activate() pushes action map and starts apply
Decal cursor becomes visible, user positions and clicks to apply
onApply records the layer and either continues or enters selection
User can reapply (modify position of existing layer) or add more
saveChanges finalizes; cancelChanges removes all applied layers
deactivate clears everything and restores normal mode

Additional Exports

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

M.activate
M.active
M.activeLayerUid
M.allowApply
M.apply
M.applyActive
M.cancelChanges
M.cancelReapply
M.cancelRequestApply
M.deactivate
M.duplicateActiveLayer
M.editModeStateChanged
M.getActiveLayer
M.getAppliedLayersData
M.highlightTimer
M.isApplyActive
M.isContinuousApply
M.isDuplicateActiveLayer
M.isReapplyActive
M.lastLayerPosition
M.liveryEditor_OnLayerAdded
M.liveryEditor_OnLayerDeleted
M.liveryEditor_onLayersUpdated
M.onApply
M.onUpdate
M.reapplyActive
M.removeAppliedLayer
M.requestApply
M.requestReapply
M.resetCursorProperties
M.saveChanges
M.setActive
M.setActiveLayer
M.setActiveLayerDirection
M.setAllowApply
M.setAppliedLayers
M.setApplyActive
M.setReapplyActive
M.setup
M.toggleHighlightActive
M.toggleRequestApply

Field	Type	Description
`active`	boolean	Whether edit mode is currently active.
`applyActive`	boolean	Whether a new decal application is pending.
`reapplyActive`	boolean	Whether reapplying an existing layer.
`allowApply`	boolean	Whether apply action is permitted.
`activeLayerUid`	string	UID of the currently selected layer.
`appliedLayers`	table	List of layer UIDs applied in this session.
`isDuplicateActiveLayer`	boolean	Flag during layer duplication.

Core Functions

Function	Description
`activate()`	Enters edit mode, pushes action map, starts apply request.
`deactivate()`	Exits edit mode, clears state, pops action map.
`apply()`	Applies current decal if allowed.
`onApply(layer)`	Callback after decal application - handles continuous/single apply.
`requestApply()`	Starts a new apply operation.
`cancelRequestApply()`	Cancels pending apply.
`requestReapply()`	Begins reapplying an existing layer (disables original).
`cancelReapply()`	Cancels reapply, re-enables original layer.
`saveChanges(params)`	Finalizes applied layers, optionally grouping them.
`cancelChanges()`	Removes all applied layers and resets state.

Layer Management

Function	Description
`setActiveLayer(uid)`	Selects a layer, updates highlighting and UI.
`setActiveLayerDirection(dir)`	Navigates between applied layers (+1/-1).
`duplicateActiveLayer()`	Creates a copy of the active layer.
`removeAppliedLayer(uid)`	Removes a layer and updates applied list.
`getActiveLayer()`	Returns the current active layer data.
`toggleHighlightActive()`	Toggles decal highlighting on the active layer.

Internals

State Machine Flow

deactivate → activate → requestApply → apply → onApply
                                                  ↓
                                        (continuous) → cursor stays active
                                        (single)    → setActiveLayer → edit/reapply
                                                  ↓
                                        requestReapply → apply → onApply → setActiveLayer
                                                  ↓
                                        saveChanges / cancelChanges → deactivate

Continuous vs Single Apply

When api.isUseMousePos() is true (mouse projection), apply is continuous - each click adds a decal and the cursor stays active. In cursor mode, apply is single-shot and selects the new layer.

Layer Grouping

saveChanges({grouped = true}) creates a linked set and moves all applied layers into it:

local group = api.addLinkedSet()
for k, v in ipairs(M.appliedLayers) do
  api.moveLayer(lastPos, nil, index, group.uid)
end

Hooks

Hook	Description
`liveryEditor_OnLayerAdded`	Tracks new layers, handles reapply replacement.
`liveryEditor_onLayersUpdated`	Updates highlighting when layers change.
`liveryEditor_editMode_onStateChanged`	Broadcasts state changes to other modules.

How It Works

User enters edit mode → activate() pushes action map and starts apply
Decal cursor becomes visible, user positions and clicks to apply
onApply records the layer and either continues or enters selection
User can reapply (modify position of existing layer) or add more
saveChanges finalizes; cancelChanges removes all applied layers
deactivate clears everything and restores normal mode

Additional Exports

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

M.activate
M.active
M.activeLayerUid
M.allowApply
M.apply
M.applyActive
M.cancelChanges
M.cancelReapply
M.cancelRequestApply
M.deactivate
M.duplicateActiveLayer
M.editModeStateChanged
M.getActiveLayer
M.getAppliedLayersData
M.highlightTimer
M.isApplyActive
M.isContinuousApply
M.isDuplicateActiveLayer
M.isReapplyActive
M.lastLayerPosition
M.liveryEditor_OnLayerAdded
M.liveryEditor_OnLayerDeleted
M.liveryEditor_onLayersUpdated
M.onApply
M.onUpdate
M.reapplyActive
M.removeAppliedLayer
M.requestApply
M.requestReapply
M.resetCursorProperties
M.saveChanges
M.setActive
M.setActiveLayer
M.setActiveLayerDirection
M.setAllowApply
M.setAppliedLayers
M.setApplyActive
M.setReapplyActive
M.setup
M.toggleHighlightActive
M.toggleRequestApply

Edit Mode State Machine

Overview

Commented API

State Fields

Core Functions

Layer Management

Internals

State Machine Flow

Continuous vs Single Apply

Layer Grouping

Hooks

How It Works

Additional Exports

See Also

On this page

Edit Mode State Machine

Overview

Commented API

State Fields

Core Functions

Layer Management

Internals

State Machine Flow

Continuous vs Single Apply

Layer Grouping

Hooks

How It Works

Additional Exports

See Also

On this page