GameByte Agent Guidelines

Read First: docs/PHILOSOPHY.md - Framework philosophy and principles

Framework Mission

GameByte Framework = Lego Blocks for AI-Driven Mobile Game Development

This framework is a modular system designed to accelerate mobile game production by AI agents. Every agent using this system follows the principles below.

Agent Types & Responsibilities

Core Architecture Agents

Game Systems Agents

UI/UX Agents

Quality & Documentation Agents

Platform & Optimization Agents

The Lego Block Principle

When Adding Code

Every new piece of code should be a "lego block":

// GOOD: Self-contained, reusable, composable
export class MatchThreeGrid {
  constructor(options: MatchThreeGridOptions) { }
  // Clear API, sensible defaults, documented
}

// BAD: Tightly coupled, game-specific assumptions
function handleMatch() {
  // Hard-coded values, no reusability
}

Contribution Checklist

Before every commit:

• Is it a reusable block? - Can it be used in other games?
• Does it have sensible defaults? - Can agent use with minimal config?
• Is it mobile-first? - Touch-friendly, performant?
• Is it documented? - JSDoc + guide + example?
• Does it follow existing patterns? - Consistent with existing API style?
• Is it 100% working? - No partial implementations

Code Standards

TypeScript Requirements

/**
 * [Component Name] - [One-line description]
 *
 * @example Basic usage
 * ```typescript
 * const component = new Component({
 *   required: 'value',
 *   // optional params shown with defaults
 * });
 * ```
 *
 * @example With customization
 * ```typescript
 * const component = new Component({
 *   required: 'value',
 *   optional: 'custom'
 * });
 * ```
 */
export class Component {
  constructor(options: ComponentOptions) {
    // Apply defaults
    const config = {
      ...DEFAULT_OPTIONS,
      ...options
    };
  }
}

export interface ComponentOptions {
  /** Required parameter description */
  required: string;

  /** Optional parameter description @default 'default' */
  optional?: string;
}

Export Requirements

Every public component must:

1. Be exported from src/index.ts
2. Be exported with its types
3. Be accessible in UMD build

Mobile-First Requirements

// Touch target sizing
const MIN_TOUCH_SIZE = 44; // px (Apple HIG)

// Button example
new UIButton({
  width: Math.max(width, MIN_TOUCH_SIZE),
  height: Math.max(height, MIN_TOUCH_SIZE)
});

Documentation Requirements

Tier 1: Core API (Required for all public APIs)

Location: docs/agent-guide/CORE_API.md

### Component Name

```typescript
// 5-line minimal example
const component = new Component({ required: 'value' });
stage.addChild(component.getContainer());

What it does: One sentence When to use: One sentence

### Tier 2: Guide (Required for complex features)

Location: `docs/guides/[feature-name].md`

```markdown
# Feature Name

One paragraph description.

<!-- keywords: relevant, search, terms, for, agents -->

## Basic Usage
[Code example]

## Advanced Configuration
[Options table + examples]

## Common Patterns
[Real-world usage patterns]

## Related Guides
[Links to related docs]

Tier 3: Example (Required for game mechanics)

Location: examples/[genre]/

examples/
  [genre]/
    index.html      # Runnable demo
    README.md       # What it demonstrates

Quality Gates

Before Merge

1. Build passes: npm run build
2. Tests pass: npm test
3. Lint clean: npm run lint
4. Docs complete: All tiers documented
5. Example works: Runnable in browser

Performance Targets

Agent Communication

When to Spawn Sub-Agents

Complex task decomposition:
- Physics system -> physics-integration-architect
- UI components -> ui-ux-components-architect
- Performance issues -> game-loop-performance-optimizer
- Asset optimization -> technical-art-optimizer

Information to Pass

// When spawning sub-agent, provide:
{
  context: "Current game genre/type",
  constraints: "Mobile-first, 60 FPS target",
  existing_code: "Relevant file paths",
  expected_output: "Working component with docs"
}

Common Patterns

Creating a New Game Mechanic

1. Research: Analyze successful mobile games
2. Design: Define minimal API
3. Implement: Build core logic
4. Polish: Add effects, sounds, haptics
5. Document: Tier 1, 2, 3 docs
6. Example: Create runnable demo
7. Test: Write unit/integration tests

Extending Existing Features

1. Read: Understand current implementation
2. Plan: Identify extension points
3. Extend: Use composition over modification
4. Verify: Ensure backward compatibility
5. Document: Update affected docs

Fixing Bugs

1. Reproduce: Create minimal test case
2. Root cause: Identify actual issue
3. Fix: Minimal change, no over-engineering
4. Test: Add regression test
5. Document: Update if behavior changed

Genre-Specific Guidelines

Hyper-Casual

• One-tap/one-swipe core mechanic
• < 3 second learn time
• Satisfying feedback loops
• Clean, minimal UI

Puzzle (Match-3, Merge)

• Grid-based systems
• Clear visual feedback
• Combo/chain mechanics
• Progress tracking

Idle/Clicker

• Incremental progression
• Offline calculations
• Multiple currencies
• Prestige systems

Platformer

• Physics-based movement
• Responsive controls
• Coyote time, variable jump
• Clear collision feedback

File Organization

src/
  core/           # Framework foundation
  rendering/      # Pixi.js, Three.js integration
  ui/             # UI components
  scenes/         # Scene management
  physics/        # Physics engines
  audio/          # Audio systems
  input/          # Input handling
  assets/         # Asset management
  mechanics/      # Game mechanics (NEW)
    match-three/
    merge/
    idle/
    platformer/
  templates/      # Game templates (NEW)
    hyper-casual/
    puzzle/
    idle/

Remember

"Every line of code should help an AI agent produce its next hit game."

The purpose of this framework:

1. Enable AI agents to rapidly produce games
2. Deliver studio-quality polish
3. Create trend-aligned output
4. Work with minimal context

This document is the foundational reference for all GameByte agents. Every agent follows these principles.