shared Module

Cross-tool helpers for the appearance toolbox. Every tool inside this toolbox can pull these in with require(".shared").

Purpose

This module holds the small set of helpers that more than one tool in the toolbox needs — the toolbox-wide hierarchy-search and ref-resolution helpers every appearance tool uses. Tools return their raw values (the tool.assetType wrapper packages them into the system ZmToolResult envelope) and raise via error(message) on failure. Keep it focused: per-tool implementation stays inside each <x>.tool/init.luau (with its own --!desc / --!arg / --!return / --!example annotations).

Usage

local shared = require(".shared")

function M.someTool(material, opts)
    local rootIds = shared.resolveRoots(opts and opts.roots)
    local hits = shared.collectAssetRefFields(rootIds, "material", opts)
    return { roots = rootIds, count = #hits, assigned = hits }
end

Exports

See init.luau for the full export surface:

• shared.resolveEntity — one entity id OR name → id.
• shared.resolveRoots — batch roots argument (one id/name, an array of ids/names/entity proxies, or nil = every scene root) → id array.
• shared.collectAssetRefFields — schema-driven discovery: walk the targeted hierarchies and return every component public field declared as Field.assetRef(<category>, ...) (read from each component's registered schema via component.getAssetFields), as { id, name, component, field } hits.
• shared.collectModelEntities — hierarchy walk collecting the Model / SkinnedModel-bearing entities (backs setModel).
• shared.isAssetHandle — whether a table is shaped like an asset-ref envelope (holds a __ref / guid / identity / path string), which is what separates a handle a caller holds from a table of some other kind.
• shared.resolveMaterialRef / shared.findMaterial — material ref resolution; findMaterial additionally combs every material in the project for a string argument.
• shared.findShader — shader ref/identity normalization, combing every shader in the project for a string argument.
• shared.refKey — stable string key (identity/guid/name/__ref) from a ref value.
• shared.specAcceptsCategory — AssetRef<...> spec-string grammar check, including AssetRef<a|b> alternatives.