Texture Importer

Promotes a loose raster image (png / jpg / jpeg / webp / gif) into a managed .texture/ container. This is the loose-image → container step only.

What it does

When a bare image lands OUTSIDE any .texture/, the importer creates <name>.texture/ beside it through asset.create("texture", ...), then moves the uploaded image into it:

foo.png  →  foo.texture/
              foo.png        the original, moved in under its own name (never lost)
              settings.yaml  the texture's resolved settings, stamped by asset.create
              data.ztex      the encoded payload the renderer uploads
              .metadata      what data.ztex was encoded from
              README.md      the type's template note

asset.create resolves the new texture's settings — the schema's defaults, the name-derived textureType (normalMap for a _normal-style suffix, mask for _rough / _ao / _height-style ones) and the colour space it sets, any preset or importer layer — stamps them into settings.yaml, and encodes data.ztex from the uploaded bytes in the same call, so the texture is complete the moment it exists. The move that follows is quiet: it lands the original file without firing a second encode.

Settings

The importer's own settings.luau declares one group, textureSettings — the texture type's settings, embedded rather than restated. Whatever it holds is the importer layer of every texture this importer creates: above the schema's defaults and the name-derived textureType, below anything a caller names. Set it with asset.setSettings(importerRef, { textureSettings = { filter = "nearest" } }) on a world's own copy of the importer.

After the import

Everything inside the container is the texture assetType's: texture.assetType/behavior.luau::onChange reacts to writes inside a .texture/ instance. Rewriting the retained image re-encodes data.ztex from it; changing a setting (texRef:setSettings({ ... }), or an edit of settings.yaml) re-encodes it against the new values.

This split mirrors the engine's two write seams:

Seam	Fires for	Consumer
loose-file (onLooseWrite)	a write with no enclosing typed-asset folder	this importer (promote)
per-type (onChange)	a write inside a <name>.<type>/ instance	the texture assetType (re-encode data.ztex)

Encoding

data.ztex is the canonical pre-encoded + pre-mipped payload defined in crates/zero_texture/src/blob.rs (ZTEX magic). The CPU encoder is exposed to Luau as renderer.texture.*. Pure CPU — runs identically on native, WASM, and headless hosts.