Voxel Template (asset type)

When to use one

• You want a reusable voxel prop (tree, rock, barrel) that many entities share, with edits to the template propagating to every live instance.
• You want a stable identity (a guid) for a voxel grid so the engine's asset-reload machinery can drive the live-link instead of a poll loop.

If you just need a one-off shape on a single entity, use Voxel.createShape — that writes a private dataPath voxbin and never becomes a template.

Where it lives

• Source: Config.get("paths.templates")/<Name>.voxelTemplate/
• Identity: <Name> (the .voxelTemplate suffix strips).
• Folder shape:
  • template.voxbin — the binary grid payload (size, blockSize, palette, flat grid array). Written by saveAsTemplate / copyTemplate. Optional in the structural spec only so the freshly-scaffolded (empty) folder validates; every real template carries it.
  • .metadata — agent-editable tags + free-form fields. Required.

How to create one

From a live shape you authored:

local Voxel = require("@builtin::systems.voxelEngine.voxelEngine")
local shape = Voxel.createShape({ size = { 8, 8, 8 } })
shape:fillBox({0,0,0}, {7,7,7}, "stone")
shape:saveAsTemplate("my_prop")
-- Writes: <paths.templates>/my_prop.voxelTemplate/
--   template.voxbin   (the grid payload)
--   .metadata

Or scaffold an empty one to fill in later:

asset.create("voxelTemplate", "MyProp")
-- Creates: /zero/source/MyProp.voxelTemplate/
--   .metadata

How it operates

1. Live-link. Voxel.fromTemplate(<name>) resolves the template to an AssetRef<voxelTemplate> and stores it in VoxelShape.templateRef. The engine indexes that subscription by guid, so a write to the template's template.voxbin fires onAssetReload("templateRef") on every live instance, which re-reads the payload and rebuilds the mesh.
2. Delete. Voxel.deleteTemplate(<name>) removes the folder and directly flips staleTemplate = true on every live instance — deletes do not emit a content-change event, so the engine notifies instances synchronously rather than waiting on a reload hook.
3. Copy-on-write. Editing a live instance (setBlock, fillBox, …) auto-bakes a private dataPath copy and clears templateRef, detaching the instance from the template. The original template is untouched.

In the Inspector

Selecting a voxel template opens its Grid section, decoded from template.voxbin once per version of the file: the template's size in voxels, its block size, whether it is chunked (and, when it is, its chunk size and chunk count), how many palette entries it holds, and whether it carries custom data.