Document scene layer seed simplification

2026-07-01 15:47:05 +02:00
parent 5e218e2d33
commit 39782ce843
1 changed files with 68 additions and 0 deletions
@@ -0,0 +1,68 @@
+# Scene Layer Seed Design
+
+## Problem
+
+`SxCPSceneLayerSeedOptions` currently has a confusing double-seed behavior. When
+`seed_mode=random`, the node displays one seed in the widget, but the build
+method replaces it with a hidden `SystemRandom` value. The generated prompt may
+therefore use a clothing/content seed that is not visible in the workflow after
+the run.
+
+This makes softcore branch clothing hard to reproduce. In a scene pair, the
+woman's softcore outfit is selected from the softcore branch content seed, then
+the hardcore branch may inherit that outfit through clothing continuity. If the
+resolved content seed is hidden, the user cannot reliably answer which seed
+picked the clothes.
+
+## Approved Behavior
+
+The visible `seed` field in `SxCPSceneLayerSeedOptions` is the authoritative
+seed. `seed_mode=random` must no longer replace it with a hidden random value.
+For layer-seed behavior:
+
+- `follow_global`: use the scene seed.
+- `fixed`: use the visible node `seed`.
+- `random`: use the visible node `seed`.
+- `disabled`: apply no layer seed.
+
+The `random` option can remain in the UI for compatibility, but it behaves like
+an explicit seed mode. If a user wants a new random value, they should randomize
+the visible seed field in the node or use ComfyUI's widget randomization.
+
+## Seed Reporting
+
+The existing scene `seed_trace` remains the source of truth for resolved prompt
+axis seeds. For softcore branch clothing, the relevant trace is usually:
+
+- layer: `softcore_branch`
+- reroll axis: `content` or `content_pose`
+- affected axes: `content_seed`, and for `content_pose` also `pose_seed` and
+  `role_seed`
+
+Scene pair metadata should continue to include the full softcore and hardcore
+scene chain so `seed_trace` is preserved in `metadata_json` and
+`scene_metadata_json`.
+
+## Non-Goals
+
+This change does not introduce a separate `clothing_seed` axis. Clothing is still
+part of the existing content axis. Splitting clothing from content would be a
+larger behavior change and should be handled separately if needed.
+
+This change does not alter image sampler seeds. KSampler/image seeds remain
+separate from prompt layer seeds.
+
+## Testing
+
+Add or update smoke coverage for `SxCPSceneLayerSeedOptions`:
+
+- A `random` mode layer seed emits the visible widget seed in its metadata.
+- A `fixed` mode layer seed emits the same seed as `random` when given the same
+  visible seed.
+- A softcore branch `content` or `content_pose` seed appears in the generated
+  softcore row `seed_config`.
+- The generated softcore outfit can be traced to that visible content seed.
+
+Existing scene pair tests should continue to verify that softcore branch seeds do
+not leak into hardcore pose/content seeds unless explicitly applied to the hard
+branch.