Material Semantic Patch

This generated snapshot is derived from packages/material-semantic-patch. Material semantic patches are intent-level material edits: the package validates each operation against its op schema, applies it to the material graph document, revalidates the graph, and compiles the target artifacts, returning a receipt. The ai_safe, mcp_safe, and sdk_basic packs advertise the same operation alphabet as the visual editor; replaceGraph is the only operation withheld from every interactive author and is reserved for import and test sources.

Patch version: material-semantic-patch.v1. Operation catalog version: material-semantic-patch-ops.v1. Operation catalog hash: sha256:56b9abeafdb710e94658bdd7e9f77c83cb473b5e78421862f3c010816a269c75. Operation count: 23.

Operations

Operation reference

createBasicPbrSurface

Create or reset a graph-native OpenPBR surface from semantic PBR values.

• Title: Create Basic PBR Surface.
• Changed surfaces: graph, pbr.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

setPbrBaseColor

Set the OpenPBR base color without exposing node ids.

• Title: Set Base Color.
• Changed surfaces: pbr.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

setPbrColor

Set a color-valued OpenPBR compatibility field.

• Title: Set PBR Color Field.
• Changed surfaces: pbr.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

setPbrScalar

Set a scalar OpenPBR compatibility field.

• Title: Set PBR Scalar Field.
• Changed surfaces: pbr.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

Scalar field ranges enforced at the operation boundary:

• metallic must be between 0 and 1.
• roughness must be between 0 and 1.
• alphaCutoff must be between 0 and 1.
• emissiveIntensity must be between 0 and 100.
• normalStrength must be between 0 and 4.
• occlusionIntensity must be between 0 and 4.
• clearcoat must be between 0 and 1.
• clearcoatRoughness must be between 0 and 1.
• sheen must be between 0 and 1.
• sheenRoughness must be between 0 and 1.
• transmission must be between 0 and 1.
• transmissionRoughness must be between 0 and 1.
• ior must be between 1 and 2.333.
• attenuationDistance must be between 0 and 1000000.
• anisotropy must be between 0 and 1.
• anisotropyRotation must be between -25.132741228718345 and 25.132741228718345.

setAlphaMode

Set alpha mode with explicit compatibility projection.

• Title: Set Alpha Mode.
• Changed surfaces: pbr.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

setDoubleSided

Set double-sided material rendering intent.

• Title: Set Double Sided.
• Changed surfaces: pbr.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

setTextureSlot

Assign a texture asset to a known material slot.

• Title: Set Texture Slot.
• Changed surfaces: pbr, textures.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

clearTextureSlot

Remove a texture asset from a known material slot.

• Title: Clear Texture Slot.
• Changed surfaces: pbr, textures.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

setInstanceAtlas

Declare the per-instance texture-array atlas an instance may select a tile from.

• Title: Set Instance Atlas.
• Changed surfaces: pbr, instance.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

clearInstanceAtlas

Remove the per-instance atlas declaration from the material.

• Title: Clear Instance Atlas.
• Changed surfaces: pbr, instance.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

setPreviewGeometry

Set editor preview geometry metadata only.

• Title: Set Preview Geometry.
• Changed surfaces: editor.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

createWaterFoamMaterial

Create an appearance-only water material graph with explicit fallback diagnostics.

• Title: Create Water Foam Material.
• Changed surfaces: graph, water, pbr.
• Allowed sources: visual_editor, ai, mcp, sdk, template, test, internal.
• Undo: receipt-data.

addCatalogNode

Add a node by catalog id (catalog nodes only; trusted-only nodes rejected for every source).

• Title: Add Catalog Node.
• Changed surfaces: topology.
• Allowed sources: visual_editor, ai, mcp, sdk, import, test.
• Undo: receipt-data.

connectSockets

Connect two catalog sockets.

• Title: Connect Sockets.
• Changed surfaces: topology.
• Allowed sources: visual_editor, ai, mcp, sdk, import, test.
• Undo: receipt-data.

disconnectEdge

Remove a graph edge.

• Title: Disconnect Edge.
• Changed surfaces: topology.
• Allowed sources: visual_editor, ai, mcp, sdk, import, test.
• Undo: receipt-data.

replaceGraph

Replace with a fully validated graph document for import/test paths.

• Title: Replace Graph.
• Changed surfaces: topology.
• Allowed sources: import, test.
• Undo: receipt-data.

removeNode

Remove a graph node and its incident edges.

• Title: Remove Node.
• Changed surfaces: topology.
• Allowed sources: visual_editor, ai, mcp, sdk, import, test.
• Undo: receipt-data.

setNodePosition

Set a graph node's canvas position (layout only).

• Title: Set Node Position.
• Changed surfaces: editor.
• Allowed sources: visual_editor, ai, mcp, sdk, import, test.
• Undo: receipt-data.

setNodeParameter

Set a generic node parameter by key.

• Title: Set Node Parameter.
• Changed surfaces: topology.
• Allowed sources: visual_editor, ai, mcp, sdk, import, test.
• Undo: receipt-data.

addComment

Add or replace a canvas comment annotation (layout only).

• Title: Add Comment.
• Changed surfaces: editor.
• Allowed sources: visual_editor, ai, mcp, sdk, import, test.
• Undo: receipt-data.

removeComment

Remove a canvas comment annotation by id.

• Title: Remove Comment.
• Changed surfaces: editor.
• Allowed sources: visual_editor, ai, mcp, sdk, import, test.
• Undo: receipt-data.

groupNodes

Add or replace a canvas node group (layout only).

• Title: Group Nodes.
• Changed surfaces: editor.
• Allowed sources: visual_editor, ai, mcp, sdk, import, test.
• Undo: receipt-data.

removeGroup

Remove a canvas node group by id.

• Title: Remove Group.
• Changed surfaces: editor.
• Allowed sources: visual_editor, ai, mcp, sdk, import, test.
• Undo: receipt-data.

Operation packs

Each pack is an allowlisted operation alphabet advertised to a source class. The agent-facing tool for a source binds the schema union to its pack, so an operation absent from the pack is not a member of the schema the caller can submit.

Patch sources

The patch source is one of visual_editor, ai, mcp, sdk, template, import, test, internal.

Texture slots

Known material texture slots: baseColor, normal, metallicRoughness, emissive, occlusion, lightMap, clearcoatNormal, sheenColor, transmission.

Eval corpus

Backend integration

• Action Catalog id: project.material.patch.apply.
• HTTP: POST /api/games/:gameId/project/assets/:assetId/material/patches/apply.
• MCP: project_apply_material_semantic_patch.
• AI metadata: apply_material_semantic_patch.
• SDK: project.materials.applySemanticPatch.