material_remap

Canonical property/texture-role dictionary used when a material swaps shaders. The new shader exposes a different vocabulary than the old one — one shader's MAIN_TEX is another's albedo is a third's base_color_texture — so values would be lost on a naive swap. This module maps any known alias onto a canonical role so floats, colors, and texture links carry across the swap to the best of our ability.

Consumed by material.assetType's setShader ref method (and, transitively, by the appearance toolbox's swapShader).

API

local remap = require("modules.material_remap")

remap.propertyRole("MAIN_COLOR")        -- "base_color"  (scalar/color side)
remap.textureRole("MAIN_TEX")           -- "base_color_texture" (texture side)

-- Remap current property values onto the new shader's accepted names.
local mapped, carried, dropped =
    remap.remapProperties(currentProps, shaderRef:getProperties())

-- Canonicalize texture slot names so links bind on the new shader.
local texMapped, texCarried = remap.canonicalizeTextures(currentTextures)

Why two tables

albedo as a color is the base-color factor; albedo as a texture is the base-color map. mat.yaml keeps colors: / floats: separate from textures:, so the caller always knows which side it's remapping. Splitting PROPERTY_ROLES from TEXTURE_ROLES removes the ambiguity instead of guessing from the value shape.

Property remap vs texture remap

• Properties are remapped against the target shader's real reflected field names (shaderRef:getProperties(), naga reflection). Direct name match wins; otherwise role-to-role. Properties the new shader doesn't expose are dropped.
• Textures are canonicalized to the engine's builtin on-disk slot convention (base_color_texture, normal_texture, …) because the engine does not yet surface a target shader's reflected texture-slot list to Luau. Unknown slots pass through unchanged.

The alias lists are deliberately broad (glTF / Unity / Unreal / Godot / hand-rolled WGSL conventions). Add new aliases here rather than special-casing a shader at a call site.