# Makko AI — Full Technical Reference

> For a concise product overview, see: https://www.makko.ai/llms.txt
> For engine API docs, see: https://www.makko.ai/lib/MakkoEngine.llm.txt

This document provides detailed technical information about Makko AI's features and capabilities for AI systems and developers.

---

## Code Studio — AI Game Development Environment

### AI Chat System

The AI assistant operates through an agentic chat interface with access to specialized tools:

**File Operations:**
- `read_file` — Read game file contents
- `write_file` — Create or modify game files (one file per tool call)
- `update_file` — Search-and-replace within files
- `apply_diff` — Apply structured SEARCH/REPLACE blocks
- `search_file` — Find code patterns across project files
- `inject_template` — Insert game templates and boilerplate code

**Game Development:**
- `build` — Compile project, return syntax and runtime errors with line-by-line diagnostics
- `lookup_reference` — Query MakkoEngine documentation for integration patterns

**Planning (Plan Mode only):**
- `init_plan` — Create structured multi-step workflow
- `add_task` / `delete_task` — Manage workflow tasks
- `finalize_plan` — Complete workflow setup
- `submit_plan` — Execute plan with automatic checkpoints
- `mark_task_complete` — Track implementation progress

### Operating Modes

- **Chat Mode**: Fast, iterative code suggestions and fixes. Best for quick edits, single-file changes, and conversational development
- **Think Mode**: Standard reasoning for moderate complexity tasks
- **Ultrathink Mode**: Extended reasoning and planning for multi-step complex tasks (higher credit cost)
- **Plan Mode**: Structured workflow that breaks complex projects into approval-based implementation plans. Creates automatic checkpoints before execution for safe rollback

### AI Models Available

| Model | Tier Required | Credits/Message | Capabilities |
|-------|---------------|-----------------|--------------|
| MiniMax M2.7 | Free | 1-2 | Fast default. Unlimited on all paid tiers (Starter+) once the weekly LLM credit budget is exhausted, at zero cost. |
| Kimi K2.5 | Free | 2 | Native image understanding |
| Kimi K2.6 | Free | 2 | Latest Kimi (April 2026 rollout) |
| GLM-5.1 | Hobbyist+ | 2-4 | Advanced reasoning |
| Claude Sonnet 4.6 | Pro only | 2-4 | Extended thinking, prompt caching |

Users can switch models per-message using an inline dropdown selector.

### Game Architecture

Games are built with vanilla JavaScript on HTML5 Canvas. The recommended project structure:

```
/src/
  /core/       — Game loop, input handling, time management
  /engine/     — Collision, physics, particles, UI, audio systems
  /game/       — Game entities (player, enemies, items)
  /scenes/     — Scene controllers (title, gameplay, gameover)
  /util/       — Helper functions
  /data/       — Level data, character manifests
  /services/   — Storage, analytics
/assets/       — Images, audio files
index.html     — Entry point with script loading order
style.css      — Game styling
README.md      — Documentation
```

**Architecture constraints:**
- Vanilla JS only — no external libraries or frameworks
- Module pattern using `window.Game` namespace
- No bundler required — files load in explicit order via script tags
- Target file size: ~80-100 lines per file for maintainability
- ES6 module support with esbuild compilation

### Supported Game Mechanics

- Grid-based movement and tile collision
- Physics: acceleration, velocity, gravity, friction
- AABB collision detection
- Pathfinding (BFS/greedy algorithms for AI enemies)
- Particle systems (lightweight particle pools)
- Audio playback and management
- HUD and score systems
- Frame-by-frame sprite animation
- Scene management with transitions
- Keyboard and touch input handling
- Save/load game state

### 50+ Game Templates

Pre-built scaffolding with automatic dependency resolution:
- Platformers (side-scrolling, precision)
- Puzzle games (match-3, sliding, logic)
- Board games (card games, strategy)
- Visual novels (branching narrative, dialogue systems)
- Deck-builders
- Arcade games (shooters, endless runners)
- RPG-style games
- Top-down exploration
- And many more added regularly

### Quick Actions Library

One-click AI prompt templates for common development tasks:
- Add Character (with animation manifest integration)
- Add Background (static or seamless tiling)
- Add Prop (with collision type selection: solid, platform, hazard, collectible, decoration)
- Assign Controls
- Debug Errors
- Refactor Code
- Generate Game Assets

---

## Art Studio — Visual Asset Generation

### Character Generation Pipeline

1. **Concept Art**: Generate character designs from text prompts (5 credits). Produces 1024x1024 images with choice of 12 art styles
2. **Reference Sheets**: Generate front/side/back views for animation consistency (5 credits)
3. **Animation**: Convert reference images to animated sprite sheets via video-first pipeline
4. **Frame Extraction**: Extract individual frames with ML background removal (10 credits)
5. **Sprite Sheet Baking**: Assemble frames into game-ready sprite sheets with metadata JSON
6. **Character Manifest**: Bundle all animations for a character into a single importable package

### 12 Art Styles

1. 16-Bit Pixel Art
2. HD Pixel Art
3. Isometric Pixel
4. Retro 8-Bit
5. Anime Character
6. Comic Book Art
7. Chibi/Cute
8. Painterly Art
9. Flat Vector Design
10. Stylized 3D
11. Cinematic Realism
12. Hyperreal

### Animation Generation

- **Video-first architecture**: Generates animation video first, then extracts sprite frames
- **ML background removal**: Automatic isolation of character from background
- **Two quality tiers**:
  - Flash (VEO-3 Flash): 45 credits — good quality, faster generation
  - Standard (VEO-3 Standard): 90 credits — premium quality
- **4-second animations** by default
- **Animation types**: walk, run, attack, jump, idle, cast, die, and custom
- **Background color options**: auto-detect, black, white, gray, transparent
- **Output**: PNG or WebP sprite sheets with metadata JSON containing frame dimensions, positioning, and timing
- **Frame editing**: Reorder frames (drag-and-drop), adjust frame duration (0.25x-10.0x multiplier)
- **Non-blocking**: Continue working while animations generate in the background

### Background Generation

- 7 perspective options: side-scroller, top-down, fixed-screen, vertical-scrolling, three-quarter, isometric, and rear-view
- Aspect ratios: 16:9, 4:3, 1:1, 9:16, and custom
- Seamless tiling preview (shows 3 copies side-by-side to verify edge continuity)
- Multiple generations per prompt (up to 3 variations)
- 5 credits per generation

### Prop Generation

- AI-generated game objects: platforms, obstacles, coins, power-ups, decorations
- Automatic background removal
- Same art style options as characters
- Collision type assignment: solid, platform, hazard, collectible, decoration
- 5 credits per generation

### Collections System

Collections are hierarchical visual reference libraries for maintaining style consistency:

- **Structure**: Up to 3 levels of nesting (e.g., Game > Chapter > Scene)
- **Concept Art Section**: Reference images that define the visual style for all generation within the collection
- **Game Assets Section**: Characters, backgrounds, and props generated or uploaded within the collection
- **Style Guidance**: When generating new assets in a collection, the AI uses existing concept art as style reference
- **Generation Preferences**: Each collection saves its preferred art style, perspective, and other settings
- **Collection types**: Concept Collections (any asset type) and Character Collections (character-focused)
- **Concept art generation within collections**: 5 credits per image
- **Collection reference art**: 12 credits per 4-view set

---

## Publishing & Distribution

### Publishing Workflow
1. Fill out multi-tab form: Basic Info (title, description, instructions, cover image), Game Details (type, difficulty, playtime, category, multiplayer toggle), Discovery (tags, social links)
2. Test-compile to verify game works
3. Publish — generates unique share URL

### Distribution Options
- **Share Link**: Public URL at `makko.ai/play/{shareToken}` with social metadata for embeds
- **Game Export**: Download as standalone HTML file — runs anywhere without dependencies. All JS/CSS/assets bundled and minified
- **Portfolio**: View all published games with play count analytics at `/studio/published/games`

### Game Metadata
- Game type/genre classification
- Difficulty levels: Easy, Medium, Hard, Expert
- Estimated play time
- Multiplayer flag
- Custom tags for discoverability
- Social links (Twitter, GitHub, website, Discord)

---

## GitHub Integration

### Capabilities
- **Link Repository**: Connect any Makko project to a GitHub repo
- **Branch Management**: Browse all branches, switch active branch, create branches
- **Commit Composer**: Stage files and create commits with custom messages from within the editor
- **Pull Request Browsing**: View and interact with open PRs
- **Two-Way Sync**: Push local changes to GitHub, pull remote changes into Makko
- **ZIP Download**: Download full repository snapshot
- **File Upload**: Upload files directly to the repository
- **History**: View commit history and restore from any point

### Authentication
- GitHub OAuth integration for secure repository access
- Per-project repository linking (one repo per project)

---

## Version Control & Safety

### Checkpoint System
- **Automatic Checkpoints**: Created before Plan Mode execution and major AI operations
- **Manual Checkpoints**: Create named savepoints at any time
- **Restore**: Revert to any checkpoint instantly
- **GitHub Restore**: Pull from any GitHub commit as a restore point

---

## Credit System Details

### Wallet Structure
- **Monthly Pool** (free_balance): Replenishing credits from subscription tier, resets every 30 days
- **Purchased Credits** (paid_balance): One-time purchased credits, never expire
- **Total Available**: Sum of monthly pool + purchased credits

### Credit Consumption Priority
Monthly pool credits are consumed first. Purchased credits are used only when the monthly pool is exhausted.

### AI Request Limits
- Free tier: 70 LLM credits/week. Beyond the cap, requests are debited from purchased credits at 1 credit per request, or hard-stop if no purchased balance.
- Paid tiers (Starter+): weekly LLM credit budget — Starter 500, Creator 1,500, Hobbyist 3,000, Pro 6,000. When the weekly budget exhausts, MiniMax M2.7 stays available at zero cost; premium models (GLM-5.1, Claude Sonnet 4.6) fall back to purchased credits overflow at 1 credit per request.
- Pro tier: 6,000 LLM credits/week on premium models, then unlimited MiniMax M2.7 at zero cost. (The MiniMax M2.7 fallback applies to all paid tiers — Starter through Pro.)

### Credit Top-Up Packages

| Package | Price | Credits | Bonus |
|---------|-------|---------|-------|
| Starter | $5 | 200 | — |
| Small | $10 | 420 | +5% |
| Medium | $25 | 1,100 | +10% |
| Large | $50 | 2,350 | +18% |
| XL | $100 | 4,800 | +20% |
| Mega | $250 | 12,500 | +25% |

### Free Features (No Credits Required)
- Manual code editing
- Game preview and testing
- Project and file management
- Asset library browsing
- Game publishing and sharing
- Portfolio management
- GitHub integration
- Checkpoint creation and restore

---

## Subscription Tier Features

### Image Uploads
- Free: Not available
- Starter+: Upload reference images and attach to AI chat (up to 4 images per message)

### Animation Quality
- Free/Starter/Creator: Flash quality only (VEO-3 Flash, 45 credits)
- Hobbyist/Pro: Flash + Standard quality (VEO-3 Standard, 90 credits)

---

## Platform Technical Details

- **Frontend**: React 19 with React Router v7, Tailwind CSS, Radix UI
- **Editor**: Monaco Editor (VS Code engine)
- **Backend**: Supabase (PostgreSQL, Auth, Storage, Realtime)
- **Build**: esbuild for game compilation, Vite for platform
- **Hosting**: Static pre-rendered marketing pages, SPA for authenticated studio
- **Game Engine**: Custom MakkoEngine — vanilla JavaScript on HTML5 Canvas 2D
- **AI Providers**: Multiple LLM providers via tiered access
- **Animation Pipeline**: Video generation (VEO-3) → ML frame extraction → sprite sheet assembly

---

## Help & Support

- Help Center: https://www.makko.ai/help (11+ articles covering all features)
- Email: support@makko.ai
- Discord: https://discord.gg/makko (community support, weekly themed prompts, Build Crew program)
- YouTube: https://www.youtube.com/@makkoai (tutorial series including visual novel development)
- Blog: https://www.makko.ai/blog