generate-material

name	generate-material
description	Generate one tiled PBR material via fal PATINA. BaseColor + Normal + Roughness + Metalness + Height maps from a text prompt. ~$0.06-0.10 per material at 1024px. Use for procedural surfaces (sand, water, grass, dirt, rock) — NOT for objects (those come textured from Tripo P1).

Codex adaptation

Use the available Codex shell and file tools. In this migrated skill, $1 means world slug and $2 means material id.

Generate one PBR material set for worlds/$1/materials/$2/.

When to call this skill

For PROCEDURAL surfaces — primitives the agent builds in Blender (ground plane, water plane, grass patch) that need a tiled material. Examples:

• sand — for the main ground plane
• water-shallow — for the water plane around the island
• grass — for grass patch planes
• wood-planks — for a wooden walkway or hut floor
• rock-cliff — only if there's a procedural cliff surface (not a placed boulder)

For OBJECTS (palms, chests, lanterns, log-stumps, boulders, flowers) — do NOT use this skill. Tripo P1 emits textured GLBs with PBR maps baked in.

Procedure

1. Build the material prompt. Combine the material type with plan.style.anchor + palette + the magic phrase seamlessly tiling:

   "{material-type-description}, {style.anchor} cartoon art style, vibrant saturated palette ({relevant palette colours}), seamlessly tiling, no border artefacts, top-down view, no shadows."

   Examples:

   • Sand: "warm stylised cartoon beach sand, Donkey Kong Bananza palette, saturated warm yellow with subtle highlights, seamlessly tiling, no border artefacts, top-down view, no shadows."
   • Water: "stylised cartoon turquoise tropical water surface, Wind Waker shading, saturated cyan, seamlessly tiling, no border artefacts, top-down view, no shadows."
   • Grass: "stylised cartoon emerald-mint grass with small pink flowers, Banjo-Kazooie palette, saturated mid-green, seamlessly tiling, no border artefacts, top-down view, no shadows."

2. Generate the PBR set.

   node .claude/scripts/asset-pipeline/patina-material.mjs \
     --prompt "<the prompt above>" \
     --output-dir worlds/$1/materials/$2 \
     --output-slug $2 \
     --resolution 1024
   

   This produces five PNGs in the output dir: {basecolor, normal, roughness, metalness, height}.png and saves request metadata.

3. Apply to Blender. Build a Python snippet that creates a Principled BSDF material with the five maps loaded and connected:

   import bpy
   def apply_patina_material(obj_name, material_id, world_slug):
       base = f"worlds/{world_slug}/materials/{material_id}"
       mat = bpy.data.materials.new(name=f"{material_id}_PATINA")
       mat.use_nodes = True
       nt = mat.node_tree
       # Clear default
       for n in nt.nodes: nt.nodes.remove(n)
       out = nt.nodes.new("ShaderNodeOutputMaterial")
       bsdf = nt.nodes.new("ShaderNodeBsdfPrincipled")
       nt.links.new(bsdf.outputs["BSDF"], out.inputs["Surface"])
   
       def load_tex(slug, colorspace="sRGB"):
           img = bpy.data.images.load(f"{base}/{material_id}-{slug}.png", check_existing=True)
           img.colorspace_settings.name = colorspace
           t = nt.nodes.new("ShaderNodeTexImage")
           t.image = img
           return t
   
       basecolor = load_tex("basecolor", "sRGB")
       normal_t  = load_tex("normal", "Non-Color")
       rough_t   = load_tex("roughness", "Non-Color")
       metal_t   = load_tex("metalness", "Non-Color")
       height_t  = load_tex("height", "Non-Color")
   
       normal_map = nt.nodes.new("ShaderNodeNormalMap")
       nt.links.new(normal_t.outputs["Color"], normal_map.inputs["Color"])
   
       nt.links.new(basecolor.outputs["Color"], bsdf.inputs["Base Color"])
       nt.links.new(rough_t.outputs["Color"], bsdf.inputs["Roughness"])
       nt.links.new(metal_t.outputs["Color"], bsdf.inputs["Metallic"])
       nt.links.new(normal_map.outputs["Normal"], bsdf.inputs["Normal"])
       # Height → optional displacement on output
   
       obj = bpy.data.objects[obj_name]
       if obj.data.materials: obj.data.materials[0] = mat
       else: obj.data.materials.append(mat)
       return mat
   

   Call via execute_blender_code after patina-material.mjs finishes.

4. Visual check. Screenshot the textured surface, read it back. If the tile looks acceptable, done. If it looks bad (wrong colour, wrong style, broken seams), regenerate with a tighter prompt or different seed.

5. Hard cap: 2 retries per material. If three attempts in a row miss, escalate — usually means the prompt needs human intervention or the material needs to be hand-authored.

6. Update worlds/$1/cost.json with the PATINA spend.

Cost guide

Resolution	~Cost / generation	When to use
1024	$0.08	Default. Fine for all procedural surfaces.
2048	$0.30	Hero surface that fills the screen (rarely needed in stylised scenes).
4096	$1.18	Avoid — overkill for our pipeline.
8192	$4.70	Never use.

Total PATINA spend for a typical world (sand + water + grass = 3 materials at 1024) = ~$0.24.

What you must NOT do

• Do NOT use PATINA for objects with topology (palms, chests, log-stumps). They come textured from Tripo P1.
• Do NOT request > 2048 resolution — the model doesn't need that much detail in a stylised scene.
• Do NOT skip the "seamlessly tiling, no border artefacts" tail in the prompt — without it you get a single-shot photo instead of a tile.
• Do NOT regenerate more than 2 times per material — escalate instead.