PromptPlay

Describe a game. Play it instantly. PromptPlay is a browser-first platform where anyone can generate a playable 3D game by typing a prompt. No download. No code.

---

Table of Contents

• Overview
• How It Works
• Tech Stack
• Monorepo Structure
• Prerequisites
• Quick Start
• Environment Variables
• Scripts Reference
• Documentation
• Contributing

---

Overview

PromptPlay lets you type a sentence like "A neon survival arena with three enemy types" and get a playable 3D browser game in seconds. The AI generates a structured GameSpec document — not code — which drives a real-time Babylon.js engine running directly in your browser.

v1 feature set (first public playable build):

Feature	Description
🤖 AI Game Generation	GPT-4o streaming via SSE, validated GameSpec JSON
🎮 3D Browser Engine	Babylon.js 7 (WebGPU → WebGL2 fallback)
🔗 Instant Sharing	Every published game gets a slug URL (/play/my-game)
📚 Game Library	Browse all published games, filter by genre and tag
🔒 Auth	JWT + refresh rotation, Google OAuth, email verification
📊 Creator Dashboard	Your games, play counts, monthly AI generation quota

Not in v1 (see ROADMAP.md):

• Multiplayer / co-play
• Marketplace and payments
• Social graph (friends, notifications)
• Admin panel
• Custom 3D asset upload

---

How It Works

User types prompt
  → POST /ai/generate (SSE stream)
    → GPT-4o generates GameSpec JSON
      → Server validates spec with Zod schema
        → Browser engine (Babylon.js) renders and runs the game
          → User publishes → shareable /play/[slug] URL

Games are defined by a constrained schema (GameSpec), not arbitrary code. The AI fills the schema; the engine interprets it. See PRODUCT_SPEC.md for the full schema definition and DECISIONS.md for why this matters.

---

Tech Stack

Layer	Technology
Monorepo	pnpm workspaces + Turborepo 2
Backend API	NestJS 10, TypeScript, Node 22
Database	PostgreSQL 16 + Prisma 5
Cache / Rate Limiting	Redis 7 (ioredis 5)
Storage	AWS S3 / Cloudflare R2 (dev: MinIO)
Email	Resend API
AI	OpenAI GPT-4o (streaming SSE)
Game Engine	Babylon.js 7 (packages/game-engine)
Frontend	Next.js 15 App Router, React 19, Tailwind CSS
UI Components	shadcn/ui
State	TanStack Query v5 + Zustand v5
Validation	Zod (packages/shared), class-validator (NestJS DTOs)

---

Monorepo Structure

.
├── apps/
│   ├── api/          # NestJS REST API (port 4000)
│   └── web/          # Next.js 15 frontend (port 3000)
├── packages/
│   ├── db/           # Prisma schema + generated client
│   ├── shared/       # Zod schemas + shared TypeScript types
│   └── game-engine/  # Babylon.js game runtime (browser-only)
├── scripts/
│   ├── start-dev.sh  # Start all infra + dev servers
│   └── smoke.sh      # HTTP smoke tests
├── docker-compose.yml
├── turbo.json
└── pnpm-workspace.yaml

---

Prerequisites

Tool	Version
Node.js	>= 22
pnpm	>= 9
Docker + Compose	>= 24

---

Quick Start

# 1. Clone
git clone https://github.com/your-org/promptplay.git
cd promptplay

# 2. Install dependencies
pnpm install

# 3. Start infrastructure (Postgres + Redis + MinIO)
docker compose up -d postgres redis minio minio-setup

# 4. Copy env and fill in secrets
cp .env.example .env
# Edit .env — required: DATABASE_URL, REDIS_URL, OPENAI_API_KEY, JWT_SECRET, JWT_REFRESH_SECRET

# 5. Run database migrations + generate Prisma client
pnpm db:migrate

# 6. Start all apps in dev mode
pnpm dev

Open:

• Web app: http://localhost:3000
• API: http://localhost:4000
• Swagger docs: http://localhost:4000/docs
• MinIO console: http://localhost:9001 (user: minioadmin, pass: minioadmin)

---

Environment Variables

Copy .env.example to .env. The API refuses to start if any required variable is missing.

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
REDIS_URL	Yes	Redis connection string
JWT_SECRET	Yes	>= 32 char random string (access token signing)
JWT_REFRESH_SECRET	Yes	>= 32 char random string (refresh token signing)
OPENAI_API_KEY	Yes	GPT-4o API key
RESEND_API_KEY	Yes	Transactional email (verification, password reset)
AWS_S3_BUCKET	Yes	S3 / MinIO bucket name
AWS_ACCESS_KEY_ID	Yes	S3 / MinIO access key
AWS_SECRET_ACCESS_KEY	Yes	S3 / MinIO secret key
AWS_S3_ENDPOINT	Optional	Custom endpoint for MinIO in dev (http://localhost:9000)
GOOGLE_CLIENT_ID	Optional	Google OAuth (disables Google login if absent)
GOOGLE_CLIENT_SECRET	Optional	Google OAuth
STRIPE_SECRET_KEY	Optional	Stripe (disables payment routes if absent; not needed for v1)
STRIPE_WEBHOOK_SECRET	Optional	Stripe webhook signing secret
ANTHROPIC_API_KEY	Optional	Claude fallback (not used in v1)

---

Scripts Reference

pnpm dev          # Start all apps in watch mode (Turborepo)
pnpm build        # Production build of all packages
pnpm lint         # ESLint across all packages
pnpm typecheck    # tsc --noEmit across all packages
pnpm test         # Jest unit tests (API) + Vitest (web)
pnpm db:migrate   # prisma migrate deploy
pnpm db:studio    # Prisma Studio (localhost:5555)
pnpm db:seed      # Seed development data

# Single-package operations
pnpm --filter @promptplay/api dev
pnpm --filter @promptplay/web dev

# Smoke tests (requires running stack)
./scripts/smoke.sh http://localhost:4000

---

Documentation

Document	Description
PRODUCT_SPEC.md	v1 scope, GameSpec schema, entities, user flows
ARCHITECTURE.md	System diagram, module map, deployment targets
ROADMAP.md	Milestones and delivery plan
DECISIONS.md	Technical decisions with rationale
RUNBOOK.md	Production deployment and incident response
SECURITY.md	Responsible disclosure policy
CREDITS.md	Open-source acknowledgements

---

Contributing

1. Fork and create a feature branch (git checkout -b feat/my-feature).
2. Make changes; ensure pnpm lint && pnpm typecheck && pnpm test all pass.
3. Commit with Conventional Commits.
4. Open a Pull Request against main.

All PRs require the CI pipeline to pass before merge.

---

License

MIT (c) 2026 PromptPlay contributors. See CREDITS.md for open-source acknowledgements.

Gamify