# Fable Nest — hatching your companion

Fable Nest can keep *any* small creature — a cat, a dragon, a moss golem,
your own character. You don't need to draw, and you don't need to pay for
anything new: your own AI (ChatGPT, Claude, Gemini — whatever you already
use) does the painting, and the egg does the rest.

The whole thing is three moves:

**1. Get your recipe.**
In the egg: ⚙ → **🥚 companions** → **✍ Get a recipe for your AI**.
Answer a few short questions — name, pronouns, what they are, art style,
personality, how they move, and who plays the arcade games — and the egg writes a complete, ordered
document of prompts. Copy it all, or download it.

**2. Cook it with your AI.**
Paste the recipe into a fresh chat with your AI and follow along. A few
field notes from real kitchens:

- **One step at a time.** Your AI won't march through the whole recipe
  alone — paste a step, collect the images, say *next*.
- **About 10 images per sitting** is what image models manage — split the
  optional poses over sittings if you're going big.
- **Backgrounds don't matter.** If images come back with fake
  checkerboard or solid backgrounds, ignore it — the egg strips
  backgrounds automatically when you import. Only the character and the
  pose need to be right.
- **The arcade pet gets a fresh chat.** Image models imitate their own
  recent work — in the same chat, your pet will come out wearing your
  companion's face.

And two things matter more than everything else:

- **The anchor rule.** The recipe has your AI make the `idle` image first,
  then stop. Don't rush past this — regenerate until the character looks
  *right*, because every other image is matched to this one. From then on,
  **attach the approved idle image to every later prompt**. That's what
  keeps your companion looking like themselves across fifteen pictures.
- **The filenames.** Save each image under the exact name the recipe gives
  (`idle`, `blink`, `happy`, `wistful`, `sleepy`, `loved`, …). The egg reads the
  names, not the pictures.

Six images make the recommended base companion — five core moods plus a
closed-eye `blink` still that the egg overlays at natural intervals. Grounded
companions breathe subtly from their feet; floating companions keep the waterline
sway. Older five-image packs still work, but do not blink. Everything past six is bonus richness:
more poses, animation, game sheets, a background. If your AI can run code
(ChatGPT and Claude can), the recipe shows it how to build real
animations and even zip the finished pack for you. If it can only make
images (Gemini, nano banana), stills are genuinely enough.

Don't forget the voice: the recipe includes a prompt that has your AI
write `lines.json` — everything your companion says, in their own
personality. Text is the thing chat AIs are best at. This is where they
become *themselves*.

**3. Bring it home.**
Put everything in one folder with `manifest.json` and `lines.json`, zip
it (or let your AI zip it), then: ⚙ → **🥚 companions** →
**Import a companion pack**. The egg shows you a little report card of
what it found — what's there, what's missing, what will fall back
gracefully — and then they hatch.

## What's involved — the two builds

**The minimum build** *(one cosy afternoon)* — enough for a companion who lives:

| piece | count | what it is |
|---|---|---|
| `manifest.json` | 1 | their name, pronouns, stance, tagline |
| `idle` | 1 image | their resting pose — the only truly required picture |
| `blink` | 1 image | the exact idle pose with only the eyes gently closed |
| core moods | 4 images | `happy` · `wistful` · `sleepy` · `loved` |
| `lines.json` | 1 | their voice — text is the thing chat AIs are best at |
| `background` | 1 image | their home behind the glass |

**9 files.** Anything missing falls back gracefully — a five-mood companion is
always whole, while the sixth still adds blinking. Moods you skip borrow the nearest pose; lines you skip use the
gentle neutral voice.

**The full build** *(a weekend of generating, worth every minute)*:

| piece | count | slots |
|---|---|---|
| base expressions | 6 | `idle` `blink` `happy` `wistful` `sleepy` `loved` |
| extra poses | 19 | `content` `eating` `cleaning` `singing` `startled` `curious` `writing` `dive` `swim` `swimabout` `walk` `roll` `cheer` `react_huddle` `react_bask` `react_watch` `sleep_night` `lake` `friend` |
| arcade art | 8 | `game_idle` `game_run_sheet` `game_swim_sheet` `game_eat_sheet` `game_cheer_sheet` `game_pout_sheet` `game_treat` `game_hazard` |
| backgrounds | up to 3 | `background` (all day) · `background2` (night) · `background3` (evening) |
| keepsakes | up to 9 | `curio1` … `curio9` — the little treasures you show them |
| words | 2 | `manifest.json` + `lines.json` |

**Up to 45 images + 2 text files.** Every one of them optional except `idle` —
build up from the minimum at whatever pace your art generator (and patience)
allows. The **＋** button on their row accepts new pieces any time.

## Good to know

- **Packs stay on your device.** Nothing is uploaded anywhere. Import,
  switch, or remove companions any time from the 🥚 menu.
- **Back up the whole nest.** More → **⬆ back up everything** saves the life,
  companions, voices, art, themes, and settings in one `.fable` file. Keep it
  somewhere safe before changing phones. The ⬆ beside an individual companion
  still exports a shareable companion-only zip.
- **The built-in residents stay.** Leander, Mossbit, and Elsy are always available —
  waking a new companion never loses them. Each companion keeps their own care bars,
  bond, mood, age, and ledger. Only the resident who is awake changes; everyone else
  rests safely with their needs paused. Tap any of their rows to wake them again.
- **Missing pieces are fine.** No `lines.json`? They speak with a gentle
  neutral voice. Missing poses? The nearest pose stands in. Only `idle`
  is truly required.
- **The background trick.** Image models can't make real transparency — ask
  for it and you often get a *painting of* transparency (that grey checkerboard).
  So the recipe asks for ONE flat colour that never appears in your companion —
  **pure magenta `#FF00FF`**, old sprite-sheet style — and the egg keys it out
  perfectly on import, enclosed corners, edges and all. Pink companion? Use pure
  green `#00FF00`. White-ish and checkerboard backgrounds still get cleaned too;
  magenta is just the spotless path. One rule though: **nothing but the
  companion in the picture** — caption bars, labels, or watermarks aren't
  magenta, so they survive the key and show up in the glass.
- **Pronouns are theirs.** Add `"pronouns": "she"` (or `"he"`, `"they"`)
  to `manifest.json` and every built-in line bends to match. Your
  `lines.json` can use `{they} {them} {their} {theirs} {themself}` too —
  plus `{are}`/`{have}`, which conjugate ("they are" / "she is"), and
  capitalised forms like `{They}` for starting a sentence.
- **Scenes want to be opaque.** Backgrounds sit behind everything —
  any transparent or semi-transparent patch in a `background` image shows
  the egg shell through it like a hole in wallpaper. The importer warns
  you if it spots one.
- **Animated images:** looping `.webp` files just play — but no model
  needs to make one. A plain `.png` sheet of frames animates natively:
  a wide strip of frames is detected by its shape, and a **grid** (2+
  rows, 4+ frames) is detected by its layout. Put `sheet` in the
  filename to force slicing on anything ambiguous. Frames need clear
  gaps of background between them — poses that touch get fused, and a
  fused sheet falls back to showing as one still (that's the "all my
  frames at once" look; regenerate with more space between poses).
- **Blinking needs only one still.** `blink.png` should match `idle` exactly in
  pose, scale, and placement, with only the eyelids closed. The egg supplies the
  timing; do not make it a sheet. It is used for grounded companions during idle
  moments and quietly ignored when absent.
- **Kind limits keep phones safe.** A pack may contain up to 128 files, with
  a 50 MB zip and 96 MB expanded total. Individual images may be up to 24 MB,
  8192 pixels on either side, and 24 megapixels. Ordinary generated assets are
  far below these limits.
- **The visitor is whoever you say.** Someone small comes to visit now
  and then (the `friend.png` slot holds their picture). Add
  `"friend": "Pip"` to the manifest — a friend's name, a beloved's,
  anyone — and the visit is announced with their name instead of
  "A Visitor".
- **Everyone is renamable.** The ✎ on a companion's row renames them
  without starting over — and the resident otter answers to whatever
  name you give him, too. His stages follow along (Baby Fergus, Young
  Fergus…).
- **The wardrobe.** The 🗂 on a companion's row shows every picture in
  their pack; ✕ removes one (poses fall back gracefully — only `idle`
  is fixed). To swap a picture, just re-import it via ＋ — same-name
  files replace.
- **One sheet of keepsakes works too.** Models love handing out all the
  curios in a single grid image — that's fine: name it `curios.png` (no
  number) and the egg splits it into `curio1`–`curio9` automatically.
  Text captions and grid lines in the image are dropped; the cabinet
  takes the names from your manifest's `curios` list, in reading order.
- **Facing rules,** if you go deep: `dive` art faces **left**, `swim` art
  faces **right**. The recipe reminds your AI at the right moments.
- **Share them!** The **⬆** on a companion's row downloads their whole
  pack as a zip — send it to a friend and they hatch in someone else's
  egg, voice and keepsakes and all.

## Make the Nest yours — themes, shells, and companion size

- Open **More → Theme** to choose from **45 complete themes**. Each one
  changes the physical egg shell, colours, atmosphere, and lettering.
- Scroll to **Tweak it** inside the theme sheet to recolour the selected
  theme and choose different display and reading fonts. **Reset to
  preset** safely returns that theme to its original design.
- Open **More → Companions** and use **A−** or **A+** beside Mossbit,
  Elsy, or any imported companion to resize them between 60% and 160%.
  Each companion remembers their own size, so a tall moth and a round
  lake imp can both sit comfortably in the same glass.
- Theme changes, custom colours, companion sizes, and uploaded shells
  stay on the device and are included by **back up everything**.

## The shell — the egg around them *(optional)*

The outer shell is art too, and you can make your own — the egg accepts
up to five custom shells (⚙ → 🎨 theme → **＋ Upload your own shell**).

1. **Grab a reference.** Pick any theme, then **⬇ Download this shell
   as a reference** in the theme sheet. Your image AI copies proportions
   far better from a picture than from words.
2. **Ask for a new one.** Attach the reference, choose **Copy the
   egg-shell prompt**, replace `[YOUR AESTHETIC]`, and paste it into your
   image AI:

   > Using the attached shell image only as a layout reference, create
   > a new tall egg-shaped virtual-pet device in [YOUR AESTHETIC]. Keep
   > the reference's portrait canvas proportions, centred silhouette,
   > overall scale, screen position, and three-button layout; show the
   > complete device with nothing cropped. Place one large rounded
   > screen opening in the upper middle, centred horizontally, about
   > 43% of the canvas width and 32% of its height, with one clean
   > uninterrupted border. Fill that entire screen opening with
   > perfectly flat solid PURE MAGENTA (#FF00FF): no shading,
   > reflections, texture, character, scenery, text, or symbols inside
   > it, and use that exact magenta nowhere else. Put three separate
   > small round buttons in one row below the screen and a small hanging
   > loop at the top. Decorate the surrounding shell in [YOUR
   > AESTHETIC], but do not add other large holes or openings. Use a
   > plain or transparent background outside the device. Return a
   > portrait PNG at the reference image's exact pixel dimensions if
   > possible.
3. **Upload it.** The magenta window is cut out automatically (same
   trick as the companion art — models can't do real transparency, so
   the egg does it), the glass seats itself in the hole, and the touch
   buttons land on the three studs. A PNG with a genuinely transparent
   window works too, if your tool can make one.
4. **Or just edit ours.** Download any shell and recolour, redecorate,
   collage — whatever you like. They're yours to play with.

If the glass sits slightly off inside your shell, the window finder
aims for the largest see-through region — make sure the screen window
is the biggest opening in the artwork (bigger than any gaps in the
filigree).
- **Forgot a pose? Made more art later?** Every companion's row has a
  **＋** — add pictures to an existing pack any time. Matched poses fill
  in (or replace the old one), and anything the egg can't place gets the
  same point-and-assign step.
- **Something looked wrong on import?** The report card says what and
  why. Fix the filename or the image and import again — re-importing is
  cheap and harmless.

*Made with the Hatchery. Pudor sed liber.* 🥚