Docs / World
The edge of the world
Every map has an edge, even one ringed by cliffs or sea, and a bug — a gap between two pieces, a hole in the ground, a push at the wrong moment — will find it. WorldBoundary is the edge every game needs and none should have to build: a shell round the whole map that a body walks up to and no further, and a net under the ground that catches anything that falls through it. BoundaryRenderer draws it, in a look you choose.
Its shape
A boundary is a footprint on the ground and a profile over it.
- The footprint is a rectangle with rounded corners:
center,halfSizeandroundness(0 square, 1 as round as the shorter side allows — a circle when the footprint is square). .domewalls rise straight tospring, then curve over into a roof that crownsheightoverbase. Over a long footprint every side curves in by the same amount at the same height, so a long map gets a long dome..wallsrise straight to a flat ceiling atheight.
base is the floor of the shell, below the lowest ground. Nothing is kept above it: what goes under it has fallen out of the world, and is caught rather than stopped.
The easy way to make one is to fit it to the world's extent:
let edge = WorldBoundary.fitted(minimum: groundMinimum, maximum: groundMaximum) // a dome, softly rounded
fitted puts the footprint a meter inside the ground's edge, so the last meters of a ground that ends are never reached, the floor 20 meters under the lowest point, and the dome curving from the lowest ground — so on a small map it is not already leaning in at head height.
Keeping things in
Give it to the CharacterController.Surroundings your bodies walk in:
var world = CharacterController.Surroundings(groundHeight: height, meshes: mesh, boundary: edge)
Then, for every body stepped in that world:
- it is kept inside, after everything else that moves it across — walking, a push, a moving platform — so nothing takes it out, and walking into the wall slides along it;
- a fall below
baseis caught: the body is put back on the last ground it stood on, standing and still, andwasCaughtis true for that step. Ground counts as safe once the body has stood on it forCharacterController.safeAfter(a quarter of a second), so a body that slips through a crack the moment it lands is not put back on the crack.safeFeetsays where that is.
OrbitCamera.keepClear(of:deltaTime:) keeps the camera inside the same boundary, so a player backed against the wall sees the world, not the world from outside.
For anything else — a thrown thing, a projectile, a camera of your own:
let kept = edge.contain(point, margin: 0.2) // the nearest point inside let hit = edge.exit(from: muzzle, direction: aim, limit: range) // where a line meets the wall, or nil if edge.isBelowFloor(crate.position) { crate.reset() }
Drawing it
let edgeRenderer = try BoundaryRenderer(device: device, sampleCount: renderer.effectiveSampleCount) renderer.residencySet.addAllocations(edgeRenderer.allocations) // In the scene pass, after the opaque geometry: edgeRenderer.draw(edge, into: encoder, frameSlot: frameSlot, viewProjection: viewProjection, camera: eye, player: playerFeet, time: seconds, brightness: 2.5)
It draws into the HDR scene, tested against depth and never writing it, both faces — it is seen from inside — blended so its glow adds as light does and a haze covers as matter does. brightness scales its color into your scene's light. Like every pipeline, make a new renderer when the sample count changes.
It leaves the encoder with its own pipeline, depth state and argument table bound. Draw it last in the pass, or bind your own argument tables again before drawing anything of yours after it — Metal validation stops a draw that finds this renderer's table where it expected yours.
strike(at:time:) sends a ripple across it from a point — where a round hit it, say — for a second and a quarter.
How it looks
WorldBoundary.Look is a choice per world:
style | .lattice hexagons, .grid squares, .forceField — a lattice under a bright rim where it is seen edge-on, with a current through it — or .haze, a soft wall with no lines |
visibility | .always the whole shell from anywhere, .near only within nearDistance of the player and brightest where they meet it, .hidden never drawn — it still stops everything |
color, opacity | linear color, and how strongly it shows |
patternSize, motion | a cell's size in meters, and how fast it moves |
The default is a quiet lattice seen only up close: an edge to find, not one to stare at. Look.forceField is an energy dome seen from anywhere. Lines fade out once a cell is smaller than a few pixels, so a lattice two hundred meters off is a shimmer rather than moiré.
Saved with Codable, every key optional: a boundary saved before a field was added reads with that field's default, and numbers out of range are clamped.