--- title: "Material Semantic Patch" description: "Sources: `packages/material-semantic-patch/src/index.ts`, `packages/protocol/src/index.ts`." engineVersion: v1.0.234 date: 2026-09-28 license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/." canonical: https://gessa.ai/docs/spec/generated/material-semantic-patch/ --- Sources: `packages/material-semantic-patch/src/index.ts`, `packages/protocol/src/index.ts`. # 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 | Title | Description | Changed surfaces | Allowed sources | Undo | | --- | --- | --- | --- | --- | --- | | `createBasicPbrSurface` | Create Basic PBR Surface | Create or reset a graph-native OpenPBR surface from semantic PBR values. | `graph`, `pbr` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `setPbrBaseColor` | Set Base Color | Set the OpenPBR base color without exposing node ids. | `pbr` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `setPbrColor` | Set PBR Color Field | Set a color-valued OpenPBR compatibility field. | `pbr` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `setPbrScalar` | Set PBR Scalar Field | Set a scalar OpenPBR compatibility field. | `pbr` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `setAlphaMode` | Set Alpha Mode | Set alpha mode with explicit compatibility projection. | `pbr` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `setDoubleSided` | Set Double Sided | Set double-sided material rendering intent. | `pbr` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `setTextureSlot` | Set Texture Slot | Assign a texture asset to a known material slot. | `pbr`, `textures` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `clearTextureSlot` | Clear Texture Slot | Remove a texture asset from a known material slot. | `pbr`, `textures` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `setInstanceAtlas` | Set Instance Atlas | Declare the per-instance texture-array atlas an instance may select a tile from. | `pbr`, `instance` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `clearInstanceAtlas` | Clear Instance Atlas | Remove the per-instance atlas declaration from the material. | `pbr`, `instance` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `setPreviewGeometry` | Set Preview Geometry | Set editor preview geometry metadata only. | `editor` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `createWaterFoamMaterial` | Create Water Foam Material | Create an appearance-only water material graph with explicit fallback diagnostics. | `graph`, `water`, `pbr` | `visual_editor`, `ai`, `mcp`, `sdk`, `template`, `test`, `internal` | receipt-data | | `addCatalogNode` | Add Catalog Node | Add a node by catalog id (catalog nodes only; trusted-only nodes rejected for every source). | `topology` | `visual_editor`, `ai`, `mcp`, `sdk`, `import`, `test` | receipt-data | | `connectSockets` | Connect Sockets | Connect two catalog sockets. | `topology` | `visual_editor`, `ai`, `mcp`, `sdk`, `import`, `test` | receipt-data | | `disconnectEdge` | Disconnect Edge | Remove a graph edge. | `topology` | `visual_editor`, `ai`, `mcp`, `sdk`, `import`, `test` | receipt-data | | `replaceGraph` | Replace Graph | Replace with a fully validated graph document for import/test paths. | `topology` | `import`, `test` | receipt-data | | `removeNode` | Remove Node | Remove a graph node and its incident edges. | `topology` | `visual_editor`, `ai`, `mcp`, `sdk`, `import`, `test` | receipt-data | | `setNodePosition` | Set Node Position | Set a graph node's canvas position (layout only). | `editor` | `visual_editor`, `ai`, `mcp`, `sdk`, `import`, `test` | receipt-data | | `setNodeParameter` | Set Node Parameter | Set a generic node parameter by key. | `topology` | `visual_editor`, `ai`, `mcp`, `sdk`, `import`, `test` | receipt-data | | `addComment` | Add Comment | Add or replace a canvas comment annotation (layout only). | `editor` | `visual_editor`, `ai`, `mcp`, `sdk`, `import`, `test` | receipt-data | | `removeComment` | Remove Comment | Remove a canvas comment annotation by id. | `editor` | `visual_editor`, `ai`, `mcp`, `sdk`, `import`, `test` | receipt-data | | `groupNodes` | Group Nodes | Add or replace a canvas node group (layout only). | `editor` | `visual_editor`, `ai`, `mcp`, `sdk`, `import`, `test` | receipt-data | | `removeGroup` | Remove Group | Remove a canvas node group by id. | `editor` | `visual_editor`, `ai`, `mcp`, `sdk`, `import`, `test` | receipt-data | ## 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. | Pack | Operation count | Operations | | --- | --- | --- | | `visual_editor` | `22` | `createBasicPbrSurface`, `setPbrBaseColor`, `setPbrColor`, `setPbrScalar`, `setAlphaMode`, `setDoubleSided`, `setTextureSlot`, `clearTextureSlot`, `setInstanceAtlas`, `clearInstanceAtlas`, `setPreviewGeometry`, `createWaterFoamMaterial`, `addCatalogNode`, `connectSockets`, `disconnectEdge`, `removeNode`, `setNodePosition`, `setNodeParameter`, `addComment`, `removeComment`, `groupNodes`, `removeGroup` | | `ai_safe` | `22` | `createBasicPbrSurface`, `setPbrBaseColor`, `setPbrColor`, `setPbrScalar`, `setAlphaMode`, `setDoubleSided`, `setTextureSlot`, `clearTextureSlot`, `setInstanceAtlas`, `clearInstanceAtlas`, `setPreviewGeometry`, `createWaterFoamMaterial`, `addCatalogNode`, `connectSockets`, `disconnectEdge`, `removeNode`, `setNodePosition`, `setNodeParameter`, `addComment`, `removeComment`, `groupNodes`, `removeGroup` | | `mcp_safe` | `22` | `createBasicPbrSurface`, `setPbrBaseColor`, `setPbrColor`, `setPbrScalar`, `setAlphaMode`, `setDoubleSided`, `setTextureSlot`, `clearTextureSlot`, `setInstanceAtlas`, `clearInstanceAtlas`, `setPreviewGeometry`, `createWaterFoamMaterial`, `addCatalogNode`, `connectSockets`, `disconnectEdge`, `removeNode`, `setNodePosition`, `setNodeParameter`, `addComment`, `removeComment`, `groupNodes`, `removeGroup` | | `sdk_basic` | `22` | `createBasicPbrSurface`, `setPbrBaseColor`, `setPbrColor`, `setPbrScalar`, `setAlphaMode`, `setDoubleSided`, `setTextureSlot`, `clearTextureSlot`, `setInstanceAtlas`, `clearInstanceAtlas`, `setPreviewGeometry`, `createWaterFoamMaterial`, `addCatalogNode`, `connectSockets`, `disconnectEdge`, `removeNode`, `setNodePosition`, `setNodeParameter`, `addComment`, `removeComment`, `groupNodes`, `removeGroup` | | `import` | `11` | `replaceGraph`, `addCatalogNode`, `connectSockets`, `disconnectEdge`, `removeNode`, `setNodePosition`, `setNodeParameter`, `addComment`, `removeComment`, `groupNodes`, `removeGroup` | ## 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 | Case | Title | Operations | | --- | --- | --- | | `red_metal` | Red Metallic PBR | `createBasicPbrSurface`, `setPbrBaseColor`, `setPbrScalar`, `setPbrScalar` | | `water_foam` | Water Foam Appearance | `createWaterFoamMaterial` | | `canvas_annotations` | Graph Canvas Annotations (comment + group, layout only) | `addComment`, `groupNodes` | ## 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`.