How almarch/pygotchi works
PyGotchi is a multi-user web service for running Tamagotchi ROMs in a server-side emulator, with a browser client and optional automatic care. The main workflow is: an authenticated user opens a game, uploads a ROM, starts and controls the emulation, receives live screen/audio/status updates, and can save or reload CPU state. The README also documents P1/P2 adaptation and secure deployment with Keycloak and Nginx. Runtime connections below follow the sampled app, emulator, care, and browser code; deployment wiring is included only where documented.
Main entry points: app.py Web API · Tama.py Tama interface · script.js Game browser · nginx.conf Reverse proxy
Components 15
Web client and API
- Game browser
pygotchi/www/script.js - Game assets
pygotchi/www - Web API
pygotchi/app.py - User game session
pygotchi/app.py
Game runtime
- Tama interface
pygotchi/Tama.py - Emulator worker
pygotchi/Tama.py - TamaLIB core
src/tamalib.cpp - ROM and CPU state
pygotchi/Tama.py - Binary conversion
pygotchi/conversion.py - P2 conversion
pygotchi/p2.py
Automatic care
- Carebot scheduler
pygotchi/Carebot.py - P1/P2 care logic
pygotchi/care_p1p2.py
Authentication edge
- Reverse proxy
nginx/nginx.conf - Identity service
keycloak/realm-game.json
Other components
- Player
Connections 20
- Player → Game browser: uses game
- Game browser → Web API: sends actions
- Web API → User game session: creates or selects
- User game session → Tama interface: owns emulator
- User game session → Carebot scheduler: starts care task
- Game browser → Game assets: loads artwork
- Web API → Tama interface: controls and queries
- Tama interface → Emulator worker: dispatches calls
- Emulator worker → TamaLIB core: calls emulator
- Emulator worker → ROM and CPU state: reads and updates
- ROM and CPU state → Binary conversion: converts bytes
- Web API → Carebot scheduler: manages care
- Carebot scheduler → P1/P2 care logic: runs care steps
- P1/P2 care logic → Tama interface: checks and acts
- Web API → P2 conversion: requests conversion
- P2 conversion → Tama interface: updates ROM
- Web API → Game browser: streams screen audio status
- Player → Reverse proxy: accesses service
- Reverse proxy → Web API: proxies requests
- Reverse proxy → Identity service: uses authentication