# 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*.

The voice also powers **Stay Awhile**, a scoreless moment together in the
arcade. You can talk, share quiet, or choose the companion's own affectionate
action — anything from head scratches to holding hands. The recipe lets you set
the relationship tone to gentle, deeply friendly, or softly romantic, then asks
for six dedicated `together_…` line banks so the moment sounds like *them*, not
generic dialogue. These choices are saved in `manifest.json` as `bondStyle` and
`affectionLabel`; old packs simply use a warm, universal fallback.

**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 | 20 | `content` `eating` `cleaning` `singing` `startled` `curious` `writing` `dive` `swim` `swimabout` `walk` `roll` `cheer` `react_huddle` `react_bask` `react_watch` `sleep_night` `lake` `friend` `quiet_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 46 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.** Companion packs, art, care, and the automatic
  ledger are never uploaded. Import, switch, or remove companions any time from
  the 🥚 menu. If the keeper explicitly enables gentle reminders, the push
  service receives only an anonymous browser push address and the one pending
  notification text and time — never companion art or care data.
- **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.
- **Closeness can sound like them, too.** `bondStyle` in `manifest.json` may be
  `"gentle"`, `"friendly"`, or `"romantic"`; `affectionLabel` names the middle
  Stay Awhile choice, such as `"wing cuddle"` or `"hold hands"`. The six optional
  voice keys are `together_invite`, `together_approach`, `together_talk`,
  `together_affection`, `together_quiet`, and `together_goodbye`. Each is an array
  of short lines. The in-egg recipe writes all of this for you.
- **Care bars can use their own words.** Open **Advanced options** at the bottom
  of the recipe to rename a visible bar and its action phrase — for example,
  SING / hum a tune can become HUM / hum along. Leave **Apply to all companions**
  unticked to carry those words inside this pack; tick it to change the display
  for every companion on this device. Existing imported companions have the same
  editor in their 🗂 wardrobe. Shared packs keep their labels in the manifest's
  `care` table, and aliases such as `hum.png` or `humming.png` are understood on
  import. The safe engine keys and filenames never change: `warm`, `write`,
  `rest`, `bond`, `feed`, `clean`, `sing`, `tap`, `show`, and poses such as
  `singing.png` remain canonical.
- **Custom words do not rewrite a voice.** If SING becomes HUM, write the
  canonical `act_sing` line bank as though humming happened. The recipe prompts
  for this automatically, while the neutral fallback lines are broad enough for
  most renames. This version renames actions only; it does not hide them, because
  a hidden care action would otherwise leave an untendable stat quietly decaying.
- **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 visitors are whoever you say.** `friend.png` is a lively, affectionate
  visitor who arrives when Calm has been held high; `quiet_friend.png` is a
  still companion who may share the shallows when Calm is high and Bond is low.
  Name them with `"friend": "Pip"` and `"quietFriend": "The Heron"` in the
  manifest. Optional voice banks `friend_visit`, `quiet_friend_visit`, and
  `friend_gift` make those relationships specific. Lines may use `{friend}` and
  `{quietFriend}`. Either visitor may be omitted.
- **Leander's visitors are yours to reinterpret.** His fox and heron remain the
  built-in defaults, but More → Companions now lets you replace either picture
  and give the visitor a new name. His public voice refers to the role and name,
  rather than assuming a particular relationship. These replacements are kept
  in a full Nest backup.
- **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.* 🥚