An AI-powered troop creation pipeline for a Clash of Clans-style strategy game. Players design troops through a guided builder, a multi-agent AI pipeline generates balanced stats and artwork, and a human director approves each troop before it joins the live roster.
Built for the Agentic Frontier Hackathon — Supercell track + Best Trust Implementation.
Player fills Troop Builder → 4 AI Agents run in sequence → Director approves → Troop joins roster + gets 3D model
| Agent | What it does |
|---|---|
| Portrait Agent | Generates a full-body troop portrait via DALL-E 3 |
| Character Agent | Designs stats and lore — constrained by archetype rules, hidden normalization prevents broken troops |
| Balance Agent | Validates stat totals, type alignment, and fit against the live roster |
| Safety Agent | Screens for harmful content, IP violations, age-appropriateness across 5 checks |
All agent reasoning is stored as transcripts — full auditability for every troop.
Players don't input raw stats. Instead they choose:
- Base archetype — Barbarian / Giant / Archer / Wizard / Balloon (sets hidden stat ranges)
- Target preference — Ground / Air / Both
- Special ability — Splash / Rage / Freeze / Chain / Heal
- Weakness trade-off — forced downside that keeps the troop balanced
- Creative vision — optional prompt for appearance and lore only
The AI generates stats within locked ranges for each archetype. Players can never create infinite-damage or unkillable troops.
- Every troop gets an AI trust score (0–100) with 5 named checks
- Human director must approve before anything goes live
- Full agent transcripts stored and visible in the admin panel
- Rejection notes feed back into the next generation (the AI learns from director decisions)
Approved troops go to the public roster where players vote them up or down. The most-voted troop gets selected for the main Builder Studio game.
| Layer | Technology |
|---|---|
| Backend | FastAPI, SQLAlchemy, PostgreSQL, Uvicorn |
| AI | OpenAI GPT-4o-mini + DALL-E 3 |
| 3D Generation | Meshy API (image-to-3D) |
| Database & Storage | Supabase (Postgres + S3 Buckets) |
| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS 4 |
| Streaming | Server-Sent Events (SSE) |
| 3D Viewer | @google/model-viewer |
- Python 3.11+
- Node.js 18+
- API keys for OpenAI, Meshy, and Supabase
git clone https://github.com/your-username/studio-wars.git
cd studio-warscd backend
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Set up environment variables
cp .env.example .env
# Edit .env and add your API keys.env file:
OPENAI_API_KEY=your_openai_api_key
MESHY_API_KEY=your_meshy_api_key
DATABASE_URL=your_supabase_postgres_url
SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_anon_key
# Start the backend
uvicorn main:app --reload --port 8000The API will be available at http://localhost:8000.
cd frontend
# Install dependencies
npm install
# Set up environment (optional — defaults to localhost:8000)
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local
# Start the dev server
npm run devThe app will be available at http://localhost:3000.
| Key | Where to get it |
|---|---|
OPENAI_API_KEY |
platform.openai.com |
MESHY_API_KEY |
meshy.ai |
SUPABASE_URL |
supabase.com -> Project Settings -> API |
SUPABASE_KEY |
supabase.com -> Project Settings -> API |
DATABASE_URL |
supabase.com -> Project Settings -> Database -> URI |
studio-wars/
├── backend/
│ ├── agents/
│ │ ├── portrait_agent.py # DALL-E 3 portrait generation
│ │ ├── character_agent.py # Stat design with archetype constraints
│ │ ├── balance_agent.py # Stat validation + roster-aware balancing
│ │ ├── safety_agent.py # Content moderation (5-check system)
│ │ └── mesh_agent.py # Meshy API 3D model generation
│ ├── routes/
│ │ ├── characters.py # Generation pipeline + voting endpoint
│ │ └── admin.py # Approval queue + mesh retry
│ ├── models.py # SQLAlchemy Character model
│ ├── schemas.py # Pydantic request/response schemas
│ ├── database.py # Database setup (PostgreSQL/SQLite)
│ ├── storage.py # Supabase Storage upload helpers
│ ├── streaming.py # SSE event helpers
│ ├── main.py # FastAPI app entry point
│ ├── migrate_votes.py # One-time DB migration for vote columns
│ ├── requirements.txt
│ └── .env.example
└── frontend/
├── app/
│ ├── page.tsx # Home / pipeline overview
│ ├── create/page.tsx # Guided Troop Builder
│ ├── roster/page.tsx # Public roster + voting + 3D viewer
│ └── admin/page.tsx # Director approval queue
├── components/
│ ├── character-card.tsx # Troop card with vote buttons + trust badge
│ ├── model-viewer.tsx # @google/model-viewer wrapper with polling
│ ├── trust-dashboard.tsx # AI safety score display
│ └── agent-pipeline.tsx # Real-time agent step display
├── hooks/
│ ├── use-character-stream.ts # SSE stream consumer
│ └── use-vote.ts # Vote state + localStorage dedup
└── lib/
├── api.ts # Typed API client
└── types.ts # TypeScript interfaces
| Page | URL | Description |
|---|---|---|
| Home | / |
Project overview and pipeline explanation |
| Create | /create |
Guided Troop Builder with real-time agent pipeline |
| Roster | /roster |
Approved troops with voting and 3D viewer |
| Admin | /admin |
Director approval queue with trust dashboard |
- Real-time streaming — SSE stream shows each agent step as it runs
- Hidden stat normalization — archetype + ability + weakness choices lock stat ranges; players can't create broken troops
- Roster-aware balancing — balance agent compares new troops against existing roster
- Rejection feedback loop — director rejection notes are injected into the next generation prompt
- Community voting — upvote/downvote per session (localStorage dedup), top pick joins Builder Studio
- 3D model generation — approved troops automatically get a GLB model via Meshy, viewable in-browser
- Full audit trail — every agent's reasoning transcript stored per troop