Transform Utility

Reusable position/rotation/scale editor widget with axis gizmo integration, helper buttons (down-to-terrain, focus, move-to-camera, align-with-terrain), and shift+click quick placement.

Class: `C` (returned by factory function)

Core Methods

Method	Signature	Description
`C:init(editName, objectName)`	-	Creates a unique edit mode, input fields, and default transform
`C:set(pos, rot, scl)`	All optional	Sets position/rotation/scale; nil params are ignored
`C:setOneDimensionalScale(ods)`	`bool`	Toggles between single float and vec3 scale
`C:start()`	-	Activates the associated edit mode
`C:stop()`	-	Deactivates the edit mode if currently active
`C:update(mouseInfo)`	-	Full update: gizmo + widget + shift-drag quick edit; returns changed
`C:enableEditing(cooldown)`	`cooldown: int` (default 1)	Activates edit mode with brief input cooldown
`C:combinedWidget()`	-	Renders edit/done button + helper buttons + pos/rot/scl inputs
`C:widget()`	-	Renders basic pos/rot/scl input fields
`C:widgetCondensed()`	-	Compact version with "Pos"/"Rot"/"Scl" labels
`C:gizmo()`	-	Renders edit/exit button and manages axis gizmo
`C:contextMenu()`	-	Renders right-click context menu with position/rotation helpers

Helper Actions

Method	Description
`C:helperFocus()`	Smoothly focuses camera on the transform position
`C:helperPositionToCamera()`	Sets position to current camera position
`C:helperPositionInFrontOfToCamera()`	Places 15m in front of camera
`C:helperPositionDownToTerrain()`	Drops position to terrain height
`C:helperRotationToCamera()`	Sets rotation to match camera
`C:helperRotateWithCamera()`	Rotates to face away from camera
`C:helperAlignWithTerrain()`	Aligns rotation with terrain normal
`C:helperMoveToTransform()`	Teleports player vehicle to the transform
`C:helperCameraToPosition()`	Moves free camera to the position
`C:helperCameraToRotation()`	Sets free camera rotation
`C:helperCameraToPositionRotation()`	Moves and rotates free camera

Dragging

Method	Description
`C:beginDrag()`	Stores pre-drag state
`C:dragging()`	Applies gizmo translation/rotation/scale; draws debug axes
`C:endDragging()`	Marks drag complete
`C:resetDragging()`	Clears stored drag state
`C:shiftUpdate(mouseInfo)`	Handles shift+click-drag quick placement on terrain

State

Method	Description
`C:correctEditMode()`	Returns `true` if this transform's edit mode is active
`C:updateTransform()`	Syncs the gizmo MatrixF from current pos/rot
`C:updateInputFields()`	Syncs ImGui input pointers from current pos/rot/scl
`C:getValidButtons()`	Returns helper buttons filtered by allowTranslate/allowRotate
`C:onActivate()`	Clears object selection on edit mode activate
`C:onDeactivate()`	Clears object selection on edit mode deactivate

Usage Example

local transformUtil = require('/lua/ge/extensions/editor/util/transformUtil')

-- Create a transform helper
local tr = transformUtil("Spawn Point", "Spawn")
tr.allowTranslate = true
tr.allowRotate = true
tr.allowScale = false

-- Set initial position
tr:set(vec3(100, 200, 50), quatFromDir(vec3(0, 1, 0), vec3(0, 0, 1)))

-- In editor GUI update loop:
local mouseInfo = {
  camPos = core_camera.getPosition(),
  ray = getCameraMouseRay(),
  rayCast = cameraMouseRayCast(),
  valid = true,
  down = im.IsMouseClicked(0),
  hold = im.IsMouseDown(0),
  up = im.IsMouseReleased(0),
}

if tr:update(mouseInfo) then
  -- Transform was changed
  local pos = tr.pos
  local rot = tr.rot
  log("I", "", string.format("New pos: %.1f, %.1f, %.1f", pos.x, pos.y, pos.z))
end

-- Or use the simpler gizmo-only mode:
if tr:gizmo() then
  -- Transform changed via gizmo
end

-- Quick placement: hold Shift and click-drag on terrain
-- The position snaps to click point, rotation follows drag direction
-- Scale is set by drag distance (if one-dimensional scale enabled)

Class: `C` (returned by factory function)

Core Methods

Method	Signature	Description
`C:init(editName, objectName)`	-	Creates a unique edit mode, input fields, and default transform
`C:set(pos, rot, scl)`	All optional	Sets position/rotation/scale; nil params are ignored
`C:setOneDimensionalScale(ods)`	`bool`	Toggles between single float and vec3 scale
`C:start()`	-	Activates the associated edit mode
`C:stop()`	-	Deactivates the edit mode if currently active
`C:update(mouseInfo)`	-	Full update: gizmo + widget + shift-drag quick edit; returns changed
`C:enableEditing(cooldown)`	`cooldown: int` (default 1)	Activates edit mode with brief input cooldown
`C:combinedWidget()`	-	Renders edit/done button + helper buttons + pos/rot/scl inputs
`C:widget()`	-	Renders basic pos/rot/scl input fields
`C:widgetCondensed()`	-	Compact version with "Pos"/"Rot"/"Scl" labels
`C:gizmo()`	-	Renders edit/exit button and manages axis gizmo
`C:contextMenu()`	-	Renders right-click context menu with position/rotation helpers

Helper Actions

Method	Description
`C:helperFocus()`	Smoothly focuses camera on the transform position
`C:helperPositionToCamera()`	Sets position to current camera position
`C:helperPositionInFrontOfToCamera()`	Places 15m in front of camera
`C:helperPositionDownToTerrain()`	Drops position to terrain height
`C:helperRotationToCamera()`	Sets rotation to match camera
`C:helperRotateWithCamera()`	Rotates to face away from camera
`C:helperAlignWithTerrain()`	Aligns rotation with terrain normal
`C:helperMoveToTransform()`	Teleports player vehicle to the transform
`C:helperCameraToPosition()`	Moves free camera to the position
`C:helperCameraToRotation()`	Sets free camera rotation
`C:helperCameraToPositionRotation()`	Moves and rotates free camera

Dragging

Method	Description
`C:beginDrag()`	Stores pre-drag state
`C:dragging()`	Applies gizmo translation/rotation/scale; draws debug axes
`C:endDragging()`	Marks drag complete
`C:resetDragging()`	Clears stored drag state
`C:shiftUpdate(mouseInfo)`	Handles shift+click-drag quick placement on terrain

State

Method	Description
`C:correctEditMode()`	Returns `true` if this transform's edit mode is active
`C:updateTransform()`	Syncs the gizmo MatrixF from current pos/rot
`C:updateInputFields()`	Syncs ImGui input pointers from current pos/rot/scl
`C:getValidButtons()`	Returns helper buttons filtered by allowTranslate/allowRotate
`C:onActivate()`	Clears object selection on edit mode activate
`C:onDeactivate()`	Clears object selection on edit mode deactivate

Usage Example

local transformUtil = require('/lua/ge/extensions/editor/util/transformUtil')

-- Create a transform helper
local tr = transformUtil("Spawn Point", "Spawn")
tr.allowTranslate = true
tr.allowRotate = true
tr.allowScale = false

-- Set initial position
tr:set(vec3(100, 200, 50), quatFromDir(vec3(0, 1, 0), vec3(0, 0, 1)))

-- In editor GUI update loop:
local mouseInfo = {
  camPos = core_camera.getPosition(),
  ray = getCameraMouseRay(),
  rayCast = cameraMouseRayCast(),
  valid = true,
  down = im.IsMouseClicked(0),
  hold = im.IsMouseDown(0),
  up = im.IsMouseReleased(0),
}

if tr:update(mouseInfo) then
  -- Transform was changed
  local pos = tr.pos
  local rot = tr.rot
  log("I", "", string.format("New pos: %.1f, %.1f, %.1f", pos.x, pos.y, pos.z))
end

-- Or use the simpler gizmo-only mode:
if tr:gizmo() then
  -- Transform changed via gizmo
end

-- Quick placement: hold Shift and click-drag on terrain
-- The position snaps to click point, rotation follows drag direction
-- Scale is set by drag distance (if one-dimensional scale enabled)

Transform Utility

Class: `C` (returned by factory function)

Core Methods

Helper Actions

Dragging

State

Usage Example

See Also

On this page

Transform Utility

Class: `C` (returned by factory function)

Core Methods

Helper Actions

Dragging

State

Usage Example

See Also

On this page