Visual

Visual is a client-only retained overlay API for world-space lines, wireframes, and simple retained marker visuals.

• non-authoritative (rendering only)
• handle based (resource-owned)
• intended for tooling/debug/editor overlays (for example map editor bounds, gizmos, and marker previews)

Scope

• client-only world overlays
• no gameplay authority
• auto-cleanup when resource unloads/disconnects

Function List

Function	Description	Scope
Visual.Acquire	Acquire a visual handle for the current resource.	C
Visual.Release	Release one owned visual handle.	C
Visual.Clear	Remove all commands for one owned handle.	C
Visual.BeginUpdate	Begin a batched retained-handle update.	C
Visual.EndUpdate	End a batched retained-handle update and apply once.	C
Visual.Line	Add one world-space line segment.	C
Visual.WireBox	Add one wireframe box.	C
Visual.WireSphere	Add one wireframe sphere.	C
Visual.Marker	Add one retained marker visual.	C
Visual.GetState	Read runtime visual counters.	C

Retained Model

Visual is retained per handle:

1. Acquire handle once.
2. For rebuilds, prefer BeginUpdate -> Clear -> add lines/wires -> EndUpdate.
3. Keep handle alive while overlay should exist.
4. Release on shutdown (optional; runtime also auto-cleans by resource ownership).

For stable overlays, do not acquire/release every frame. For larger retained overlays, do not rebuild one command at a time without batching.

Visual.Acquire

C Client Only

local handleId, err = Visual.Acquire({
  reason = "map_editor_world_overlay"
})

Options:

• reason (string, optional)

Returns:

• handleId (string | nil)
• err (nil | string)

Visual.Release

local err = Visual.Release(handleId)

Returns:

• err (nil | string)

Visual.Clear

local err = Visual.Clear(handleId)

Returns:

• err (nil | string)

Visual.Line

local err = Visual.Line(handleId, {
  from = { x = 0, y = 2, z = 0 },
  to = { x = 32, y = 2, z = 0 },
  color = { r = 0.7, g = 0.8, b = 0.9, a = 0.3 },
  depthTest = true
})

Options:

• from ({x,y,z} required)
• to ({x,y,z} required)
• color ({r,g,b,a} or color string, optional)
• depthTest (boolean, optional, default true)

Visual.BeginUpdate

local err = Visual.BeginUpdate(handleId)

Begins a batched mutation scope for one retained handle.

Use this before clearing/rebuilding many line, wire, or marker commands.

Visual.EndUpdate

local err = Visual.EndUpdate(handleId)

Ends a batched mutation scope for one retained handle.

When the outermost update scope ends, the runtime rebuilds the retained mesh once.

Visual.Marker

local err = Visual.Marker(handleId, {
  id = "editor_marker_preview",
  markerType = "cylinder",
  position = { x = 12, y = 2, z = 8 },
  scale = { x = 3, y = 4, z = 3 },
  color = { r = 0.98, g = 0.72, b = 0.18, a = 0.88 },
  opacity = 0.88,
  emission = 1.0,
  billboard = false,
  visible = true,
  effectiveVisible = true
})

Options:

• id (string, optional)
• markerType ("cylinder" | "arrow" | "corona" | "ring", optional, default "cylinder")
• position or center ({x,y,z} required)
• scale or size ({x,y,z} required)
• color ({r,g,b,a} or color string, optional)
• opacity (number, optional, default uses color alpha)
• emission (number, optional, default 1.0)
• billboard (boolean, optional; typically true for corona)
• visible (boolean, optional, default true)
• effectiveVisible (boolean, optional, default visible)

Visual.WireBox

local err = Visual.WireBox(handleId, {
  center = { x = 12, y = 2, z = 8 },
  size = { x = 4, y = 2, z = 4 },
  rotation = { x = 0, y = 0, z = 0 },
  color = { r = 0.5, g = 0.76, b = 1.0, a = 0.8 },
  depthTest = true
})

Options:

• center ({x,y,z} required)
• size ({x,y,z} required)
• rotation ({x,y,z} in degrees, optional)
• color ({r,g,b,a} or color string, optional)
• depthTest (boolean, optional, default true)

Visual.WireSphere

local err = Visual.WireSphere(handleId, {
  center = { x = 20, y = 2, z = 8 },
  radius = 2,
  segments = 20,
  color = { r = 0.95, g = 0.75, b = 0.45, a = 0.8 },
  depthTest = true
})

Options:

• center ({x,y,z} required)
• radius (number required)
• segments (number, optional, clamped to safe range)
• color ({r,g,b,a} or color string, optional)
• depthTest (boolean, optional, default true)

Visual.GetState

local state, err = Visual.GetState()

State fields:

• activeHandleCount
• totalLineSegmentCount
• totalMarkerCount

Ownership Rules

• resource can mutate/release only its own handles
• handles are cleaned automatically on resource unload
• server-side Lua has no Visual API

Errors

Current error set includes:

• ERR_INVALID_HANDLE
• ERR_INVALID_STATE
• ERR_NOT_FOUND
• ERR_PERMISSION_DENIED
• ERR_INVALID_FROM
• ERR_INVALID_TO
• ERR_INVALID_CENTER
• ERR_INVALID_SIZE
• ERR_INVALID_RADIUS
• ERR_INVALID_POSITION
• ERR_INVALID_SCALE