Expand H3 reference-node documentation
This commit is contained in:
@@ -891,6 +891,77 @@ The node uses reference data in two different ways:
|
||||
|
||||
Character refs can now contribute actual image identity when the beat names the character, not just when you explicitly tag the picture slot.
|
||||
|
||||
### Character Reference Node: what the fields actually do
|
||||
|
||||
`Dumas Character Reference` packages one image plus metadata into one `REFERENCE` socket.
|
||||
|
||||
What the long-videos code actually uses:
|
||||
|
||||
- `image`: the real reference image H3 sees when that slot is selected for a shot
|
||||
- `name`, `character_id`, `alias`: used for character-name matching in beat text
|
||||
- `description`: injected as persistent appearance text when that character ref is matched
|
||||
- `wardrobe`: injected as persistent wardrobe text when matched, and also used to seed `character_memory` if the long-videos node field is blank
|
||||
- `general`: injected as extra character notes when matched
|
||||
- `gender`, `age`, `nationality`, `occupation`, `height`, `accent`: turned into one "Character facts" sentence when matched
|
||||
|
||||
What this means in practice:
|
||||
|
||||
- the image and the text metadata are separate channels
|
||||
- a character image can still condition a shot even if its metadata was not injected into the beat text
|
||||
- wardrobe from character refs is only promoted into live tracked wardrobe state when `character_memory` is empty
|
||||
|
||||
### When character data gets used
|
||||
|
||||
There are three different moments:
|
||||
|
||||
1. Shot ref routing chooses whether the character image is attached to that beat at all.
|
||||
2. Text matching decides whether the character metadata is injected into that beat text.
|
||||
3. Chain-state seeding decides whether the character ref wardrobe becomes the starting `character_memory`.
|
||||
|
||||
The important detail is that these do not always happen together.
|
||||
|
||||
Character image conditioning:
|
||||
|
||||
- happens according to `ref_mode`
|
||||
- can be forced with `<Picture N>`
|
||||
- can also be pulled in by naming the character in the beat
|
||||
|
||||
Character text metadata injection:
|
||||
|
||||
- happens only when the beat explicitly tags the slot with `<Picture N>`
|
||||
- or when the beat mentions the character by `name`, `id`, or `alias`
|
||||
|
||||
Character wardrobe seeding:
|
||||
|
||||
- happens once at chain setup
|
||||
- only if the long-videos `character_memory` field is blank
|
||||
- only for character refs that actually contain wardrobe text
|
||||
|
||||
### Location Reference Node: what the fields actually do
|
||||
|
||||
`Dumas Location Reference` is simpler. It packages one environment image plus environment metadata into one `REFERENCE` socket.
|
||||
|
||||
What the long-videos code actually uses:
|
||||
|
||||
- `image`: the real location reference image H3 sees when that slot is selected for a shot
|
||||
- `description`: injected as location context when that slot is explicitly tagged
|
||||
- `general`: injected as location notes when that slot is explicitly tagged
|
||||
- `name`, `location_id`, `alias`: used mainly as labels in summaries and injected sentences, not for automatic prose matching
|
||||
|
||||
Important difference from character refs:
|
||||
|
||||
- location refs are **not** auto-matched from location names in beat prose
|
||||
- if you write `in the cafe` and do not tag `<Picture N>`, the location image may still be in the shot because of `ref_mode`, but the location text metadata is not auto-injected just from that name
|
||||
|
||||
### When location data gets used
|
||||
|
||||
Location node data has two separate paths:
|
||||
|
||||
1. The location image can be attached to shots through normal ref routing.
|
||||
2. The location text metadata is only injected when you explicitly tag that slot with `<Picture N>`.
|
||||
|
||||
So location references are more tag-driven than character references.
|
||||
|
||||
Simple usage patterns:
|
||||
|
||||
- one character, no special routing: use `auto ref2v`
|
||||
@@ -904,6 +975,96 @@ What to remember:
|
||||
- location refs are often tagged because they are about where the shot happens
|
||||
- character refs are often named because they are about who is in the shot
|
||||
|
||||
### Scenarios
|
||||
|
||||
### Scenario: one hero character, no location ref
|
||||
|
||||
Setup:
|
||||
|
||||
- `ref_1` = Maya character reference
|
||||
- beat text says `Maya crosses the road and looks back`
|
||||
- `ref_mode = auto ref2v`
|
||||
|
||||
What happens:
|
||||
|
||||
- Maya's image is attached to the shot
|
||||
- Maya's character metadata is injected because the beat names `Maya`
|
||||
- if `character_memory` is blank, Maya's `wardrobe` field also seeds the live wardrobe tracker at chain start
|
||||
|
||||
### Scenario: two characters plus one tagged location
|
||||
|
||||
Setup:
|
||||
|
||||
- `ref_1` = Maya character reference
|
||||
- `ref_2` = Jon character reference
|
||||
- `ref_3` = warehouse location reference
|
||||
- beat says `Maya argues with Jon near the loading bay <Picture 3>`
|
||||
|
||||
What happens:
|
||||
|
||||
- Maya and Jon can be matched by name, so their character metadata can be injected
|
||||
- the warehouse location metadata is injected because `<Picture 3>` tags it
|
||||
- the image refs used on the shot still depend on `ref_mode`
|
||||
|
||||
Why this pattern works well:
|
||||
|
||||
- character refs can be driven by names
|
||||
- location refs usually need explicit tags when you want the environment text to be stated clearly
|
||||
|
||||
### Scenario: location image works, but location notes do not seem to
|
||||
|
||||
Setup:
|
||||
|
||||
- `ref_3` = cafe location reference
|
||||
- beat says `They sit in the cafe window booth`
|
||||
- no `<Picture 3>` tag
|
||||
|
||||
What happens:
|
||||
|
||||
- with `auto ref2v` or `every shot`, the cafe image may still be conditioning the shot
|
||||
- but the location `description` and `general` fields are not auto-injected from the word `cafe`
|
||||
|
||||
What to do:
|
||||
|
||||
- add `<Picture 3>` on the beat where the location wording matters
|
||||
|
||||
### Scenario: character face is partly right, but identity is weak
|
||||
|
||||
Setup:
|
||||
|
||||
- character refs are connected
|
||||
- beat prose uses `she` and `he`, but never names the characters
|
||||
- `character_memory` contains clothing and height-like facts
|
||||
|
||||
What happens:
|
||||
|
||||
- the beat can still pick up some tracked wardrobe/state language
|
||||
- but the strongest character-ref match path is weaker because the beat is not naming the people
|
||||
- that can produce "same role, wrong face" results
|
||||
|
||||
What to do:
|
||||
|
||||
- name the characters in the beat, or tag their slots explicitly
|
||||
- keep `ref_noise_aug` high
|
||||
- use `every shot` when identity matters more than soft continuity
|
||||
|
||||
### Scenario: character wardrobe from the ref node does not update later
|
||||
|
||||
Setup:
|
||||
|
||||
- character ref has wardrobe filled in
|
||||
- long-videos `character_memory` is also filled in with different clothing
|
||||
|
||||
What happens:
|
||||
|
||||
- the long-videos `character_memory` wins as the live starting wardrobe state
|
||||
- the wardrobe field inside the character ref is still usable as injected descriptive text when matched, but it does not replace the explicit `character_memory` sheet
|
||||
|
||||
What to do:
|
||||
|
||||
- put the canonical changing outfit in `character_memory`
|
||||
- treat character-ref wardrobe as a fallback/default seed, not the main changing state source
|
||||
|
||||
### If faces drift or people turn into random lookalikes
|
||||
|
||||
Check these in this order:
|
||||
|
||||
Reference in New Issue
Block a user