Manual
Manual
Models
A model is a file of meshes, materials, a skeleton and clips made in a modeling tool. This page covers the formats Abyss reads, each import setting, a model's parts in the Project panel, editing several models at once, and loading a model's pieces from code. For placing a model in a scene, see Models are prefabs.
Model files
Put model files anywhere in your project's assets/ folder.
| Format | Extensions | Units and axes |
|---|---|---|
| glTF | .gltf with its .bin and images beside it, or .glb with everything inside | Meters, +Y up, as the format says |
| FBX | .fbx | Converted as it is read: a file authored +Z up in centimeters, as Blender and 3ds Max write one, arrives upright and at its size in meters |
| OBJ | .obj, with the .mtl its mtllib line names, or the .mtl of its own name beside it | Read as meters, +Y up, since an OBJ says neither |
Every model is imported in meters with +Y up, so a model from any of these tools stands up the right way in the scene with no node turned. An FBX's or an OBJ's materials are made into the engine's own: its color and texture, its roughness from its shininess, how much is seen through it, its normal map and its light. An OBJ with no .mtl imports white, and an edit to its .mtl imports it again.
How a model is imported
The model's file stays as you exported it. Its meshes are imported from it into the project's cache/ folder, in the form the engine draws, with their normals and tangents already made, and the images it carries inside it are imported as textures beside them. Then the editor builds the model's prefab from its nodes. A model is imported again only when its file, a file it reads beside it, or its settings change, in the background; Importing explains the cache, the spinner on a tile and the status bar.
A model is always drawn from its import, never from its source. While its first import runs, its meshes are drawn with nothing, and its Inspector says so. A model that cannot be imported says why, in its Inspector and in the Logs panel.
Pick a model in the Project panel and the Inspector shows its import settings, headed with its name and model importer, in these sections. Change them, then click Apply to import it again, or Revert to go back. The editor asks about settings you changed and did not apply before the Inspector shows something else, and before you quit. When the import lands, every instance of the model in the open scene follows it.
Scene
| Setting | What it does |
|---|---|
| Scale Factor | How many times larger the model is than its file says, greater than zero. It scales every position and every node's place, so the model grows as a whole. |
| Bake Axis Conversion | Turns the model half a turn about Y as it imports, from glTF's front, +Z, to the engine's forward, −Z, as Bevy's is. An FBX or an OBJ is in glTF's terms once read, so this means the same for every format. |
| Preserve Hierarchy | Gives the model's prefab a root of its own, named after the file, even where the file has one node at its top. It changes only the prefab, and imports no meshes again. |
Geometry
| Setting | What it does |
|---|---|
| Index Format | Auto: two bytes an index for a mesh of 65,535 vertices or fewer, four for a larger one. 16 bits: two bytes wherever they can name every vertex, four for a mesh they cannot. 32 bits: four bytes always. |
| Normals | Import: the file's, calculated for a mesh that has none. Calculate: worked out again, whatever the file has. None: no normals, for a mesh drawn unlit. |
| Smoothing Angle | 0 to 180 degrees, 60 unless you change it: faces that meet flatter than this are smoothed together, and across a sharper edge each face keeps its own normal. Grayed unless Normals is Calculate. |
| Tangents | Import: the file's, calculated by MikkTSpace for a mesh that has none. Calculate Mikktspace: calculated whatever the file has. None: sixteen bytes a vertex fewer, for a mesh no normal map is drawn on. Grayed when Normals is None. |
A material with a normal map needs tangents, which is why every mesh gets them unless you say None. A mesh with no texture coordinates can have none, and the log says so.
Baking
A package can work something out of each mesh as the model is imported, so a game reads it instead of working it out as it starts. Each such package adds a tick to a Baking section, named after it. With the Physics 3D package, Physics 3D bakes the shape a Mesh Collider 3D of the model's meshes uses; see 3D physics bodies. The section is not there when no package bakes anything.
Animation
| Row | What it is |
|---|---|
| Import Animation | Reads the model's clips beside its meshes. Off, the clips are left out, but its skin is still read, so clips from another file can move it. |
| Rig | What its meshes bend by: No skin, or how many skins and joints. |
| Skeleton | The model these clips are for, where they were exported in a file of their own. See Clips for another model. |
Under them is a row for each clip, with its Length and a Loop tick, off until you tick it, as most clips a model brings play once. Pick a clip's row to see its timeline and hold the preview where its playhead is. Events, curves and sync markers on a model's clips are covered in Animation clips.
Materials
A slot for each of the model's materials, by its name in the file, or its label, such as Material0, where the file names none. A slot starts as The model's own: the material the file describes, drawn as the file says. Drop a material file on a slot, or pick one with its button, and once applied that material is drawn wherever the model's material was. The prefab is made again with it, without importing the meshes again, and every instance follows.
Extract Materials writes each of the model's materials as a .mat file in a Materials folder beside the model, with the numbers and textures the model gives it, and writes out each image the model carries beside them, such as crate_Texture0.png. It then gives each file to its slot, so you edit the model's look as you edit any material (see Meshes and materials). Nothing already there is written over: a name that is taken gets a number after it.
The images a model names in files of their own are found where the model says. A model made on another computer often names folders your project does not have, such as ..\Textures\skin.png; then the image of that name nearest the model is used, looking in fewer folders up first, then down. An image the project does not have yet is named in the log, and the model is drawn without it until you add it, when its prefab is made again.
An image file the model names is imported by its own settings, not by how the model uses it. Set a normal map's Texture Type to Normal Map yourself (see Textures). An image carried inside the model is imported as its use says.
Meshes
Under Apply and Revert, a row for each mesh the import made: its name and its label, such as Mesh0/Primitive0, its vertices and triangles, what each vertex holds, the size of its indices, its memory and its size in meters. A mesh drawn with several materials is a mesh for each, one material each. The section ends with how many textures the model carries were imported, and says when some could not be, which the Logs panel explains.
Preview
At the foot of the Inspector, the model is drawn by a camera of its own. Drag over it to turn round the model, and turn the wheel to move in and out. It shows the model as it was bound, or posed where the picked clip's playhead is, playing as the clip plays.
A model's parts in the Project panel
A model's tile has an arrow that unfolds its parts beside it: each mesh, each material, each clip and its skeleton, each with its own icon. Pick one, and the Inspector shows the model's settings with that part:
| Part | What the Inspector shows |
|---|---|
| A mesh | First, its counts, and its key where the model is addressable |
| A material | First, its slot, then what the model's file says of it: Color, Metallic, Roughness, Transparency, Double Sided, Unlit and each image by its slot |
| A clip | The model, with the clip picked on its timeline |
| The skeleton | First, its tree of nodes, each a bone or a mesh |
Drag a part onto a slot that takes it: a mesh onto the Mesh slot of a Mesh 3D section, a material onto the Material slot of a Mesh Material 3D section, or a clip onto an animator state's Clip slot. A model that holds one clip, as a file of clips exported on their own often does, can be dropped on a Clip slot itself.
A part is not a file. It cannot be renamed, moved or copied, and Show in Explorer shows its model.
Clips for another model
Animations are often exported a file each beside their model, such as Dino_Idle.fbx beside Dino.fbx. A clip moves the bones under an animator by their names, so a clip from any file plays on any model whose bones it names. Where the paths differ, a clip still finds its bones: by the whole path where the skeleton has it, else the one bone whose path ends as the clip's does, else the one bone of its name. The animator says once which bones its skeleton lacks.
The Skeleton slot in the clip file's Animation section names the model its clips are for. Drop that model on it, or pick it from the list, which offers every model of the project but this one. Then:
- the preview plays the clips on that model;
- a clip's row lists its Bones, each beside the bone of the model it moves, with None of its name in amber for one it finds nowhere;
- an animator state's Clip list groups them under that model, beside its own clips.
The Skeleton is the editor's alone, so applying it imports nothing again, and a game plays the clips the same with or without it.
Several models at once
Pick several models in the Project panel, and nothing else, to edit their settings together: glTF, GLB, FBX and OBJ in any mix. The Inspector is headed with how many and names them. Each setting shows the first model's value, and a dash where any of the others differs. A change is made in every model. Apply writes each one you changed and imports it again, unless only its Skeleton changed, and Revert puts every one back.
Together you can change the Scene, Geometry and Baking settings, Import Animation, the Skeleton, a Loop tick for every clip of every model, and Extract Materials, which writes each model's materials beside it and passes over those with none. The preview, the meshes, the clips' rows and the material slots are shown only for one model at a time.
To give a model's clip files their Skeleton in one go, pick the model and all its clip files, then pick the model in the Skeleton slot. The model keeps its own skeleton, and each clip file is given the model.
Models in code
A model's key is a prefab's key, PrefabAddress, and holds the keys of its clips, its meshes under Meshes and its materials under Materials. The model has to be addressable; see Keys in code.
PrefabId door = context.Assets.LoadPrefab(Addresses.Models.Door); // the whole model, as a prefabClipId open = context.Assets.LoadClip(Addresses.Models.Door.Open); // one of its clipsMeshId frame = context.Assets.LoadMesh(Addresses.Models.Door.Meshes.Frame); // one of its meshesMaterialId wood = context.Assets.LoadMaterial(Addresses.Models.Door.Materials.Wood); // one of its materials
ulong made = context.Commands.Instantiate(door, position, rotation);A mesh's key is named after its mesh, and a mesh drawn with several materials has a key for each part, named after both, such as BodySkin. A material's key loads what the model is drawn with: the material file its Materials slot gives it, or the model's own. Where the model is addressable, the Inspector shows each mesh's and each material's key, ready to copy. Instance prefabs from code covers Instantiate.
A build packs each model the game reaches as it was imported, with its meshes, the images it carries, its clips and its prefab, so a built game reads no model file. A game played from its folders with dotnet run draws its models from the imports the editor made in the project's cache; a model the editor never imported is not drawn, and the log says so.
What a model leaves out
- Lights and cameras. A node with a light or a camera is an empty entity in the prefab: add the light or the camera in the scene.
- Blend shapes, also called morph targets, are not imported, nor the clips' channels that move them.
- More than four bones to a vertex. Each vertex is drawn by its four strongest bones, their weights shared between them.
- Some of what a material can say. A texture's transform and a second set of texture coordinates are not read. An FBX's roughness and metalness in textures of their own, and an opacity map, have no place in the engine's material. A node mirrored by a negative scale draws its faces inside out.
- An OBJ's units and axes, which the file does not say: it is read as meters, +Y up, so set its Scale Factor if it was made otherwise.
In the Scripting API
- PrefabAddress, MeshAddress, MaterialAddress and ClipAddress: the keys of a model and of its parts.
- AssetAccess:
LoadPrefab,LoadMesh,LoadMaterialandLoadClipfrom a system or a flow. - ImportSettings: a model's import settings, with ImportIndexFormat, ImportNormals and ImportTangents.
- ClipSettings: how a model's clips are imported, and the model they are for.
