# GameByte Framework Documentation
> Modern Mobile-First Game Development Framework
> Version: 1.3.0

## Overview
GameByte is a comprehensive JavaScript game framework that unifies 2D (Pixi.js v8) and 3D (Three.js) rendering with Laravel-inspired architecture. Mobile-optimized with 44px touch targets and performance features.

## Quick Start
- /overview - Framework introduction and features
- /getting-started/installation - npm install @gamebyte/framework
- /getting-started/quick-start - Build first game in 5 minutes
- /getting-started/first-game-tutorial - Complete platformer tutorial

## Core Concepts
- /core-concepts/architecture - Service container, providers, facades
- /core-concepts/game-loop - Update cycle, delta time
- /core-concepts/configuration - All config options

## Rendering
- /rendering/overview - 2D vs 3D vs Hybrid modes
- /rendering/2d-pixi - Pixi.js v8 sprites, textures, filters
- /rendering/3d-three - Three.js meshes, materials, lighting
- /rendering/hybrid-mode - Combine 2D UI with 3D world

## Scenes
- /scenes/scene-management - Lifecycle, switching, data passing
- /scenes/transitions - Fade, slide, zoom, custom

## UI Components
- /ui-components/overview - Mobile-first UI system
- /ui-components/button - GameStyleButton, UIButton
- /ui-components/panel - GameStylePanel, UIPanel
- /ui-components/tooltip - GameTooltip (speech bubble popover)
- /ui-components/text - UIText typography
- /ui-components/topbar - GameTopBar, TopBar (HUD resources)
- /ui-components/progress-bar - Health, loading bars
- /ui-components/navigation - GameBottomNav, ArcheroMenu
- /ui-components/level-selector - HexagonLevelButton, LevelPath
- /ui-components/responsive-layout - Adaptive layouts

## Boilerplate (Game Screens)
- /boilerplate/overview - Complete game boilerplate system
- /boilerplate/screen-manager - ScreenManager (push/pop navigation)
- /boilerplate/screens - HubScreen, GameHUDScreen, ResultScreen
- /boilerplate/panels - GameModalPanel, GameBottomSheet
- /boilerplate/simple-screen - SimpleScreen base class

## Physics
- /physics/overview - 2D and 3D physics
- /physics/2d-matter - Matter.js integration
- /physics/3d-cannon - Cannon.js integration

## Audio
- /audio/overview - Audio system
- /audio/music-sfx - Music and sound effects
- /audio/spatial-audio - 3D positional audio

## Input
- /input/overview - Unified input system
- /input/keyboard-mouse - Desktop controls
- /input/touch - Mobile gestures, virtual joystick
- /input/gamepad - Controller support

## Assets
- /assets/loading-caching - Asset management
- /assets/smart-pipeline - Priority loading, memory budgets, LRU eviction

## Tick System (Component-Level Render Loop)
- /tick/overview - Per-component render loop with priority ordering
- /tick/fixed-timestep - Deterministic physics at fixed intervals

## Resource Lifecycle
- /resources/overview - Auto-dispose, scoped resource tracking
- /resources/scopes - Hierarchical cleanup (scene-level, entity-level)

## 3D Pointer Events
- /three/events/overview - DOM-like click/hover/drag on 3D objects
- /three/events/raycasting - Layer-based filtering, BVH acceleration

## Adaptive Performance
- /performance/advisor - Auto quality tier adjustment with hysteresis
- /performance/thermal - Thermal throttling detection

## GPU Instancing
- /three/instancing/overview - Automatic instanced rendering at 3+ copies

## Post-Processing
- /postprocessing/overview - Effect merging via pmndrs/postprocessing
- /postprocessing/effects - Bloom, FXAA, Vignette, SSAO, DOF, ChromaticAberration

## Environment System
- /environment/overview - Skybox, fog, sun, ambient lighting
- /environment/presets - Day, sunset, night, overcast presets
- /environment/transitions - Smooth lerp between presets

## Prefab / Entity System
- /prefabs/overview - JSON-driven prefabs with template inheritance
- /prefabs/components - ECS-lite component lifecycle hooks
- /prefabs/serialization - Save/load entity state

## Procedural Audio
- /audio/procedural - 15 built-in game sounds (hit, explosion, coin, etc.)

## API Reference
- /api-reference - Complete API documentation

## AI Agent Guide
- /ai-agent-guide - AI integration overview
- /ai-agent-guide/core-api - Essential API (~2000 tokens)
- /ai-agent-guide/quick-reference - Cheatsheet (~500 tokens)

## Essential Code Patterns

### Setup
```typescript
import { createGame } from '@gamebyte/framework';
const game = createGame();
await game.initialize(canvas, '2d');
game.start();
```

### Scene
```typescript
import { BaseScene } from '@gamebyte/framework';
class MyScene extends BaseScene {
    constructor() { super('id', 'Name'); }
    async initialize() { await super.initialize(); }
    update(dt) { super.update(dt); }
}
```

### Graphics Abstraction (Renderer-Agnostic)
```typescript
import { graphics } from '@gamebyte/framework';
const gfx = graphics();
const container = gfx.createContainer();
const rect = gfx.createGraphics();
rect.rect(0, 0, 100, 50).fill(0x4CAF50);
const text = gfx.createText('Hello', { fontSize: 24, fill: 0xffffff });
```

### Game-Style Button
```typescript
import { GameStyleButton, GameStyleColors } from '@gamebyte/framework';
const btn = new GameStyleButton({
    text: 'Play',
    width: 200,
    height: 60,
    colorScheme: GameStyleColors.YELLOW_BUTTON
});
btn.on('click', () => startGame());
```

### Game-Style Tooltip (Speech Bubble)
```typescript
import { GameTooltip, GameTooltipColors } from '@gamebyte/framework';
const tooltip = new GameTooltip({
    text: 'Coming Soon',
    tailPosition: 'bottom-left', // 12 positions + 'none'
    colorScheme: GameTooltipColors.CYAN
});
tooltip.setPosition(100, 50);
stage.addChild(tooltip.getContainer());
tooltip.show(); tooltip.hide(); tooltip.toggle();
```

### Screen Navigation
```typescript
import { ScreenManager, HubScreen } from '@gamebyte/framework';
const screenManager = new ScreenManager({ container: stage, width: 720, height: 1280 });
screenManager.push(new HubScreen({ /* config */ }));
screenManager.push(gameScreen, 'slide');
screenManager.pop();
```

### Tick System (Per-Component Render Loop)
```typescript
import { Tick } from '@gamebyte/framework';
Tick.subscribe(({ delta }) => player.move(delta));
Tick.subscribe(updatePhysics, -10);   // high priority (runs first)
Tick.subscribe(updateParticles, 10);  // low priority (runs last)
Tick.runOnce(({ elapsed }) => console.log('Time:', elapsed));
```

### Resource Lifecycle (Auto-Dispose)
```typescript
import { Resources } from '@gamebyte/framework';
const scope = Resources.createScope('level-1');
const geo = scope.track(new THREE.BoxGeometry(1, 1, 1));
const mat = scope.track(new THREE.MeshStandardMaterial());
Resources.disposeScope('level-1'); // both auto-disposed
```

### 3D Pointer Events
```typescript
import { RaycastEventSystem } from '@gamebyte/framework/three-toolkit';
const events = new RaycastEventSystem();
events.setScene(scene, camera, canvas);
events.on(cube, 'click', (e) => console.log('Hit at', e.point));
events.on(cube, 'pointerenter', () => cube.scale.setScalar(1.1));
events.on(cube, 'pointerleave', () => cube.scale.setScalar(1.0));
```

### Adaptive Performance
```typescript
import { PerformanceAdvisor } from '@gamebyte/framework';
const advisor = new PerformanceAdvisor();
advisor.enable({ targetFps: 55, downgradeThreshold: 45, upgradeThreshold: 58 });
advisor.onQualityChange((tier, dir) => console.log(tier.name, dir));
advisor.regress(); // manual quality drop during heavy interaction
```

### Post-Processing
```typescript
import { PostProcessing } from '@gamebyte/framework';
PostProcessing.add('bloom', { intensity: 0.5, threshold: 0.8 });
PostProcessing.add('vignette', { darkness: 0.3 });
PostProcessing.add('fxaa');
PostProcessing.get('bloom')?.setParams({ intensity: 1.0 });
```

### Environment System
```typescript
import { Environment } from '@gamebyte/framework';
Environment.preset('sunset');
await Environment.transitionTo('night', 5.0); // 5s smooth transition
await Environment.setHDRI('/hdris/studio.hdr');
Environment.setFog({ color: '#aaccee', near: 10, far: 100, type: 'linear' });
```

### Prefab System
```typescript
import { Prefabs } from '@gamebyte/framework';
Prefabs.register({
  id: 'enemy', name: 'Enemy',
  visual: { type: 'model', url: '/models/enemy.glb' },
  tags: ['npc']
});
const enemy = await Prefabs.spawn('enemy', { position: [0, 0, 5] });
enemy.addComponent('health', { current: 100, max: 100 });
const npcs = Prefabs.getEntitiesByTag('npc');
```

### Smart Asset Pipeline
```typescript
import { SmartAssetPipeline } from '@gamebyte/framework';
const pipeline = new SmartAssetPipeline();
pipeline.registerManifest({
  scenes: { level1: ['player', 'bg', 'music'] },
  assets: {
    player: { url: '/textures/player.png', type: 'texture', priority: 'critical' },
    bg: { url: '/textures/bg.png', type: 'texture', priority: 'normal' },
    music: { url: '/audio/bgm.mp3', type: 'audio', priority: 'low' }
  }
});
pipeline.on('progress', (p) => loadingBar.setProgress(p));
await pipeline.loadScene('level1');
pipeline.setMemoryBudget(256); // 256MB max, LRU eviction
```

### Procedural Audio (No Audio Files Needed)
```typescript
import { GameSoundPresets } from '@gamebyte/framework';
const sounds = new GameSoundPresets();
sounds.play('explosion');
sounds.play('coin', { volume: 0.5, pitch: 1.2, variation: 0.3 });
// 15 built-in types: hit, pickup, explosion, laser, powerUp, death,
//   click, jump, land, coin, error, success, whoosh, thrust, nearMiss
```

### GPU Instancing (Three.js)
```typescript
import { InstanceManager } from '@gamebyte/framework/three-toolkit';
const im = new InstanceManager(scene);
for (let i = 0; i < 100; i++) {
  const tree = im.createInstance('tree', treeModel);
  tree.setPosition(Math.random() * 100, 0, Math.random() * 100);
}
// Auto-switches to InstancedMesh at 3+ copies
```

### Input
```typescript
const input = game.make('input');
input.keyboard.on('Space', (pressed) => { if (pressed) jump(); });
```

### Physics
```typescript
import { Physics } from '@gamebyte/framework';
Physics.create2DWorld({ gravity: { x: 0, y: 1 } });
Physics.createBody({ x: 100, y: 100, width: 32, height: 48 });
```

## Key Exports

### Core
- `createGame()` - Entry point
- `BaseScene`, `BaseScene3D` - Scene base classes
- `graphics()` - Renderer-agnostic graphics factory

### New Feature Modules
- `Tick` - Facade for component-level render loop
- `Resources` - Facade for scoped resource lifecycle management
- `PostProcessing` - Facade for post-processing pipeline
- `Environment` - Facade for 3D environment/skybox/fog
- `Prefabs` - Facade for prefab/entity system
- `TickSystem` - Component-level render loop with priority ordering
- `ResourceTracker`, `ResourceScope` - Auto-dispose resource lifecycle
- `PerformanceAdvisor`, `QualityTierManager` - Adaptive quality system
- `PostProcessingPipeline` - Effect merging via pmndrs/postprocessing
- `EnvironmentSystem` - Skybox, fog, sun, presets, transitions
- `PrefabSystem` - JSON-driven prefabs with ECS-lite components
- `SmartAssetPipeline` - Priority loading, memory budgets, LRU eviction
- `GameSoundPresets` - 15 procedural game sound effects

### Three.js Toolkit (sub-path: @gamebyte/framework/three-toolkit)
- `RaycastEventSystem` - DOM-like 3D pointer events with raycasting
- `InstanceManager` - Automatic GPU instancing at 3+ copies

### UI Components
- `GameStyleButton`, `GameButtons` - Game-style buttons
- `GameStylePanel` - Game-style panel with title/close
- `GameTooltip`, `GameTooltipColors` - Speech bubble tooltip/popover
- `GameTopBar` - Resource bar (lives, coins, gems)
- `GameBottomNav` - Bottom navigation
- `ArcheroMenu` - Animated bottom menu with particles
- `HexagonLevelButton`, `LevelPath` - Level selector
- `GameToggle`, `GameSlider` - Form controls
- `UIButton`, `UIPanel`, `UIText`, `UIProgressBar` - Basic UI

### Screens & Panels
- `ScreenManager` - Stack-based screen navigation
- `PanelManager` - Modal/sheet overlay management
- `HubScreen` - Main menu hub
- `GameHUDScreen` - In-game HUD
- `ResultScreen` - Victory/defeat screen
- `GameModalPanel` - Centered modal
- `GameBottomSheet` - Slide-up panel
- `SimpleScreen` - Lightweight screen base

### Color Schemes
- `GameStyleColors.YELLOW_BUTTON`, `GREEN_BUTTON`, `BLUE_BUTTON`, `RED_BUTTON`, `PURPLE_BUTTON`
- `GameStyleColors.PANEL_BLUE`, `PANEL_PURPLE`
- `GameTooltipColors.CYAN`, `.YELLOW`, `.GREEN`, `.RED`, `.PURPLE`, `.DARK`, `.WHITE`
- `ARCHERO_COLORS.red`, `.blue`, `.purple`, `.green`, `.activeYellow`

## Service Keys
- `renderer` - Rendering control
- `scene.manager` - Scene management
- `input` - Input handling
- `audio` - Audio playback
- `assets` - Asset loading
- `physics` - Physics engine
- `tick` - Component-level render loop (TickSystem)
- `resources` - Resource lifecycle management (ResourceTracker)
- `postprocessing` - Post-processing pipeline
- `environment` - 3D environment system (deferred)
- `prefabs` - Prefab/entity system (deferred)
- `asset.pipeline` - Smart asset pipeline (deferred)

## Links
- GitHub: https://github.com/nicholasdelucca/gamebyte-framework
- Full API: /llms-full.txt