---
title: "Voxel Template (asset type)"
description: "A voxel template is a reusable, named voxel grid that live instances link to. It is the source of truth for a family of VoxelShape instances spawned via Voxel.fromTemplate(<name>) — every live…"
section: "Types"
slug: "types-voxeltemplate"
canonical: "https://origozero.ai/docs/types-voxeltemplate"
updated: "2026-09-05T16:41:47.530854592+00:00"
tags: ["asset-type", "reference"]
---

# 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:

```luau
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:

```luau
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.