outline.module
This package holds more than this page lists. See all of its files in its world.
README.md
outline
The public outline API — mark entities to draw with a coloured silhouette rim.
Its registry (entity id → { color, thickness }) is read every frame by the
@builtin::renderFeatures.outline render feature, which draws a screen-space
jump-flood rim hugging each marked entity's silhouette (uniform width, no gaps on
hard-edge or multi-part meshes). The feature is ensured live on first use, so
outline.set(entity) is all a caller needs. outline.prepare() loads the renderer
in advance; the editor calls it when attaching selection handling.
thickness is the rim's width in output pixels at any resolution and distance,
and its outer edge is antialiased.
What stands in front of the entity: occluded
Each outline states what its rim does where opaque geometry stands between the camera and the entity:
occluded | the rim | default for |
|---|---|---|
"hide" | grows only from the part of the entity the camera sees and stands at that part's depth, so a wall, a floor or any other opaque surface in front of the entity hides its rim exactly as it hides the entity, and an entity hidden entirely draws no rim | outline.set |
"dashed" | is drawn all round the entity, solid where the entity is seen and in dashes of its full colour where something stands in front of it, so the entity stays marked through the wall, over a bright surface as over a dark one, the way an editor marks its selection | outline.setEditorHint |
A game outline (a pickup's glow, a hovered unit) keeps the default "hide". An
outline that has to mark an entity wherever it is, such as a teammate seen
through a wall, states "dashed":
outline.set(teammate, { color = { 0.2, 0.6, 1, 1 }, occluded = "dashed" })
A Model or SkinnedModel drawing its outline from its outline fields states
the same choice in outlineOccluded ("hide" unless set), so a through-wall
marker can be authored as scene data.
Editor hints
outline.setEditorHint(entity, opts) draws the outline the editor uses to mark
an entity out (the selection, a player spawn point). It is drawn on the
EditorUI render layer, so a capture or camera that leaves the editor's chrome
out leaves it out too, it reads "dashed" unless opts.occluded states
otherwise, and it is drawn only in edit mode: the world leaving edit mode clears
every hint, and a call made outside edit mode registers nothing and returns
false, so a hint never draws in play.
An entity's outline lasts as long as the entity: when it is despawned, by
entity.despawn, a parent's cascade, a scene rebuild or reload, its id leaves
the registry, so the feature's per-frame cost follows the outlined entities in
the world. A Model or SkinnedModel drawing an outline from its outline fields
clears it when the component is removed.
local outline = require("modules.outline")
outline.set(entity, { color = { 1, 0.5, 0, 1 }, thickness = 3 })
outline.set(entity, { color = { 1, 0.5, 0, 1 }, thickness = 3, occluded = "dashed" })
outline.clear(entity)
outline.clearAll()