Ductane v1.4.0
Contents

Docs / World

Showing the way

A player who asks where to go wants two things: the way there, and what is around them on the way. Waymark is the first — a line over the ground from where they stand, along the way they can walk, and a beam of light standing up from the place, for a few seconds. WaymarkScan is the second — a ring sweeping out over the ground from where they stand, and everything it passes that is worth finding outlined through walls, with an icon over it and how far off it is. Both are values with no GPU in them: your game makes and steps them, and WaymarkRenderer and WaymarkScanRenderer draw them.

The way

Waymark.way(from:to:grid:surface:) finds the points of the way over a NavigationGrid — round walls, up stairs — and straight on where the grid ends. Make the mark from it once, and step it:

let way = Waymark.way(from: feet, to: target, grid: grid, surface: groundHeight)
var mark = Waymark(way: way, target: target, facing: aim, surface: groundHeight, look: look, kind: class="p">"objective")
// each step
mark.step(deltaTime: deltaTime)
if mark.isOver { /* drop it */ }

When the way starts behind the player it is begun in front of them and swung round to it, so the line is seen leaving (Look.turnsToFace). It sweeps out at Look.sweepSpeed, pulses run along it, and it all fades at the end of Look.duration — fifteen seconds unless the look says otherwise.

Its look

A Waymark.Look is a value a world saves and an editor sets, as WorldBoundary.Look is: the pattern (dots, dashes, arrows, chevrons or a line), floating or flat on the ground, its color, width, spacing, roundness and glow; the beam's color, height, width and rising bands; the sound heard as it appears (WaymarkSound makes it, so nothing is shipped); and the scan's. A world's look is WorldFile.waymark.

Kinds say what each kind of place looks like: Look.kinds, by name in lower case. A Kind has an icon, a color — a path leading to that kind is drawn in it, and its icon too — and whether a world's markers of that kind are found by a scan. Every look starts with objective, ping, collectible, loot and enemy. Pass the kind when you make the mark (kind:), or ask look.leading(to:); a kind with no color keeps the line's.

The scan

Send one with the way, from where the player stands, and step it with what it can find:

var scan = WaymarkScan(from: feet, look: look)
// each step
scan.step(deltaTime: deltaTime, findables: things)
let shown = scan.shown(things, from: eye)   // how much of each outline and icon shows now, and how far off

A thing is found as the ring crosses it, across the ground from where the scan set out, and shown where it is from then on — moving or not. One added behind the ring, or one that walked in behind it, is not found. Each stays outlined for Scan.holds seconds, its icon Scan.iconLinger seconds longer, and the scan isOver once the last icon has gone. The ring reaches Scan.reach (50 meters) at Scan.speed (50 meters a second).

What a scan finds

What the world tags, plus what your game adds. Findables.inWorld(_:propURL:propBounds:) gives a world's own: its markers of every kind whose markers is on, and every placement of a prop in WorldFile.found, each outlined as that prop. Your game registers its own in a Findables — Unity's and Unreal's "scannable" component:

var things = Findables()
let id = things.add(kind: class="p">"enemy", at: feet, top: 2.1)
things.move(id, to: newFeet)          // as it moves
things.remove(id)                      // when it is gone

Their icons and colors are the world's, by kind — your game says what a thing is, the world says how it looks.

Drawing it

WorldRenderer does it all: sendScan(from:look:), stepScan(deltaTime:), findables for your own things, and scanViewer for where distances are measured from. It finds what its scene tags, and outlines tagged props as it draws them.

A renderer of your own makes a WaymarkScanRenderer. Outlines come from a mask: each frame, before the scene's pass, hand encodeMask(_:viewProjection:width:height:frameSlot:into:) the triangles of everything shown with an outline — a Findable.MaskDraw names vertices you already have on the GPU, positions first in each vertex, so a skinned figure's posed buffer works as it is. Then, in the scene's pass after the opaque geometry, draw(_:shown:surface:mask:into:frameSlot:viewProjection:camera:viewportSize:) draws the ring over surface with a faint curtain above it, a band round each shape in the mask, and the icons with their distances, a fixed size on screen and over everything. Make the mask resident when it is made: allocationsChanged tells you.

The mask is drawn whatever stands in front of a shape, so an outline is seen through walls — that is the point. It is the view's size: a renderer that draws its scene smaller than its drawable passes the scene's size.

See also Finding a way, Worlds from a file and Drawing a world.