BeastyPage

A pixel cat gacha platform featuring generators, wheels, and collection tools built with ClanGen sprites.

Features

• Cat Generator - Generate random pixel cats with customizable traits, accessories, and tortie coats
• Gacha Wheel - Weighted wheel spins with animated reveals
• Catdex - Browse and search all generated cats in a Pokedex-style archive
• Adoption Generator - Roll whole litters, trim each round, finish with your favorites
• Visual Builder - Trait-by-trait sprite previews with instant updates
• Stream Tools - Live session controls for audience voting and shareable builds

Tech Stack

• Frontend: Next.js 16, React 19, TailwindCSS
• Backend: Convex (serverless database), FastAPI renderer service
• Package Manager: pnpm
• Deployment: Kubernetes via FluxCD, Docker containers

Quick Start

Prerequisites

• Node.js (v22+)
• pnpm (v10+)
• Convex account (for database)
• Python 3.11+ with uv (for renderer service)

Frontend

cd frontend
pnpm install
pnpm run dev

Open http://localhost:3000 in your browser.

Renderer Service (Optional)

The renderer service generates cat card images. If not running, the frontend will work but card generation will be unavailable.

cd backend/renderer_service
uv pip install --editable .
uv run uvicorn renderer_service.app.main:app --reload --port 8001

Environment Variables

Build-time (Frontend)

Variable	Description
CONVEX_DEPLOYMENT	Convex deployment identifier
NEXT_PUBLIC_CONVEX_URL	Convex cloud URL
NEXT_PUBLIC_POSTHOG_KEY	PostHog analytics key (optional)
NEXT_PUBLIC_POSTHOG_HOST	PostHog host URL (optional)

Convex deployment

Variable	Description
QUICK_SHARE_WORKER_URL	Public base URL Convex uses to dispatch Quick Share jobs (for example, https://beastyrabbit.com)

Runtime

Variable	Description	Default
PORT	Server port	3000
RENDERER_INTERNAL_URL	Renderer service URL	-

Project Structure

beastypage/
├── frontend/               # Next.js application
│   ├── convex/             # Convex functions and schema
│   ├── app/                # Next.js app router pages
│   └── Dockerfile          # Multi-stage build (pnpm → Node)
├── backend/
│   ├── renderer_service/   # FastAPI cat renderer
│   │   └── Dockerfile      # Python/uv build
│   └── README.md
├── lifegen-fullgen/        # LifeGen sprite generation library
└── .github/workflows/      # CI/CD pipelines

Container Images

Images are automatically built and pushed to GHCR on pushes to main:

• ghcr.io/beastyrabbit/beastypage-frontend:latest
• ghcr.io/beastyrabbit/beastypage-renderer:latest

Running with Your Own Database

The frontend image uses a placeholder for the Convex URL at build time. Provide your own Convex instance at runtime:

docker run -p 3000:3000 \
  -e NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud \
  ghcr.io/beastyrabbit/beastypage-frontend:latest

Kubernetes Deployment

For Kubernetes/Talos deployments, configure the Convex URL via ConfigMap or Secret:

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: frontend
          image: ghcr.io/beastyrabbit/beastypage-frontend:latest
          env:
            - name: NEXT_PUBLIC_CONVEX_URL
              valueFrom:
                secretKeyRef:
                  name: beastypage-secrets
                  key: convex-url

Credits

ClanGen Sprites

Cat sprites originate from ClanGen, licensed under CC BY-NC 4.0.

• Original creator: just-some-cat.tumblr.com
• Fan-edit creator: SableSteel and others

LifeGen

Built with components from LifeGen, a ClanGen mod.

Pixel Cat Maker

Additional tooling from Pixel Cat Maker.

License

• Code: MPL-2.0 (Mozilla Public License 2.0)
• Sprites/Art: CC BY-NC 4.0 (NonCommercial)

See LICENSE.md for full details.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.