Dicey Table

Workflow: Importing a Model

Steps#

  1. In the asset explorer, switch to the Models folder (or any folder you want it filed under).
  2. Click Upload, or drag your file(s) onto the explorer. Select the model plus any companion files it needs in the same action:
    • A .glb alone.
    • A .gltf plus its .bin and texture files.
    • A convertible DCC format (.fbx, .obj, .dae, .stl, .ply, .3ds, .3mf, .off, .lwo, .x) plus its .mtl/textures — see Working with models for the full list.
  3. For a convertible format, watch the status line — it reports each conversion stage (loading the converter, converting, packing) and can take several seconds for a dense mesh.
  4. Check the status line for what was extracted: the importer lifts the model's materials and embedded textures into the project automatically, so they become editable assets rather than staying locked inside the GLB. It reports how many of each, plus anything it skipped (materials no mesh uses) or could not represent. Your model still renders exactly as it did — nothing is assigned for you. See Assigning and editing materials.
  5. Once it lands in the explorer, double-click it to open the Model editor tab and check Errors & stats. Address any warnings you care about now — high triangle count, oversized embedded textures, missing normals — with the matching Optimize action, or decide they're acceptable and move on.
  6. Still in the Model tab, give it a collider if the fitted box is wrong for it. Select the Collision row in the model tree, pick a shape, and use Fit to bounds as a starting point. For a mesh-derived collider, check the Collider tris figure in Errors & stats — the collider budget is 2,000 triangles, not the render budget's 150,000 — and use Simplify to fit if you are over, which decimates and bakes a <stem>.collider.glb beside the model in one step.
  7. Add any trigger volumes the model needs, from the Triggers row. They fire enter/leave events for scripts and mods and do nothing else — skip this unless a rule will subscribe.
  8. Press Save on the save bar. Collider and trigger edits live in the tab's draft until you do; nothing else commits them.
  9. Drag the model from the explorer onto the viewport, or click it, to place it as an Entity in the scene.
  10. Select the placed Entity and confirm its PIECE kind, transform, and (if it's meant to be a custom playable piece) its spawn defaults in the Model editor's Spawn defaults form.

Definition of done#

The model appears in the Hierarchy under Entities (N) as a new Entity with render and collision, positioned where you dropped it, and its Model tab shows no unaddressed errors (an error, unlike a warning, means the model couldn't be parsed at all).

If it fails#

  • "Only binary .glb models can be inspected." The file isn't a well-formed GLB container — if you uploaded a .gltf, make sure you selected its .bin file alongside it so the importer could pack it; if you uploaded a convertible format, check the conversion status line for an assimp error first.
  • A convertible model converts but textures are blank/white. The referenced texture files weren't in your selection — re-select the model with every image it references alongside it.
  • Draco warning with empty stats. Expected — see Working with models. The model still renders fine on the table; decompress it outside the editor if you need Optimize/inspection.
  • A format not on the supported list. Re-export from your modeling tool as .glb — the most reliably supported target — rather than fighting an unsupported interchange format.
  • The collider does not match the shape you chose. The COLLISION panel spells out why: a triangle mesh on a moving piece falls back to a convex hull, and geometry that has not loaded yet is pending rather than broken. See COLLISION.
  • You edited a collider and nothing changed on the table. Edits apply to future spawns. To change pieces already out there, use Re-apply to N objects on the collision panel — it is host-only, and it skips (and names) anything currently held.

See also#