README.md

Atmochi (proof of concept) #

A virtual pet for the Atmosphere. It eats the records you create in other AT Protocol apps.

Run it #

npm install
npm run dev

Open http://127.0.0.1:3000 (use 127.0.0.1, not localhost: AT Proto loopback OAuth requires it; the client redirects there itself).

  • / : sign in, hatch, feed, tickle, room.
  • /dev/preview : the room, panels, eating and tickle with sample data, no sign-in (dev only).
  • /dev/game and /dev/visit : the real game screen and a friend's room as a pretend signed-in account (dev only; used by the end-to-end tests).

Tests #

npm test            # unit + component tests (Vitest), a few seconds
npm run test:e2e    # browser journeys (Playwright), starts the dev server itself
npm run test:all    # both
  • tests/unit/ : game rules and pure logic (pet, food, catalog, room placement, holidays, pixel art, share cards). Plain Node.
  • tests/integration/ : components (React Testing Library in jsdom) and the data layer and API routes, with the network faked (tests/helpers/data-fake-network.ts).
  • tests/e2e/ : full journeys on the dev harness pages (/dev/game, /dev/visit, /dev/preview, pretend accounts, no real repo) as desktop Firefox, a phone-sized Firefox and an iPhone (WebKit). Everything outside localhost is stubbed (tests/e2e/helpers/network.ts).
  • First time: npx playwright install firefox webkit.
  • Found a bug? Write the test for the right behavior first, watch it fail, then fix it.

What the POC does #

  1. Sign in with AT Proto OAuth (browser client, loopback in dev). Scopes: atproto repo:dev.arigonzalez.atmochi.pet repo:dev.arigonzalez.atmochi.room.
  2. Hatch a blob: writes dev.arigonzalez.atmochi.pet/self with zero diet and fedThrough = now; describeRepo fills the taste journal ("sniff").
  3. Feed when you choose: each visit looks for records created after fedThrough in every collection (capped at 150 per collection) and shows them as "snacks waiting". Nothing is eaten until you press Feed. Then each record maps to a diet stat (src/lib/atmochi/food.ts), old scores fade (half-life 7 days), the happiness bonus applies (1x to 1.5x), and the pet is written back with swapRecord so two tabs can't overwrite each other. With nothing new, it nudges you toward your favorite apps and stumble.at.
  4. Blob sprite (16x16, pastel) with idle, blink, eating, happy and giggle frames.
  5. Tickle minigame (15 s). Score becomes happiness through one shared converter (play()): max 20 per game, 30 per day.
  6. Points and rewards: eating banks points in seven categories (Everyday, Music, Social, Code, Writing, Creative, Curiosity). Points never fade. Each category's shop has mystery tiers: a Small, Medium or Large reward draws a random item from that tier's pool (preferring items you don't own yet) in a random color, with one free color reroll. Five categories also have an evolution, shown as a "?" until the pet has been that form. The pet hatches in a random color, and a dye (40 points from any category) changes it. Prices, pools and colors are all in src/lib/atmochi/catalog.ts.
  7. Room starts bare (plain wall and floor). Owned items are yours forever: place, swap and put them away freely (wallpaper and flooring included). Live items: the record player (latest teal.fm play) and the TV (Streamplace stream). Ownership lives on the pet record (bank, inventory); the room record only stores which owned item sits in which slot.

Layout #

  • src/lib/atmochi/ : pure logic (pet.ts, food.ts, time.ts), repo reads and writes (repo.ts), room and live items (room.ts).
  • src/components/ : UI. Pixel art lives in sprites.ts as strings.
  • lexicons/dev/arigonzalez/atmochi/ : draft lexicons for pet and room.

Notes #

  • Records can't hold floats, so scores are stored as integers in hundredths.
  • OAuth client_id is <origin>/oauth-client-metadata.json on whatever origin serves the app (see src/lib/oauth.ts), so the Vercel URL and a custom domain both work. The origin must not redirect. After deploying, check the hosted metadata: client_id must equal its own URL.
  • Which app feeds which category: hand-written rules in src/lib/atmochi/food.ts win; next comes src/lib/atmochi/apps.json, a snapshot of the atstore.fyi app directory (refresh it with npm run snapshot:apps and review the diff); anything else is a Curiosity snack.
  • See docs/atmochi-plan.md for the full design.