Building Levels
Levels are loaded as GLTF files with a specific structure. This instructs the pipeline how to process the level file.
A level is a collection of individual scenes or "chunks" of static data that may be loaded and unloaded individually. These chunks are defined by the scene's object hierarchy. Naturally a level must contain at least one chunk.
This text will reference a simple level built in blender to illustrate basic features of the level pipeline.
The level itself is represented by the root GLTF node and does not serve any particular purpose. Every child of the root node is treated as an individual scene and will result in a separate asset.
Consider the following hierarchy:
The processing of this level would result in 4 individual scenes:
- Atrium
- Firewall
- Hallway
- LavaPit
Each individual scene is defined by a collection of "category" nodes describing its contents which must be named in a particular way.
Note for the category name, the node only needs to begin with the specified text. For example: Scene and Scene.001 will both be treated the same. This is get around the limitation of nodes not being able to share the same name.
| Category name | Description | Required |
|---|---|---|
| Scene | Contains all nodes which represent objects in the world. | Yes |
| Colliders | Contains custom collision meshes | No |
Consider an expanded view of the hierarchy above:
In examining the image we can see that each chunk contains a Scene node and some contain optional collider nodes.
All children of a Scene Node will be represented as fw64Nodes with their transform setup when the level is loaded into the game engine. Nodes with mesh data will automatically have their mesh property set.
Consider the scene nodes of the Lava Pit:
You can see that the scene contains a mix of empty and mesh nodes. During level processing a header file will be generated which will allow you to access specific nodes in code.
If you know that you will need additional static scene objects at runtime you may specify additional quantities on the scene node. The following custom properties may be attached to a scene node:
| Property Name | Description |
|---|---|
| extraMeshes | will allocate additional mesh slots when loading |
| extraMeshInstances | will allocate additional mesh instances when loading |
| extraColliders | will allocate additional collider objects when loading |
| extraNodes | will allocate additional nodeobjects when loading |
Note that this only allocates space for them, they will still need to be created with the various scene add / load methods
There are a few properties which can be placed on nodes. Properties are added using "Custom Properties" in a node's "Object Properties Panel".
| Property Name | Type | Description |
|---|---|---|
| layers | String | Space separated list of layers to assign this object to. These layers can be used for raycasting or collision related queries |
| collider | String | Contains the name of a Collider to use as a custom collision mesh. Specifying a value of none will not generate a collider even if the node has a mesh attached to it. Specifying a value of transform will create a box collider based on the node's transform. The position will be used as the box center, and scale as the extents. |
| data | Integer | Numeric value that will be places into the data struct of the node in game. This can be useful for a number of things such a denoting the type of the object this node represents |
| mesh | String | Specifies a mesh override. Currently the only supported value is none which will tell the pipeline to ignore the mesh attached to this node. |
Consider the properties for the walls of the fire pit:
We can see here that this node is part of the walls layer and uses the Lava Pit Walls Collision mesh.
Children of the Colliders node contain meshes that can be used as custom collision object. The transform of collision mesh nodes is ignored during processing so they may be positioned anywhere in the blender scene.
It is likely that you may not want the bounding box of a mesh node determined by the mesh itself. This is accomplished by adding a child node whose name begins with Box to the mesh node. The position and scale of this node will be used as the center and extents of the node's bounding.
It is important to note that the values on this node are interpreted in local space, meaning they will be transformed along with the mesh.
In blender, for box to line up as expected, be sure to select "Object (Without Inverse)" when performing the parenting operation.
When exporting the level from blender, ensure that you have checked Include -> Custom Properties from the export options.
