# Skill: Reference Sheet System (Per-Entity)

## What
How to create production-quality reference sheets for ANY entity — characters, rooms, objects, props. Each entity gets its OWN folder with its OWN sheets. They're spices you pick and combine per-scene.

## Why
Putting multiple characters on one sheet defeats the purpose. Each entity is a self-contained visual DNA package. When you generate a scene, `resolve_refs()` grabs ALL PNGs from matched entity folders and sends them alongside the prompt. The model sees each entity's full vocabulary — identity, emotions, mechanics — as separate reference images. Mixing entities on one sheet means the model can't isolate visual DNA per character.

## The Entity Model

Every folder in `objects/` = ONE entity. One character. One room. One prop. Never combine.

```
objects/
  daughter/           <- ONE character
    sheet.md
    character-sheet.png
    expression-sheet.png
    motion-sheet.png
  mother/             <- ONE character
    sheet.md
    character-sheet.png
    expression-sheet.png
  hospital-room/      <- ONE environment
    sheet.md
    view-door.png       (from doorway looking in)
    view-window.png     (from window looking out)
    view-overhead.png   (top-down layout)
  stuffed-bunny/      <- ONE prop
    sheet.md
    reference.png
```

## Sheet Types by Entity Kind

### Characters
| Sheet | What | When to make |
|-------|------|-------------|
| **Character Turnaround** | 2x3 or 3x3 grid: front, 3/4 front, side, 3/4 back, BACK VIEW, top-down. One image, all angles. | ALWAYS — every character |
| **Expression Sheet** | Grid of facial close-ups across emotion range. Same character, multiple expressions. | Characters with dialogue or emotional beats |
| **Motion Sheet** | Key action poses arranged in sequence. Same character, multiple poses on one image. | Characters with complex/unusual physical actions (e.g., toddler climbing) |

**Character Turnaround Rule (NON-NEGOTIABLE):**
NEVER waste a generation on a single front-view portrait. Always generate a 2x3 or 3x3 turnaround grid. One API call = 6-9 views. This gives the model visual DNA for EVERY angle it might need to render.

The views you include must be driven by the SCENE PLAN. Ask: "In which panels does this character appear, and from which angles?" If the character is seen from behind for 5 panels, the turnaround sheet MUST include a back view. If they're seen from above, include a top-down view. If they spend most of the scene in a specific pose (e.g., mother propped up in hospital bed), include that pose as one of the grid slots.

Example — daughter in a POV sequence where she's seen from behind for panels 03-07:
- Front view (establishing identity)
- 3/4 front (recognition scenes)
- Side view (profile moments)
- 3/4 back (running away at angle)
- **Back view** (running AWAY from POV camera — the most common angle in this story)
- **Top-down view** (what she looks like from a tall adult looking straight down at her)

Example — mother who spends 80% of the story in a hospital bed:
- Front, 3/4, side, back views (standard turnaround)
- **Propped up in bed** (scene-specific pose that replaces one standard view — this is how the model will see her most often)

### Rooms / Environments
| Sheet | What | When to make |
|-------|------|-------------|
| **View from door** | Room as seen entering — establishes spatial layout | ALWAYS |
| **View from window/far wall** | Room looking back toward entrance — reverse angle | When scenes require multiple camera angles |
| **Overhead layout** | Top-down view showing furniture arrangement, spatial relationships | Complex rooms with movement through space |

### Props / Objects
| Sheet | What | When to make |
|-------|------|-------------|
| **Reference** | Clean view on neutral grey. Multiple angles if shape matters. | Props that appear after establishing shot OR are small/critical |

## Chaining Rule (WITHIN an entity)

Generate sheets in strict order. Each entity's character sheet feeds into its own expression and motion sheets:

```
daughter/character-sheet.png  (standalone)
      |
      +-> daughter/expression-sheet.png  (receives character sheet as reference)
      +-> daughter/motion-sheet.png      (receives character sheet as reference)

mother/character-sheet.png   (standalone)
      |
      +-> mother/expression-sheet.png   (receives character sheet as reference)
```

**Chaining is WITHIN an entity.** Daughter's character sheet feeds daughter's expression sheet. NOT mother's character sheet feeding daughter's anything.

**Why chain?** Without seeing the character sheet, expression/motion sheets drift — different eye size, different skin tone, different proportions. The character sheet IS the visual anchor for that entity.

## Prompt Patterns

### Character Turnaround Sheet (standalone)
```
Pixar 3D animation CHARACTER TURNAROUND SHEET on clean neutral grey background.
SIX views of the SAME character arranged in a 2x3 grid (two rows, three columns).
Full body visible in every view.

[Full description: age, ethnicity, skin tone, hair, eyes, build, clothing, accessories, props]

TOP ROW (left to right):
1. FRONT VIEW — facing camera, standing relaxed
2. 3/4 FRONT — turned 45 degrees
3. SIDE VIEW — full profile

BOTTOM ROW (left to right):
4. 3/4 BACK — turned 135 degrees, showing back details
5. BACK VIEW — facing completely away, showing hair/clothing from behind
6. [SCENE-SPECIFIC VIEW] — the angle or pose most common in the story
   (e.g., TOP-DOWN for characters seen from above, SEATED IN BED for bedridden characters)

Same character in all views. Consistent proportions. Clean studio lighting.
No other characters. No background elements. No text in image.
```

**The 6th slot is scene-driven.** Don't waste it on another standard angle. Use it for the pose/angle the model will need most often for this specific story.

### Expression Sheet (chained from character sheet)
```
[Feed entity's character-sheet.png as image reference]
"REFERENCE CHARACTER SHEET -- match this character exactly. Same face, same proportions, same style."

Pixar 3D animation FACIAL EXPRESSION SHEET on clean neutral grey background.
[N] face close-ups of the SAME character arranged in a grid.
1. [EMOTION]: [specific facial description]
2. [EMOTION]: [specific facial description]
...
Same character throughout. Clean grid layout. High quality Pixar 3D.
```

### Motion Sheet (chained from character sheet)
```
[Feed entity's character-sheet.png as image reference]
"REFERENCE CHARACTER SHEET -- match this character exactly. Same body, same proportions, same outfit."

Pixar 3D animation MOTION/ACTION REFERENCE SHEET on clean neutral grey background.
[N] poses of the SAME character arranged in sequence.
TOP ROW:
1. [POSE NAME] -- [full body mechanics description using figure-posing skill]
2. [POSE NAME] -- [full body mechanics description]
BOTTOM ROW:
...
All poses SAME character. Consistent design throughout.
```

### Room Multi-Angle Views
```
Pixar 3D animation ROOM REFERENCE on clean background.
[Room type] viewed from [angle/position].
[Full description: furniture, colors, lighting, spatial layout]
Clean architectural visualization style. No characters.
```

### Prop Reference
```
Pixar 3D animation OBJECT REFERENCE on clean neutral grey background.
[Object]: [full description — size, color, material, condition, distinguishing features]
Clean studio lighting. Multiple angles if needed.
```

## How generate.py Uses Them

`resolve_refs()` grabs ALL PNGs from each entity folder listed in `"characters"` and `"environments"`. So if a prompt has:
```json
{
  "characters": ["daughter", "mother"],
  "environments": ["hospital-room"]
}
```

The model receives:
- daughter/character-sheet.png + expression-sheet.png + motion-sheet.png
- mother/character-sheet.png + expression-sheet.png
- hospital-room/view-door.png + view-window.png + view-overhead.png

Each entity's visual DNA travels with it. Scenes are recipes — you pick the spices you need.

## Budget

Per entity, character sheets cost ~$0.15 each (Nano Banana Pro):
- Simple character (character sheet only): ~$0.15
- Full character (character + expression + motion): ~$0.45
- Room (3 views): ~$0.45
- Prop (1 reference): ~$0.15

A project with 3 characters + 1 room + 1 prop = ~$1.50-$2.00 in reference sheets.

## Scene-Driven Sheet Design

### The Core Principle
If you ENVISION the scene — truly see it in your mind — the reference sheets design themselves. You don't need a separate "what sheets do I need?" step. The scenes TELL you.

A mother who never leaves a hospital bed doesn't need standing turnaround views. A father who is only ever hands/forearms in a POV sequence doesn't need a back view. A toddler seen from behind for 5 consecutive panels absolutely needs a back view and a top-down view.

**The failure mode:** Working mechanically — "every character gets a standard turnaround" — without actually SEEING the story. This produces beautiful sheets that are completely useless for the actual panels you need to render.

### The Process: Scene → Sheet Design
1. **Read the scene plan end to end.** Actually envision each panel.
2. **For each character, list the PANELS they appear in** and what angle/pose they're in:
   ```
   Mother:
   - Panel 02: distant silhouette in bed, from doorway (12 feet)
   - Panel 06: in bed, face visible, from 10 feet
   - Panel 07: in bed, looking down at daughter, from 8 feet
   - Panel 08: in bed, hand on daughter's back, from 5 feet
   - Panel 09: in bed, shifted baby to far arm, from 4 feet
   - Panel 10: in bed, arm opening for daughter, from 3 feet
   - Panel 11: in bed, arm around daughter, watching her watch baby
   - Panel 14: in bed, looking directly at camera, eyes glistening
   → She is ALWAYS IN BED. Standing views = wasted.
   → Need: bed from doorway, bed from bedside, face close-up,
     hand reaching, arm around child, looking down at baby
   ```
3. **Each unique angle/pose becomes a grid slot.** If a character has more than 6 unique views, prioritize the most common or most important ones.
4. **Name the panels each slot serves.** If you can't name a panel → cut the slot.

### Questions That Drive Sheet Design
1. **Does this character ever stand up?** If no → no standing turnaround. All views should show their actual position.
2. **What's their most common position?** That position dominates the grid (e.g., 6/6 slots are bed poses for the mother).
3. **From which angles is this character seen?** Those angles go in the grid.
4. **What are the key emotional beats?** Those expressions go in the expression sheet — derived from scene plan, not generic.
5. **What body parts are most visible?** POV characters might need hand close-ups, not full body shots.
6. **Are they ever seen from behind?** If yes, back view is MANDATORY.
7. **Are they seen from above/below?** If yes, top-down/bottom-up view is MANDATORY.

### The Test
For every view in your reference sheet, complete this sentence: **"This view serves panel(s) [X] where the character is [doing Y] seen from [angle Z]."** If you can't complete it, you're wasting a grid slot.

### Examples of Scene-Driven vs Mechanical

**Mechanical (WRONG):** "Mother gets a standard turnaround: front, 3/4, side, 3/4 back, back, top-down."
→ She never stands. 5 of 6 views are useless.

**Scene-driven (RIGHT):** "Mother is in bed for panels 02-14. She needs: bed from doorway (distant), bed from bedside (close), face close-up, hand reaching, arm around daughter, looking down at baby."
→ Every view serves specific panels. Zero waste.

## Common Mistakes

1. **Combining multiple characters on one sheet** -- each entity gets its OWN sheet in its OWN folder. Never mix.
2. **Chaining across entities** -- daughter's sheet feeds daughter's sheets only. Not mother's.
3. **Skipping motion sheets for unusual actions** -- if a character does something non-standard (toddler climbing, unusual gait), a motion sheet prevents the model from guessing wrong.
4. **Rooms as flat images** -- rooms need multiple angles. The model needs spatial understanding, not just one view.
5. **Generating sheets before scene plan exists** -- sheets come FROM the scene plan. The scene plan defines WHO is there, WHAT they wear, HOW they move. Extract, don't invent.
6. **Not using figure-posing skill for motion sheets** -- motion sheet poses must use the full pose stack (line of action, weight, landmarks, foreshortening, push). Generic "standing" or "running" wastes the sheet.
7. **Forgetting "Same character" anchor in multi-pose sheets** -- without it, the model generates different-looking characters per pose.
8. **Random body parts from unspecified figures** -- if a pose involves interaction with another character, either fully describe them or leave them out. "Next to a larger figure" produces floating arms.
9. **Single-view character sheets** -- NEVER generate a single front-view portrait. Always 2x3 or 3x3 turnaround. One API call = 6-9 views. A single view wastes both generation cost AND gives the model blind spots for angles it needs.
10. **Generic turnaround views that don't serve the scene** -- don't fill all 6 slots with standard angles if the story needs specific poses. Replace the 6th slot (or more) with scene-specific views (seated in bed, seen from above, running away). The turnaround serves the STORY, not a generic character bible.
11. **Creating sheets without reading the scene plan first** -- if you don't know which angles and poses the panels require, your sheets will have the wrong views. Always trace: scene plan → required angles → turnaround design.