GitMon Engine

The open-source sprite engine & world toolkit behind gitmon.io
Your GitHub activity feeds, trains, and evolves a persistent pixel-art creature.

---

What is GitMon?

GitMon is a virtual pet platform where every developer gets a unique pixel-art creature tied to their GitHub activity. Commits feed it, PRs train it, and inactivity makes it hungry. This repository contains the self-contained engine — no auth, no database, no network required.

  Commit → XP gained → Level up → Evolution!
  
  Egg (lv0) → Baby (lv1-14) → Teen (lv15-34) → Adult (lv35+)

Species Gallery

Atom	Bat	Bear	Black Hole	Cat
Cyclops	Dementor	Dragon	Ghost	Lion
Minotaur	Monkey	Owl	Phoenix	Robot
Shark	Slime	Snake	Unicorn	Wolf

All sprites are hand-crafted 64x64 pixel art with idle and walk animations (192x64 spritesheets, 3 frames at 8 FPS).

Architecture

gitmon-oss/
├── src/
│   ├── lib/
│   │   ├── sprite-engine/     # Animation state machine + palettes + procedural fallback
│   │   │   ├── state-machine.ts
│   │   │   ├── palettes.ts
│   │   │   └── procedural.ts
│   │   ├── world/             # Spatial math, proximity, sentiment, scripted lines
│   │   │   ├── constants.ts
│   │   │   ├── proximity.ts
│   │   │   ├── sentiment.ts
│   │   │   └── scripted-lines.ts
│   │   ├── i18n/              # Lightweight i18n (no deps)
│   │   └── services/
│   │       └── ai-fallback.ts # Offline chat fallback lines
│   └── components/
│       └── locale-switcher.tsx
├── extension/                 # Chrome MV3 content-script mirror
├── scripts/                   # PixelLab sprite generation pipeline
├── public/sprites/            # 20 species × 4 stages (egg/baby/teen/adult)
├── examples/showcase/         # Vite demo app — see it running!
└── types/

Quick Start

# Clone
git clone https://github.com/brunobracaioli/gitmon-oss.git
cd gitmon-oss

# Install
npm install

# Type check
npm run typecheck

# Run the showcase demo
npm run showcase
# → opens http://localhost:5173 with animated species viewer

What's Inside

Sprite Engine

The core animation system. Frame-by-frame 64x64 pixel art on HTML5 Canvas, 8 FPS, nearest-neighbor scaling.

import { SpriteStateMachine } from './src/lib/sprite-engine';

// Drives idle → walk → sleep → dead transitions
const sm = new SpriteStateMachine('dragon', 'adult');
sm.transition('walk');
// → returns frame data for rendering

Features:

• State machine with idle, walk, sleep, dead, happy, sad, critical, hatching states
• Species-specific color palettes with procedural fallback renderer
• Canvas effects (filters, overlays) for emotional states — no extra sprite sheets needed

World Math

Spatial utilities for the shared GitMon world (320x240 tile map).

• Proximity scanner — spatial bucket lookup for nearby entities
• Sentiment scoring — rule-based mood classification for NPC conversations
• Scripted lines — weighted random openers/reactions per emotion state
• Constants — SPRITE_PX=64, TILE_SIZE=32, chunk dimensions

Species Pipeline

Generate new species sprites using PixelLab AI:

# Requires PIXELLAB_SECRET env var
npm run regen -- --species dragon --stage adult --type idle

# Promote a species to production
npm run promote -- --species dragon

Evolution Stages

Each species has 4 visual stages that unlock as your GitMon levels up:

Stage	Level	Visual
Egg	0	Small, round, species-colored egg
Baby	1-14	Tiny creature, simple features
Teen	15-34	Larger, more detail, walk animation
Adult	35+	Full size, all animations, final form

XP formula: floor(50 * level^1.5) per level.

Showcase Demo

The examples/showcase/ directory contains a standalone Vite app that renders animated species:

npm run showcase        # dev server
npm run showcase:build  # production build

Environment

The engine itself has zero runtime secrets. Only the sprite generation scripts need a key:

Variable	Required	Purpose
PIXELLAB_SECRET	Only for npm run regen	PixelLab API key for sprite generation

Sprite Specifications

Property	Value
Native size	64x64 pixels
Idle sheet	64x64 (single frame)
Walk sheet	192x64 (3 frames)
Frame rate	8 FPS
Scaling	Nearest-neighbor (no anti-aliasing)
Format	PNG with transparency

Contributing

See CONTRIBUTING.md for guidelines. In short:

• Bug fixes in sprite engine, world math, or species pipeline are welcome
• New species PRs (open a discussion first)
• Additional i18n translations
• Performance improvements with benchmarks

The Full GitMon Experience

This repo is the engine. The full platform at gitmon.io adds:

• GitHub OAuth login
• Real-time activity tracking (commits, PRs, issues, stars)
• Shared multiplayer world with NPC conversations
• AI personality system (5 traits, client-side LLM)
• Cosmetics shop with GitCoins economy
• Chrome extension (sprite on github.com)
• Public profiles with dynamic OG images
• Leaderboards and achievements

License

Apache License 2.0 — use it, fork it, build with it.

---

_{Egg → Baby → Teen → Adult}

_{Made with pixel love by @brunobracaioli}