Docs / World
Drawing a world
WorldRenderer draws a whole world: the painted ground with its holes, puddles and fallen leaves; every placed prop and scattered copy, culled and drawn at the right level of detail, with far copies drawn as far pictures; the sky, the night sky and volumetric clouds; the sun's shadows; point lights; still water and streams; living effects; the weather, including rain, lying snow, snow built up on props, wet ground, footprints and lightning; volumetric and ground fog; fall colors; and foliage moving in the wind. A world editor can draw its viewport with the same renderer, so what the author sees is what a player sees.
It is a GameLoop. Give it to the engine as your game, or call its GameLoop methods from your own loop and draw your own things after them.
Showing a package
A world exported as a scene package (see worlds from a file) is one call:
// your game let engine = try FrameRenderer(device: device) let world = try WorldRenderer(engine: engine) engine.game = world let url = Bundle.main.url(forResource: class="p">"Meadow", withExtension: class="p">"usdz")! try world.show(WorldPackage(contentsOf: url)) { failures in for (prop, error) in failures { print(class="p">"\(prop.lastPathComponent): \(error)") } }
show(_:loaded:) sets the scene from the package (WorldScene(package)), shows its ground (package.groundSource()), wires up the liquids, grime and collision shapes it describes, and loads the props in the background. Props appear as they arrive. When they are all in, loaded hears the ones that failed, and the far shadow cascade is fitted to the whole world (fitExtent()).
Each frame
Set camera before the frame is drawn. A WorldRenderer.View is an eye, a target, a distance, a view matrix, a vertical fieldOfView and a nearZ. The projection has no far plane (reversed-Z). From a camera, use the convenience initializer:
// your game, in its step or frame
world.camera = WorldRenderer.View(camera, fieldOfView: 60 * .pi / 180)
distance is where the fog and the editor's grid count from. A first-person eye uses 0. An orbit camera uses its distance to the target, so a world seen from high above is not lost in its own fog.
The clock. scheduleTime is the world's clock in seconds since 1970, and is what the sky's hour and season and a weather schedule are read at. Leave it nil for the real time (UTC), so everyone on a map shares one sky without a server. A game with a server sets the server's time. weatherTime is the clock lightning strikes by. Pass it to a Soundscape so the thunder agrees with the flash. frameWeather and frameDaySky are the weather and sky being drawn.
Settings. graphicsSettings takes a GraphicsSettings: anti-aliasing, shadows, render scale, frame rate, clouds, fog, snow depth and texture quality. A change is applied at the start of the next frame. Pipelines and shadow maps that are replaced are kept until no frame in flight still uses them.
Walking it
The renderer knows the ground and every prop, so it answers what a walker needs. groundHeight(x:z:) is the ground's height under a point, or nil off the ground or over a hole. collisionTriangles(of:) is a loaded prop's solid triangles in its own space. That is the shape its maker drew to walk on where there is one, and otherwise the prop as drawn without its cut-out leaves and grass. bounds(of:) gives a prop's box. Build a character controller's world from them, leaving out what WorldFile.walkedThrough lists.
Footprints come from footprints, a FootprintTrail. Step your characters' feet into it and the renderer shows the prints in snow and soft ground, wiped by the weather.
What it draws from
scene is a WorldScene:
| Field | What it is |
|---|---|
placements | [Placement]: a prop file, a transform, its largest scale, and the materials it wears from other files |
scatters | [Scatter]: groups of copies of a few prototypes, each copy a Copy (a prototype, a transform, a scale) |
sky, groundGrain | the WorldFile.Sky, and a fine grain on the ground near the eye |
weather | the Weather as set. The frame's is weather.current(at:) at the clock |
waters, streams | still water as rectangles at a level, and stream surfaces |
effects, effectMeshes | living effects, each with the recipe it moves by, and the meshes some recipes throw |
lights, boundary | point lights, and the world's edge, already fitted |
foliage, sway | what the season and the wind do to each prop file |
Set it again whenever it changes. The renderer compares the new scene with the last one and redoes only what changed. A placement dragged updates that placement's copy, and copies moved by a brush update those copies. Anything else gathers the copies again. When you know exactly which copies moved, moveScatteredCopies(_:in:) skips even the comparison.
The ground is handed over apart, as a WorldGroundSource: its size, resolution, heights and holes, a lineage and revision that identify it, and methods that write its vertices and where puddles gather. showGround(_:changed:) writes only the WorldGroundRegion that changed, so an editor's brush can show the ground sixty times a second. The renderer never keeps the ground value itself, because keeping it would make every brush tick copy it.
Props
Props load from their files through MeshLoader, off the main thread (loadPropsInBackground(_:)), or at once (loadPropsNow()) for a check drawn off screen. Their textures are compressed for the GPU and cached (CompressedTextures) unless the renderer is made with textureCache: nil. propFiles says which file a prop is drawn from and where its own coarser levels are (PropLevels). A prop without levels of its own is simplified as it loads (see level of detail). reload(_:) reads changed files again and frees what they held on the GPU.
Diagnostics
drawn counts the last frame's draws and triangles, in view and in shadows. refusedObjects counts what did not fit in the frame's uniforms. graphicsMemory() reports what the GPU holds for the world. takeFrameAverage() returns the frames' average since it was last called. Switches like drawsEffects, castsShadows, hidesScattered, drawsFarPictures, drawsFallColors, drawsSnowCaps, cloudsAsked and fogAsked turn one thing off at a time to measure what it costs. pngFrame(width:height:) draws a frame off screen (see recorded frames).
For an editor
showsGrid draws faint meter lines on the ground, and a grid where there is no ground. previewsClock set to false holds the hour as set while the clock's latitude and season still apply. showsWeather set to false leaves the falling weather out of a view being worked in. showsWholeBoundary shows all of the world's edge. encodeSilhouette(of:wearing:transform:scale:into:) draws a prop's shape into a texture so a selection outline can be drawn round it over the finished frame.
Its per-frame loops are built optimized even in Debug. Choosing which of tens of thousands of copies a frame draws runs in the DuctaneCulling target, which is compiled with -O in every configuration. Unoptimized, a 400 m zone of 48,000 copies spent 85 ms of every Debug frame there, against 4 ms optimized.