# Workflow: Importing a Model

> The numbered click-path for uploading a GLB, glTF or convertible DCC model, reading its findings, giving it a collider, and placing it on the table.

- Source: https://diceytable.com/docs/editor/workflows/import-a-model
- Last verified: 2026-08-04

## 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](https://diceytable.com/docs/editor/working/models#what-the-importer-accepts) 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](https://diceytable.com/docs/editor/working/materials#materials-from-an-imported-model).
5. Once it lands in the explorer, double-click it to open the [Model
   editor](https://diceytable.com/docs/editor/item-editors/model) 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](https://diceytable.com/docs/editor/working/models#draco-compressed-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](https://diceytable.com/docs/editor/inspector/collision#the-two-refusals-when-a-mesh-derived-collider-does-not-happen).
- **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

- [Working with models](https://diceytable.com/docs/editor/working/models)
- [Item editors: Model](https://diceytable.com/docs/editor/item-editors/model)
- [Where my files live](https://diceytable.com/docs/editor/workflows/where-my-files-live)
