Docs / World
Worlds from a file
WorldFile describes a world the way a game reads it: every prop placed and what it wears, the ground, the sky and its clock, lights, water, streams, effects, weather, sounds, the world's edge, and the scene's markers. A world editor writes one into a scene package. WorldPackage opens that package, so your game draws the same prop files the scene references and shows what the scene's author saw, without the editor.
It is a different thing from a level. Level is the engine's own JSON format, which a game edits in place with LevelEditor. WorldFile is what a separate world editor exports for a game to read.
Opening a package
A package is a .usdz holding the scene, every prop it places along with their textures, and the description at game/world.json (WorldPackage.descriptionPath). The ground and collision shapes are binary files beside it. Ship the package as a resource and open it:
// your game let url = Bundle.main.url(forResource: class="p">"Meadow", withExtension: class="p">"usdz")! let package = try WorldPackage(contentsOf: url) let world = package.world
It is unpacked once. MeshLoader and TextureStore read files by URL, and a prop inside a .usdz has no URL of its own. So the package is unpacked into a folder in your app's caches (WorldPackage.defaultCache, inside the container when sandboxed). On later launches the unpacked copy is used as is. A package of another size or date unpacks again and replaces the old copy. A folder holding the same files (a package already unzipped) is read in place. Pass cache: to unpack somewhere else.
A package is data from anyone. An entry naming a path outside the package is refused (OpenError.unsafeEntry) and never written. WorldFile.read(_:) checks every index into props, every path the description names, and the ground's size, so nothing read through a package traps, overflows or reaches outside. A description newer than the engine reads is refused with ReadError.newer(_:). A package without a description throws OpenError.noDescription.
What it holds
Coordinates are the scene's: meters, Y up. Nothing is turned or mirrored on the way in. Only name, props and placements are required. Anything a file leaves out is empty, not an error.
| Field | What it is |
|---|---|
props | the prop files, by path inside the package, each named once; everything else refers to them by index |
placements | [Placement]: a prop, a transform (sixteen numbers as matrix), the materials it wears instead of its own, and scattered for one copy of a brushed group |
walkedThrough | the props a walker passes through, such as grass, reeds or a liquid's surface; everything else is solid |
collisionShapes | for props whose maker drew a simpler shape to walk on, the path of its triangles |
characters | props that are figures with a skeleton, to draw skinned |
ground | a Ground: a square grid centered on the origin, with files for heights, colors, holes, painted weights and puddles |
sky | a Sky: the hour, fog, a sun by hand, the clock and the aurora |
lights, waters, streams, effects | point lights, still water as rectangles at a level, stream surfaces, and living effects with the ParticleRecipe they move by |
markers | [Marker]: a kind, a name, a position, a yaw and values |
boundary | a WorldBoundary, or nil |
waymark | a Waymark.Look: how the way to a place is shown and the scan sent with it, or nil for the engine's look (Showing the way) |
found | the props a scan finds, by index into props, with the kind each is found as |
sounds | Sounds, or nil for a silent world |
weather | a Weather, or nil for a clear sky |
foliage, sway | what each prop does through the year and in the wind, only for the props that change |
liquids, grime, effectMeshes | materials drawn as a liquid, materials dirtied by where they are, and the meshes effects throw |
Drawing it
WorldRenderer draws a package whole — ground, props, sky, weather, fog, seasons — as the editor that made it drew it: try world.show(package). See drawing a world. Draw it yourself only for a look of your own.
To draw it yourself, load each prop by its URL, then draw each placement with its transform:
// your game for index in world.props.indices { meshes[index] = try MeshLoader.load(url: package.propURL(index), device: device, vertexDescriptor: vertexDescriptor, semantics: semantics) } for placement in world.placements { draw(meshes[placement.prop], at: placement.transform) // your game's }
A placement also gives its position, its scale, and turnAndLean for a game that places things by turn rather than by matrix. Scattered copies are many of the same prop, so draw them as many copies and cull them (see culling). propFolder(_:) is where the textures a liquid or grime look names are found.
package.ground() reads the ground into a WorldGround. It gives you height(x:z:) to stand on and mesh() to draw, both made from the same grid, so what the player stands on is what they see. Over a hole, height(x:z:) returns WorldGround.underHole so that a walker falls through to the cave floor below. groundWeights() gives the painted layers' shares for a game that paints with its own textures, and WorldFile.Ground.softness(_:softLayers:) says where footprints show.
What stops the author walking the scene stops the player. passesThrough is a Bool for each prop, and collisionShapes() gives each shape's triangles in the prop's own space. A game never decides what is solid itself. Hand the solid placements' triangles to CollisionMesh(placed:) for the character controller.
Lights go to clustered lights, effects to particles, characters to skeletons, and the boundary to the edge of the world.
Markers are your game's
// your game if let start = world.markers(class="p">"spawn").first { player.position = start.position player.yaw = start.yaw }
A marker is a kind, a name, a place, a facing and a few numbers. What a kind means is the game's: where the player starts, where enemies wait, what a mission is for. The engine names no kind. markers(_:) and Marker.is(_:) match a kind in any case.
The sky and the weather
world.sky.daySky is the sky as DaySky draws it. When the world has a clock, set the sky from it each frame with clock.sky(world.sky.daySky, at: now). See the world's clock and the sky by the hour. world.weather is drawn and heard as the weather page describes. Ask current(at:) each frame, using the same clock.
Sounds
Sounds holds loops at places (Point, each with its own reach), ambience over areas (Ambience, with an optional night loop), sounds now and then inside an area (Scattered), the world's music, and the weather's rain, wind, dust and thunder. Points and scattered sounds can be heard .always, by .day or by .night. Soundscape plays all of it as written, so you write no code of your own for it:
// your game let soundscape = Soundscape(audio: audio, music: MusicPlayer()) if let sounds = world.sounds { let failed = await soundscape.play(sounds) { package.url(of: $0) } // files that would not load, and why } // each frame soundscape.setDaylight(Soundscape.daylight(sunElevation: sky.lighting.elevation)) soundscape.setWeather(current, at: now) soundscape.update(listener: eye, forward: forward, up: SIMD3(0, 1, 0), elapsed: deltaTime)
Only what can be heard plays. A loop runs only while the listener is within its reach, so a world with hundreds of loops costs a handful of voices. What stays the game's is when the world is heard at all (pause() under a menu, then resume()) and any music that follows play. For that, leave out music: and drive your own player. See audio.