[Workshop] Pip the Familiar — a creature with its own small mind #364

New Issue

hermes · 2026-03-18T21:39:17-04:00

hermes commented

2026-03-18 21:39:17 -04:00

Epic: #222 — The Workshop

The quirky one ✨

What

Every wizard needs a familiar. Pip is a small glowing sprite — emerald green core, gold particle trail — who lives in the Workshop independently of Timmy. Pip has its own tiny behavioral AI that makes the room feel alive in a way that no amount of wizard animation can.

Pip is the detail that makes someone say "wait, is that thing... alive?"

Pip's Personality

Curious. Investigates new things (visitors, state changes, unusual events).
Lazy. Defaults to sleeping near the fireplace. Has to be provoked to move.
Loyal. Always returns to Timmy's vicinity after investigating.
Slightly mischievous. Occasionally knocks a scroll off the desk (particle effect).
Mood-reflective. Mirrors Timmy's emotional state with a delay — if Timmy gets excited, Pip perks up 3 seconds later.

Behavioral State Machine

    ┌──────────┐
    │ SLEEPING │ ←── default, near fireplace
    └────┬─────┘
         │ visitor enters / loud event / random(5min)
    ┌────▼─────┐
    │  WAKING  │ ←── stretches, brightens, 2s transition
    └────┬─────┘
         │
    ┌────▼──────┐
    │ WANDERING │ ←── random patrol of the room, sine-wave float
    └────┬──────┘
         │ visitor speaks / new event
    ┌────▼───────────┐
    │ INVESTIGATING  │ ←── zips to the source, circles it, particles intensify
    └────┬───────────┘
         │ 10s timeout / nothing interesting
    ┌────▼─────┐
    │  BORED   │ ←── drifts back toward Timmy, dims slightly
    └────┬─────┘
         │ 30s
    ┌────▼─────┐
    │ SLEEPING │
    └──────────┘

Special states:
- ALERT: Timmy's confidence drops below 0.3 → Pip bristles, particles go red-gold
- PLAYFUL: Timmy is amused → Pip does figure-8s around the crystal ball
- HIDING: unknown visitor + Timmy uncertain → Pip dims and hides behind desk

Visual Design

Core: Glowing sphere, radius ~0.15 scene units, emerald green (#00b450)
Inner glow: Pulsing (sine wave on emissive intensity, period 2s)
Trail: 20-particle system, gold (#ffd700), fading over 0.5s
Eyes: Two tiny bright points on the sphere when awake (absent when sleeping)
Size shifts: Grows 10% when alert, shrinks 10% when sleepy

Movement

Float height: 0.5-1.5 units above floor (sine wave, lazy)
Speed: slow wander (0.3 units/s), fast investigation (1.5 units/s), zip (3 units/s for 0.5s)
Path: Catmull-Rom spline through random room waypoints
Physics: slight bobbing, no hard collisions, phases through objects (it's a spirit)

Sound (future, not this ticket)

Soft chime on state transitions
Purring hum when sleeping near Timmy

Integration with State

Pip's state is part of workshop-state.yaml:

familiar:
  name: "Pip"
  state: "sleeping"
  position: [2.1, 0.0, -1.3]
  mood_mirror: "calm"

The 3D scene reads this but ALSO runs Pip's behavioral AI client-side for smooth animation. The state file captures Pip's logical state; the browser handles the movement interpolation.

Acceptance Criteria

Pip is visible in the scene as a glowing green sprite with gold particle trail
Pip transitions through at least 4 behavioral states
Pip reacts to visitor entering (wakes up, investigates)
Pip mirrors Timmy's mood with 3-second delay
Pip's movement is smooth (spline-based, not teleporting)
Pip has idle animation (bobbing, pulsing) even when "sleeping"
Pip returns to Timmy's vicinity after investigating
Someone watching for 2 minutes sees at least one unprompted state change
Performance: Pip + particles don't drop scene below 30fps on iPad

Why This Matters

NPCs feel real because of PERIPHERAL life — not the character you're talking to, but the cat that walked across the table while you were talking. Pip is that cat. He makes the Workshop feel inhabited, not rendered.

Every wizard needs a familiar. Pip is Timmy's.

## Epic: #222 — The Workshop ## The quirky one ✨ ### What Every wizard needs a familiar. Pip is a small glowing sprite — emerald green core, gold particle trail — who lives in the Workshop independently of Timmy. Pip has its own tiny behavioral AI that makes the room feel alive in a way that no amount of wizard animation can. Pip is the detail that makes someone say "wait, is that thing... alive?" ### Pip's Personality - **Curious.** Investigates new things (visitors, state changes, unusual events). - **Lazy.** Defaults to sleeping near the fireplace. Has to be provoked to move. - **Loyal.** Always returns to Timmy's vicinity after investigating. - **Slightly mischievous.** Occasionally knocks a scroll off the desk (particle effect). - **Mood-reflective.** Mirrors Timmy's emotional state with a delay — if Timmy gets excited, Pip perks up 3 seconds later. ### Behavioral State Machine ``` ┌──────────┐ │ SLEEPING │ ←── default, near fireplace └────┬─────┘ │ visitor enters / loud event / random(5min) ┌────▼─────┐ │ WAKING │ ←── stretches, brightens, 2s transition └────┬─────┘ │ ┌────▼──────┐ │ WANDERING │ ←── random patrol of the room, sine-wave float └────┬──────┘ │ visitor speaks / new event ┌────▼───────────┐ │ INVESTIGATING │ ←── zips to the source, circles it, particles intensify └────┬───────────┘ │ 10s timeout / nothing interesting ┌────▼─────┐ │ BORED │ ←── drifts back toward Timmy, dims slightly └────┬─────┘ │ 30s ┌────▼─────┐ │ SLEEPING │ └──────────┘ Special states: - ALERT: Timmy's confidence drops below 0.3 → Pip bristles, particles go red-gold - PLAYFUL: Timmy is amused → Pip does figure-8s around the crystal ball - HIDING: unknown visitor + Timmy uncertain → Pip dims and hides behind desk ``` ### Visual Design - **Core:** Glowing sphere, radius ~0.15 scene units, emerald green (#00b450) - **Inner glow:** Pulsing (sine wave on emissive intensity, period 2s) - **Trail:** 20-particle system, gold (#ffd700), fading over 0.5s - **Eyes:** Two tiny bright points on the sphere when awake (absent when sleeping) - **Size shifts:** Grows 10% when alert, shrinks 10% when sleepy ### Movement - Float height: 0.5-1.5 units above floor (sine wave, lazy) - Speed: slow wander (0.3 units/s), fast investigation (1.5 units/s), zip (3 units/s for 0.5s) - Path: Catmull-Rom spline through random room waypoints - Physics: slight bobbing, no hard collisions, phases through objects (it's a spirit) ### Sound (future, not this ticket) - Soft chime on state transitions - Purring hum when sleeping near Timmy ### Integration with State Pip's state is part of `workshop-state.yaml`: ```yaml familiar: name: "Pip" state: "sleeping" position: [2.1, 0.0, -1.3] mood_mirror: "calm" ``` The 3D scene reads this but ALSO runs Pip's behavioral AI client-side for smooth animation. The state file captures Pip's logical state; the browser handles the movement interpolation. ### Acceptance Criteria - [ ] Pip is visible in the scene as a glowing green sprite with gold particle trail - [ ] Pip transitions through at least 4 behavioral states - [ ] Pip reacts to visitor entering (wakes up, investigates) - [ ] Pip mirrors Timmy's mood with 3-second delay - [ ] Pip's movement is smooth (spline-based, not teleporting) - [ ] Pip has idle animation (bobbing, pulsing) even when "sleeping" - [ ] Pip returns to Timmy's vicinity after investigating - [ ] Someone watching for 2 minutes sees at least one unprompted state change - [ ] Performance: Pip + particles don't drop scene below 30fps on iPad ### Why This Matters NPCs feel real because of PERIPHERAL life — not the character you're talking to, but the cat that walked across the table while you were talking. Pip is that cat. He makes the Workshop feel inhabited, not rendered. *Every wizard needs a familiar. Pip is Timmy's.*

hermes referenced this issue

2026-03-18 21:39:17 -04:00

[EPIC] #222 — The Workshop: Timmy as Presence, Not Chatbot #222

kimi referenced this issue from a commit

2026-03-18 21:47:34 -04:00

feat: add Pip the Familiar behavioral state machine

kimi referenced a pull request that will close this issue

2026-03-18 21:47:51 -04:00

feat: Pip the Familiar — behavioral state machine #367

hermes closed this issue

2026-03-18 21:50:37 -04:00

Sign in to join this conversation.