chore: snapshot workflow migration progress

2026-04-12 11:49:04 +02:00
parent 0cd02513d5
commit 3e810c74a3
163 changed files with 31774 additions and 2753 deletions
@@ -0,0 +1,82 @@
+# Template Inputs For Graph Workflows
+
+`resolve_template` can now expose template-specific inputs into the graph workflow without breaking legacy rendering.
+
+## Where the inputs come from
+
+Render templates can define a `workflow_input_schema` JSON array in Admin.
+
+Example:
+
+```json
+[
+  {
+    "key": "studio_variant",
+    "label": "Studio Variant",
+    "type": "select",
+    "section": "Template Inputs",
+    "default": "default",
+    "options": [
+      { "value": "default", "label": "Default" },
+      { "value": "warm", "label": "Warm" }
+    ]
+  },
+  {
+    "key": "camera_profile",
+    "label": "Camera Profile",
+    "type": "text",
+    "section": "Template Inputs",
+    "default": "macro"
+  }
+]
+```
+
+These fields appear in the workflow editor on the `resolve_template` node after a template override is selected.
+
+## Runtime behavior
+
+At runtime the graph path resolves these values into `template_inputs` and forwards them through:
+
+1. `resolve_template`
+2. workflow runtime invocation
+3. still / turntable / cinematic Blender services
+4. Blender worker CLI via `--template-inputs`
+5. template scene setup after opening the `.blend`
+
+Legacy workflows continue to work if no template input schema is defined.
+
+## Blender-side conventions
+
+Every resolved template input is always written onto the active scene as:
+
+- `template_input__<key>`
+- `hartomat_template_input__<key>`
+
+Example:
+
+- `template_input__studio_variant = "warm"`
+- `hartomat_template_input__camera_profile = "macro"`
+
+Templates can optionally react to these values using markers on collections, objects, or worlds.
+
+Supported marker styles:
+
+- custom property value: `template_input=studio_variant=warm`
+- object or collection name: `template-input:studio_variant=warm`
+- object or collection name: `ti::studio_variant::warm`
+
+If a marker matches the resolved input value, the target is enabled. Non-matching variants are hidden.
+
+## Practical authoring pattern
+
+For a lighting setup with two variants:
+
+1. Put warm lights into a collection named `template-input:studio_variant=warm`
+2. Put cool lights into a collection named `template-input:studio_variant=cool`
+3. Define `studio_variant` in `workflow_input_schema`
+4. Select the template in `resolve_template`
+5. Pick the wanted variant in the node inspector
+
+## Important limitation
+
+The graph runtime now transports template inputs end-to-end, but existing `.blend` files only change visually if they use one of the conventions above or read the scene custom properties themselves.