voxbinCatalog.package

A curated catalog of ready-to-spawn .voxbin voxel assets, organized for use across scenes, demos, and worlds. Every file in templates/ is a flattened shape (no composite hierarchy) that can be placed directly with Voxel.spawn({ op = "template", ... }).

Layout

voxbinCatalog.package/
  templates/
    <category>/                # category == filename prefix (e.g. bird/, gem/)
      <name>.voxbin
    misc/                      # single-word names with no underscore prefix
      <name>.voxbin
  readme.md

The category folder for each asset is its filename prefix (everything before the first _). Single-word assets (anchor.voxbin, accordion.voxbin, …) live under templates/misc/.

Using the catalog

The catalog is shipped as a VFS-mounted folder. The voxel engine's default paths.templates resolves to /source/voxel/templates, so the simplest path is to either:

1. Re-point the templates path at the catalog:

   local Config = require("@builtin/voxelEngine/config") -- or your equivalent
   Config.set("paths.templates", "/source/voxbinCatalog/<category>")
   

2. Register each file as a named template at scene mount time, walking the catalog with vfs.list() and writing into the world's template path via Voxel.persist({ op = "saveAsTemplate", name = name, target = handle }) — or simpler, vfs.write(templatesPath .. "/" .. name .. ".voxbin", bytes) for a direct bytewise copy.
3. Spawn directly by VFS path (preferred for one-offs):

   local bytes = vfs.read("/source/voxbinCatalog/bird/bird_finch_red.voxbin")
   -- decode + spawn through the voxel pipeline
   

Spawning by template name (once registered)

Voxel.spawn({ op = "template", name = "bird_finch_red",
              position = {0, 2, 0} })

Bulk scatter

Voxel.spawn({
    op       = "scatter",
    template = "tree_oak_summer",
    region   = { box = { min = {0,0,0}, max = {64,0,64} } },
    count    = 30,
    seed     = 7,
})

Composite kitbash

Voxel.composite({
    children = {
        { template = "house_cottage_wall", offset = {0,0,0} },
        { template = "chimney_brick",      offset = {2,3,0} },
    },
    saveBaked = "/source/voxel/templates/house_with_chimney.voxbin",
})

Catalog provenance

Every asset in this catalog was crafted in the running engine (voxel build → visual inspection → save). The crafting journal lives at docs/voxbin_catalog/JOURNAL.md, and the canonical (un-categorized) catalog lives at docs/voxbin_catalog/crafted/. Files here are bytewise copies of the canonical catalog organized into prefix folders for easier discovery.

If you add an asset, place it in the matching prefix folder (creating one if needed) and add the canonical copy to docs/voxbin_catalog/crafted/ in the same commit.