GameStory Lab：面向游戏编剧的 AI 叙事与故事设计工具

GameStory Lab is a game narrative and story lab tooling that helps game writers and narrative designers prototype and structure game stories.

TL;DR: GameStory Lab — game narrative and story lab tooling. Best for game writers and narrative designers.

AI-Powered Game Concept Generator for Indie Developers

GameStory Lab helps indie game developers create cohesive, professional game concepts before development starts. Using AI orchestration and consistency validation, it ensures your mechanics and lore work together seamlessly.

✨ Features

✅ Implemented & Working:

🎮 Flexible Workflow: Start with mechanics OR lore - AI adapts to your creative process
🖥️ Full Web Interface: Complete React UI with project management, concept editing, validation, and export
🤖 AI Model Orchestration: Automatically selects optimal AI models (MiniMax, GLM, DeepSeek, Qwen 3, Phi-4, Gemini, Ollama)
✅ Comprehensive Validation: 27 validation rules across 6 categories with real-time feedback
🎯 Genre Templates: 15 professionally crafted templates covering all major genres (Nov 2025)
🎨 Genre Blending: Mix and match genres with weighted blending to create hybrid templates (Metroidvania, Action RPG, etc.)
✨ Blended Project Creation: Create projects directly from genre hybrids with full mechanics/lore integration
🔄 Iterative Refinement: Full version tracking and change comparison with 4 refinement focuses
📝 Professional Export: Generate GDD, pitch decks, or technical specs in markdown
🏷️ Title Generation: Advanced title suggestions with SEO analysis and market fit scoring
💰 Cost Optimization: Intelligent fallback to local Ollama models to minimize API costs
🔧 Full REST API: Complete backend with 9 endpoint groups
📊 Health Monitoring: Real-time system status with AI provider tracking and cost monitoring
🏗️ AI Project Architect: Complete documentation workflow with structured interviews and 4-6 generated documents
💬 AI Assistant Panel: Project-level chat assistant with proposal system for concept updates and architect document generation
📦 Architect ZIP Export: Download complete documentation packages as ZIP archives

🚀 Quick Start

Prerequisites

Node.js ≥ 22.0.0
Docker and Docker Compose (for PostgreSQL)
Ollama (optional, for local AI models)
MiniMax API Key (primary cloud provider)
GLM API Key (secondary cloud provider)
OpenRouter API Key (optional, for other cloud AI models)
Google API Key (optional, for Gemini models)

Installation

Clone the repository

git clone https://github.com/simongonzalezdc/GameStory-Lab.git
cd GameStory-Lab

Install dependencies
```
npm install
```

Set up environment variables

cp .env.example .env
# Edit .env and add your API keys

Start infrastructure (PostgreSQL)
```
docker-compose up -d
```

Initialize database

cd packages/backend
npx prisma migrate dev
npx prisma generate
cd ../..

Install and configure Ollama (optional but recommended)

# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh

# Pull recommended models (November 2025 - optimized for Mac M4 16GB)
ollama pull qwen3:30b-a3b     # MoE: 30B quality, 3B memory! (BEST)
ollama pull phi4:14b          # High quality reasoning
ollama pull qwen3-coder:7b    # Creative writing
ollama pull qwen3:7b          # Structured output

Start development servers

# Terminal 1: Backend
cd packages/backend
npm run dev

# Terminal 2: Frontend
cd packages/frontend
npm run dev

Access the application
- Frontend UI: http://localhost:5173
- Backend API: http://localhost:3001
- API Health Check: http://localhost:3001/health

🏗️ Architecture

GameStory Lab uses a monorepo structure with npm workspaces:

gamestory-lab/
├── packages/
│   ├── frontend/          # React + TypeScript UI ✅
│   ├── backend/           # Node.js + Express API ✅
│   └── shared/            # Shared types and validation ✅
├── modules/               # Standalone experiments (own deps, own CI — see below)
├── docker-compose.yml     # PostgreSQL ✅
├── .env.example          # Environment template ✅
└── README.md             # This file

Modules (standalone, not in root workspaces)

modules/ holds three independent experiments, each with its own package.json/requirements.txt, lockfile, and CI coverage. They are not part of the root npm workspaces — cd into each to install and test:

Module	Stack	Test
`generative-assets-lab/backend`	FastAPI + LangChain	`pytest`
`generative-assets-lab/frontend`	Vite + React	`vitest run`
`generative-score-lab`	Vite + React 18	`vitest run`
`shiplab`	Next.js + Drizzle	`vitest run`

Tech Stack

Component	Technology	Purpose
Frontend	React 19 + TypeScript	User interface
Backend	Node.js + Express	API server
Database	PostgreSQL 17	Structured data + JSONB
ORM	Prisma 6	Type-safe database access
AI Gateway	MiniMax + GLM + OpenRouter + Google + Ollama	Multi-model AI orchestration

🔑 AI Provider Configuration

MiniMax (Primary Cloud Provider)

Get API key from MiniMax Platform

Add to .env:

MINIMAX_API_KEY=your-minimax-key-here
MINIMAX_API_BASE_URL=https://api.minimax.io/anthropic

Anthropic-compatible API; used as the primary provider when configured

GLM / Zhipu AI (Secondary Cloud Provider)

Get API key from Zhipu AI

Add to .env:

GLM_API_KEY=your-glm-key-here
GLM_API_BASE_URL=https://open.bigmodel.cn/api/paas/v4

OpenAI-compatible API; also serves as the cost-limit fallback

OpenRouter (Recommended for Cloud AI)

Get API key from OpenRouter

Add to .env:

OPENROUTER_API_KEY=sk-or-v1-your-key-here

Provides access to DeepSeek, Qwen, GPT, Claude, and more

Google Gemini (For Consistency Validation)

Get API key from Google AI Studio
Add to .env:
```
GOOGLE_API_KEY=AIzaSy-your-key-here
```
Used for fast consistency checking with 1M context

Ollama (Free Local Models - November 2025 Updates)

Install Ollama: https://ollama.com/download

Pull models (optimized for Mac M4 16GB):

# PRIMARY (MoE - Best quality/memory ratio!)
ollama pull qwen3:30b-a3b     # 30B quality, 3B memory (8-12GB RAM)

# HIGH QUALITY
ollama pull phi4:14b          # Best reasoning (11-13GB RAM)

# SPECIALIZED
ollama pull qwen3-coder:7b    # Best creative/narrative (6-8GB RAM)
ollama pull qwen3:7b          # Best JSON/mechanics (6-8GB RAM)
ollama pull deepseek-r1:8b    # Advanced reasoning (7-9GB RAM)
ollama pull llama4:8b         # Lightweight, versatile (<8GB RAM)

Models Released: Qwen 3 (April 2025), Phi-4 (Nov 2025), DeepSeek R1, Llama 4
MoE Breakthrough: Qwen3-30B-A3B uses Mixture-of-Experts - 30B params, only 3B active!
Ollama runs on http://localhost:11434 by default
No API key required - completely free and unlimited

📊 Database Schema

The database uses PostgreSQL with JSONB for flexible concept storage:

users: User accounts (future multi-user support)
projects: Top-level game projects
concepts: Versioned game concepts (mechanics + lore as JSONB)
ai_generations: Log of all AI API calls for cost tracking
validation_results: Consistency check results

Key Features

JSONB fields for flexible mechanics/lore structure
GIN indexes on JSONB for fast queries
Versioning for iterative refinement
Automatic timestamps for all records

🎨 Genre Blending System

Create unique hybrid game concepts by intelligently blending multiple genres:

Available Genres (15 Total)

Action-Adventure, Adventure, Battle Royale, Fighting, FPS
Horror, Platformer, Puzzle, Racing, Roguelike
RPG, Simulation, Sports, Strategy, Survival

How It Works

Select 2+ genres in Mix Mode
Adjust weight sliders (e.g., 70% RPG + 30% FPS)
Blend to preview hybrid mechanics and lore
Create project directly from blended template

Popular Blends

70% RPG + 30% FPS → Action RPG (Borderlands-style)
50% Platformer + 50% Adventure → Metroidvania (Hollow Knight-style)
60% Survival + 40% Horror → Survival Horror (The Last of Us-style)
40% Roguelike + 40% Action-Adventure + 20% RPG → Roguelite Action RPG (Hades-style)

Smart Merging

Combines mechanics, progression systems, and resource management
Blends lore elements (setting, protagonist, conflicts, themes)
Intelligently weights primary genre characteristics
Stores blend metadata for future refinement

🏗️ AI Project Architect (Final Stage)

Transform your completed game concept into comprehensive, AI-agent-ready project documentation.

What It Does

After completing your game concept, the Project Architect guides you through a structured interview (10-25 questions) and automatically generates professional documentation optimized for AI coding agents.

Documentation Generated

4 Core Documents (Always):

Executive Summary - Quick reference for humans (1-2 pages)
Technical Specification - Complete implementation guide for AI agents
Product Requirements - What to build (features & acceptance criteria)
Roadmap - Development timeline and phases

2 Optional Documents (For Open Source Projects): 5. Monetization Audit - Revenue strategy and feature tier recommendations 6. Launch Checklist - Go-to-market plan and community setup

How to Use

Complete your game concept in the editor
Click the 🏗️ Project Architect button
Answer 10-25 questions about your project
Generate and download all documentation

Interview Structure

Phase 1: Quick Discovery (5 questions) - Project basics, type, tech stack, key features
Phase 2: Deep Dive (10-20 questions) - Technical preferences, architecture, quality requirements
Phase 3: Open Source (optional) - License, monetization, community strategy

Key Benefits

Token-efficient: 4-6 comprehensive documents vs 10+ separate files (60% reduction)
AI-agent optimized: Technical specs include exact file paths, build order, and implementation guidance
Flexible: Adapts questions based on your answers and project type
Complete: Covers all aspects from architecture to deployment
ZIP Export: Download all documentation as a single ZIP archive via GET /api/architect/export/:projectId

💬 AI Assistant Panel

What It Does

The Assistant Panel provides project-level AI chat assistance with a proposal system. You can:

Chat with AI about your project concepts
Receive AI-generated proposals for concept improvements
Accept or reject proposals to update your concepts
Use the assistant in both concept editing and architect workflows

How to Use

Open a project in the editor
Click the Assistant Panel button (💬 icon)
Start chatting with the AI about your project
Review proposals when the AI suggests changes
Accept proposals to create new concept versions

Proposal Types

Concept Updates: AI suggests improvements to mechanics or lore
Architect Documents: AI generates documentation based on your project

Features

Session Persistence: Messages and proposals persist across page reloads
Context-Aware: Assistant has access to your project's current concept and metadata
Proposal System: Review changes before applying them
Version Tracking: Accepted proposals create new concept versions automatically

🛠️ API Endpoints

Projects

GET /api/projects - List all projects
POST /api/projects - Create new project
GET /api/projects/:id - Get project with concepts
PATCH /api/projects/:id - Update project
DELETE /api/projects/:id - Delete project

Templates

GET /api/templates - List all 15 genre templates
GET /api/templates/:genre - Get specific genre template
GET /api/templates/:genre/stats - Get template statistics
POST /api/templates/:genre/customize - Customize template with overrides
POST /api/templates/:genre/create-project - Create project from single genre
POST /api/templates/blend - Blend multiple genres (preview only)
POST /api/templates/blend-and-create - Blend genres and create project

Generation

POST /api/generate - Generate mechanics, lore, or titles
- Task types: mechanics, lore, title, refinement
- Model preference: auto, openrouter, ollama

Validation

POST /api/validate - Run consistency validation
GET /api/validate/rules - List all validation rules
PATCH /api/validate/:conceptId/dismiss/:ruleId - Dismiss validation issue

Export

POST /api/export - Export concept to markdown
- Templates: gdd, pitch, technical

Refinement

POST /api/refinement - Refine existing concept
GET /api/refinement/history/:projectId - Get version history
POST /api/refinement/compare - Compare two versions

Titles

POST /api/titles/generate - Generate title suggestions
POST /api/titles/analyze - Analyze title marketability

Project Architect

POST /api/architect/start - Start interview session for a project
POST /api/architect/answer - Submit answer and get next question
GET /api/architect/session/:sessionId - Get current session progress
GET /api/architect/questions - Get all available interview questions
POST /api/architect/generate - Generate complete documentation package
GET /api/architect/documentation/:projectId - Get generated documentation
GET /api/architect/document/:projectId/:documentName - Download specific document
GET /api/architect/templates - List all document templates
DELETE /api/architect/session/:sessionId - Delete interview session

System

GET /health - API health check
GET /api - API documentation

💡 Usage Examples

Creating a New Game Concept

# 1. Create a project
curl -X POST http://localhost:3001/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Sci-Fi RPG",
    "genre": "rpg"
  }'

# 2. Generate mechanics
curl -X POST http://localhost:3001/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "<project-id>",
    "taskType": "mechanics",
    "context": {
      "genre": "rpg",
      "userPrompt": "Create a space exploration RPG with ship customization"
    },
    "modelPreference": "auto"
  }'

# 3. Validate consistency
curl -X POST http://localhost:3001/api/validate \
  -H "Content-Type: application/json" \
  -d '{
    "conceptId": "<concept-id>",
    "mechanics": { ... },
    "lore": { ... }
  }'

# 4. Export to markdown
curl -X POST http://localhost:3001/api/export \
  -H "Content-Type: application/json" \
  -d '{
    "conceptId": "<concept-id>",
    "template": "gdd"
  }'

🧪 Development

Running Tests

# Backend tests
cd packages/backend
npm test

# Frontend tests
cd packages/frontend
npm test

Database Management

# Create a new migration
cd packages/backend
npx prisma migrate dev --name description_of_changes

# Open Prisma Studio (GUI)
npx prisma studio

# Reset database (WARNING: deletes all data)
npx prisma migrate reset

Linting and Formatting

# Lint all packages
npm run lint

# Format all files
npm run format

🐛 Troubleshooting

OpenRouter API returns 429 (rate limit)

Solution: The orchestrator automatically falls back to Ollama. Check logs for fallback confirmation.

Prisma migration fails

Solution: Ensure Docker containers are running (docker-compose ps). Check schema syntax. Rollback with npx prisma migrate resolve --rolled-back <migration>.

Ollama not responding

Solution:

# Check if Ollama is running
ollama list

# Start Ollama
ollama serve

# Install recommended models (November 2025)
ollama pull qwen3:30b-a3b  # MoE: Best for 16GB Mac
ollama pull phi4:14b       # High quality reasoning

Frontend can't connect to backend

Solution: Verify FRONTEND_URL in .env. Check CORS settings in packages/backend/src/server.ts. Ensure backend is running on port 3001.

📝 Environment Variables

See .env.example for all available configuration options.

Required

DATABASE_URL - PostgreSQL connection string

Optional (but recommended)

OPENROUTER_API_KEY - For cloud AI models
GOOGLE_API_KEY - For Gemini validation
OLLAMA_BASE_URL - Local Ollama instance (default: http://localhost:11434)

Application Settings

NODE_ENV - development | production | test
PORT - Backend port (default: 3001)
FRONTEND_URL - Frontend URL for CORS (default: http://localhost:5173)
AI_COST_LIMIT_PER_HOUR_USD - Spending cap (default: 5.00)

🗺️ Roadmap

✅ Phase 1: Backend Foundation (Completed - 100%)

Monorepo setup with TypeScript
Database schema with Prisma (5 tables)
AI client abstraction (OpenRouter, Google, Ollama)
AI Model Orchestrator with intelligent routing
Backend REST API (projects, generate, validate, export)
Consistency Validation Engine framework
Markdown export templates (GDD, Pitch, Technical)
Cost tracking and rate limiting

✅ Phase 2: Complete Validation System (Completed - 100%)

Validation engine architecture with parallel processing
All 27 validation rules implemented ✅
- Mechanics-Lore Alignment (10 rules)
- Genre Conventions (1 meta-rule)
- World Physics (5 rules)
- Progression Coherence (4 rules)
- Narrative Structure (3 rules)
- Technical Feasibility (3 rules)

✅ Phase 3: Genre Templates & Refinement (Completed - 100%)

Genre template system ✅
- 15 JSON template files covering all major genres (Nov 2025)
- Template loading service
- Template customization API
- Template browser UI with visual previews
Genre blending system ✅
- Weighted genre mixing algorithm
- Smart mechanics and lore merging
- Blend preview API endpoint
- Blend-and-create API for direct project creation
- Interactive Mix Mode UI with weight sliders
Dedicated refinement service with version tracking
Enhanced title generation service with SEO analysis

✅ Phase 4: Frontend UI (Completed - 100%)

React UI with Vite + TypeScript setup
Main layout with navigation
Project management dashboard with CRUD operations
Concept editor with mechanics and lore display
Real-time validation panel with live issue detection
Export dialog with multiple template options
Template browser with visual preview and project creation
System health monitoring page
Complete routing and state management

✅ Phase 5: AI Project Architect (Completed - 100%)

Interview workflow system ✅
- Structured interview questions (27 questions across 3 phases)
- Intelligent question branching based on answers
- Progress tracking and completion percentage
- Session state management
Document generation engine ✅
- 6 professional markdown templates
- Smart placeholder replacement
- Conditional content blocks
- Context-aware content generation
Backend API ✅
- 9 architect endpoints for interview and documentation
- Document download functionality
- Session management
Frontend UI ✅
- Interactive interview page
- Progress visualization
- Document preview and download
- Integration with concept editor

🔮 Phase 6: Advanced Features (Future)

Multi-user support with authentication
Cloud saves and sync
Visual concept art generation (Stable Diffusion)
Community template marketplace
Hosted SaaS offering
Custom model training

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

Built with insights from the game design research community
AI models powered by OpenRouter, Google Gemini, and Ollama
Inspired by the needs of indie game developers worldwide

📚 Documentation

TUTORIAL.md - Complete user tutorial (start here!)
SETUP.md - Detailed setup instructions (start here for local dev)
Dev Docs/ - Technical specifications and requirements

📧 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Generated with ❤️ for indie game developers

What is GameStory Lab?

GameStory Lab is a game narrative and story lab tooling that helps game writers and narrative designers prototype and structure game stories.


Product	GameStory Lab
Category	game narrative and story lab tooling
Best for	game writers and narrative designers
Not	a full game engine
Source	GitHub · Forgejo
Keywords	game story lab, narrative design tooling

Who it's for

Primary: game writers and narrative designers
Use when you need to prototype and structure game stories
Skip if you need a full game engine

FAQ

What is GameStory Lab?

GameStory Lab is a game narrative and story lab tooling. It helps game writers and narrative designers prototype and structure game stories.

Who should use GameStory Lab?

game writers and narrative designers.

How is GameStory Lab different?

Story lab, not Unity/Unreal replacement.

Is GameStory Lab production software?

Treat the README status and release tags as source of truth for maturity. Validate against your own requirements before production use.

Status

Maintained as of 2026 on the default branch
Prefer release tags when pinning dependencies
Report issues on the canonical remote listed above

Agent surface

Coding agents: read this README first, then repo docs/AGENTS.md if present
Prefer machine-readable briefs (llms.txt) when the repo ships one
MCP or skill entrypoints are documented in-repo when applicable

Contributing

Issues and PRs welcome on the canonical remote. Keep public docs free of secrets and machine-local paths.

License

See LICENSE in this repository (or package metadata if license is package-only).