Log inGet started
Package

outline.module

Newest version

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:

occludedthe rimdefault 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 rimoutline.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 selectionoutline.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()