Outlines
Outline creatures, players and other things so they show through walls, in any colour.
game.Highlight draws an outline round a thing in the world. The outline follows the shape of the model and
shows through walls and trees. It can also fill the model with a colour.
local wolf = game.Creatures:GetNearest("Wolf")
local mark = game.Highlight:Add(wolf, { Color = "Red" })
-- later
mark:Remove()What can be outlined
Anything that has a shape:
- An actor: a creature, a player's character, an item on the ground, a bench, a wall.
- One part of an actor, such as a single mesh. Pass the part in place of the actor.
-- only the body of the nearest creature
local creature = game.Creatures:GetNearest()
game.Highlight:Add(creature.Mesh, { Color = "Pink" })
-- every player's character
for _, character in ipairs(game.Players:GetCharacters()) do
game.Highlight:Add(character, { Color = "Cyan" })
endFor other things, find the actor first. game:FindAll("ClassName") returns every object of a class. It
searches every object, so call it once, not every frame.
A whole kind at once
game.Creatures:Highlight("Wolf", { Color = "#ff7a00" })This outlines every wolf that is here now and every wolf that appears later. It returns a connection. Call
:Disconnect() on it to take the outlines off again.
Options
| Option | What it does |
|---|---|
Color | The outline's colour. "Red" when left out. |
Fill | true also fills the model with colour. true when left out. |
FillColor | The fill's colour, when it should differ from the outline. |
A colour is a name from game.Highlight.Colors, a string such as "#ff7a00", or a table such as
{ R = 1, G = 0.5, B = 0 } with values from 0 to 1.
game.Highlight:Add(creature, { Color = "#00ff66", FillColor = "#ffd60a" })Change many outlines at once
A look is a colour and fill that many outlines share. Change the look and every outline that uses it changes.
local look = game.Highlight:Look({ Color = "Cyan" })
game.Creatures:Observe("Deer", function(deer)
local mark = game.Highlight:Add(deer, look)
return function() mark:Remove() end
end)
-- every deer turns orange
look:Set({ Color = "Orange" })Settings for every outline
game.Highlight:Configure({ Fill = 0.3, Width = 2 })Fill is how strong the fill is, from 0 to 1. Width is the line width, from 1 to 4.
How far an outline shows
The game's outline only draws things within 14 metres of you. Farther away the outline is gone, however the
thing is marked. Range moves that limit, for every outline at once:
game.Highlight:Configure({ Range = 120 }) -- metres
print(game.Highlight:GetRange()) -- 120
game.Highlight:Configure({ Range = false }) -- back to the game's own 14Range goes from 1 to 5000 metres. It is the same for every outline, because the game draws them all in one
pass.
Through walls
An outline shows through walls, and so does the tint of a filled mark. That is how Wax sets the game's outline
up, so a mod needs nothing for it. The game's own setting keeps the tint behind walls for three of the four
filled colours and drops it for the fourth; ThroughWalls = false goes back to that:
game.Highlight:Configure({ ThroughWalls = false })An object whose whole bounding box is hidden is not rendered by this game's engine at all, so it gets no outline, whatever the settings. A bench against the far side of a wall is outlined; the same bench two rooms away shows only the parts whose box reaches past what hides it. The cheaper per-mesh settings and the engine's occlusion-query switch are untried.
A tag with the outline
A mod that outlines something usually names it too. Give the mark a Tag and the text sits over the actor,
shows exactly as far as the outline does, and goes away with it:
local mark = game.Highlight:Add(wolf, { Color = "Red", Tag = "Wolf" })
mark:Set({ Tag = "Wolf Lv 12" }) -- a new text
mark.Tag:SetColor("#ff5555") -- it is a tag, as ui.Tag makes
mark:Remove() -- takes the tag off tooTag takes a text, or the same table of options as ui.Tag: { text = "Wolf", color = "Red", size = 12 }. With a within of its own the tag keeps that range instead of the outline's. A tag made on its
own with ui.Tag follows the outline's range with outline = true.
Before this, a tag made with ui.Tag showed up to 100 metres while the outline stopped at 14, so a far creature
had a name over it and no outline round it.
Limits
Wax uses the outline that the game itself draws. That gives it these limits:
- There is room for four colours with a fill and three colours without one at the same time. A colour counts once, however many things use it. When there is no room left, the nearest colour in use is shown.
- An outline shows through walls, whole, unless
ThroughWallsis set to false. - Outlines reach 14 metres unless
Rangesays otherwise, and every outline has the same reach. - Trees, rocks and bushes cannot be outlined one at a time.
- The outline needs your character. It is not drawn at the space station.
Example: outline what you pick
local look = game.Highlight:Look({ Color = "#ff7a00", Fill = true })
local watch = nil
local window = ui.Window({ title = "Outlines", width = 320, height = 220 })
window:Dropdown("Kind", game.Creatures:GetLiveKinds(), nil, function(kind)
if watch then watch:Disconnect() end
watch = game.Creatures:Highlight(kind, look)
end)
window:Color("Colour", "#ff7a00", function(color)
look:Set({ Color = color })
end)