Troubleshooting

Every entry here is a real, current gap — not a hypothetical — sourced from docs/feature-plans/edit-mode/IMPLEMENTATION-STATUS.md's tracked follow-ups and verified against the current code. Each has a workaround. If something you hit isn't listed here, it may be one of the known scripting limitations instead.

Clearing a material doesn't visually revert until reload#

Symptom: you clear a material from an object or a room surface (the Material box's ×), and the old look stays on screen instead of reverting to the default board/token/surface appearance.

Cause: the runtime's material-apply path only overrides the look when a material id resolves; an empty id is a no-op rather than a revert (applyAssignedMaterial: if (!materialId) { return; }).

Workaround: reload the scene. The document itself is correct the moment you clear the field — only the live rendering is stale. See Assigning and editing materials for the full explanation.

Manually created empty folders disappear on reload#

Symptom: you use New ▾ ▸ Folder in the asset explorer to organize your project tree, and the empty folder is gone the next time you load the project — even though you didn't delete it.

Cause: there's no backend record for a folder — a folder only exists as a path prefix shared by real assets. A folder with nothing in it yet is client-only UI state.

Workaround: move (or upload) at least one asset into the folder before you rely on it surviving a reload — once an asset's path includes it, the folder is real.

KTX2 assets are missing from the Textures tab#

Symptom: a .ktx2 texture you compressed drags and assigns onto material/surface texture slots from the asset explorer grid just fine, but it never shows up in the Textures tab's own list, and its Sampling/WebP panels are unavailable there.

Cause: the Textures tab only lists assets that pass isSupportedTextureContentType — a browser-decodable image format. A GPU-compressed KTX2 container isn't one, by definition, so it's excluded from that list rather than mis-detected.

Workaround: find and manage a .ktx2 asset through the asset explorer grid, not the Textures tab. Assignment and rendering both work correctly either way. See Working with textures.

Saving fails for a deeply nested or long asset path#

Symptom: saving an asset you've organized several folders deep fails with no obvious reason.

Cause: the move/organize route accepts paths up to 1024 characters, but the shared schema that persists an asset reference (modProjectAssetReferenceSchema.path, packages/shared/src/modManifest.ts) caps a path at 180 characters. A path that passes the move but exceeds 180 characters fails at save.

Workaround: keep folder nesting and file names reasonably short — a few folders deep with concise names stays well under the limit. If you hit this, shorten a folder name in the chain rather than the file name alone, since the whole path counts.

AVIF images may not decode on every device#

Symptom: an AVIF image you uploaded previews fine for you but fails to render — or looks broken — for some players or on some devices.

Cause: AVIF upload is accepted, but decode support varies by browser and OS version (notably older iOS). There's no server-side transcode to fall back to — every peer decodes the raw file in their own browser.

Workaround: prefer PNG, JPG or WebP for any texture every peer needs to render correctly — all three have universal decode support across the browsers DiceyTable targets. Reserve AVIF for assets you know only you will see (a private reference image), not shared table assets.

Large-texture compression briefly blocks the editor#

Symptom: clicking Compress to Basis on a 2K+ texture makes the tab visibly freeze for a moment.

Cause: Basis/KTX2 encoding runs synchronously on the main thread — a Web Worker version was attempted, but the Vite module-worker plus the ktx2-encoder dynamic-glue path proved fragile and was deferred.

Workaround: expect a brief pause (worse on larger textures) and don't interact with the tab until it clears — it's a real compute cost, not a hang. Compressing several large textures back to back will feel slower than compressing one; there's no batch/background option today.