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.
  • README.md — instance documentation. Required.
  • .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)
--   README.md
--   .metadata

Or scaffold an empty one to fill in later:

asset.create("voxelTemplate", "MyProp")
-- Creates: /zero/source/MyProp.voxelTemplate/
--   README.md   (this template, with [name]/[type]/[guid] filled in)
--   .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.