game-quality-gates

# Game Quality Gates

Mandatory quality standards for all game projects. Based on 70+ real bugs and industry best practices.

## Core Principle

> Bugs come from **cross-state interactions**, not individual features.
> Each feature works alone; they break in combination.

## 12 Universal Rules (all games)

### 1. Single Cleanup Entry Point 🔄
All exit paths (death/level-complete/quit/pause/scene-switch) call ONE cleanup method with options.

```js
cleanupGameState(opts) {
  // Fixed order: sub-objects → buffs+timers → UI → projectiles → (optional) enemies/controls/events
}
// Every exit: resetBall(), levelComplete(), gameOver(), onShutdown() → calls this
```

**New feature = add one line here. Never scatter cleanup across exits.**

### 2. Respect Active Buffs ⚡
Any code modifying attributes (speed/attack/size/defense) must check for active temporary effects first.

```js
// ❌ speed = Math.max(speed, BASE_SPEED);  // ignores slow buff
// ✅ speed = Math.max(speed, this._currentBaseSpeed);  // buff-aware baseline
```

### 3. Cache Before Destroy 📦
Extract all needed data before `destroy()`/`dispose()`/`remove()`.

```js
const { x, y } = obj; const color = obj.getData('color');
obj.destroy();
spawnParticles(x, y, color);
```

### 4. Timers Follow Lifecycle ⏰
Track all `setTimeout`/`setInterval`/`delayedCall`/`rAF`. Cancel in cleanup.

```js
this.activeTimers.push(this.time.delayedCall(10000, cb));
// In cleanup: this.activeTimers.forEach(t => t.remove(false));
```

### 5. Frame-Rate Independent Logic 🖥️
Multiply all time-dependent logic by delta. Never assume 60fps.

```js
// ✅ player.x += speed * (delta / 1000);
```
- Phaser `update(time, delta)`: delta in ms, divide by 1000
- Three.js `clock.getDelta()`: returns seconds
- Physics: prefer fixed timestep (accumulate delta, step every 16.67ms)

### 6. Scene Transition = Full Cleanup 🚪
On scene/level switch, clean: event listeners, timers, rAF, audio nodes, object pools, WebGL resources (geometry/material/texture d...

# 🎮 Game Quality Gates

> **Stop shipping games with phantom timers, memory leaks, and double-spend exploits.** A battle-tested quality standard for H5/Canvas/WebGL games.

[![ClawHub](https://img.shields.io/badge/ClawHub-game--quality--gates-blue?style=flat-square)](https://clawhub.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
[![Wiki](https://img.shields.io/badge/📖_Wiki-8_pages-purple?style=flat-square)](https://github.com/abczsl520/game-quality-gates/wiki)
[![OpenClaw Skill](https://img.shields.io/badge/OpenClaw-Agent_Skill-orange?style=flat-square)](https://github.com/openclaw/openclaw)

---

## 💀 The Problem

Every feature works fine alone. They break **in combination**:

| Feature A | + Feature B | = Bug |
|-----------|-------------|-------|
| Slow powerup | Paddle collision | Speed value overwritten |
| Multi-ball | Main ball death | Orphan sub-balls still scoring |
| Power-up falling | Player dies | Ghost objects after game over |
| Game over | Buff timers | Phantom timer modifies destroyed object 💥 |

These aren't edge cases — they're the **#1 cause of game bugs**. After fixing **70+ of these bugs** in production H5 games, we encoded the prevention patterns into 12 universal rules.

## 📋 The 12 Universal Rules

| # | Rule | Prevents |
|---|------|---------|
| 1 | 🔄 Single Cleanup Entry Point | "Fixed in A, forgot in B" |
| 2 | ⚡ Respect Active Buffs | Buff silently overwritten |
| 3 | 📦 Cache Before Destroy | Reading dead object props |
| 4 | ⏰ Timers Follow Lifecycle | Phantom timers after game over |
| 5 | 🖥️ Frame-Rate Independent | 30fps device = half speed |
| 6 | 🚪 Scene Switch = Full Cleanup | Memory grows per restart |
| 7 | 🔊 Audio Lifecycle | iOS silent, background still playing |
| 8 | 👆 Input Safety | Double-buy, rapid-fire exploits |
| 9 | 💾 Save State Versioning | Broken saves after update |
| 10 | 🌐 Network Fault Tolerance | Game freezes on bad network |
| 11 | 📦 Asset Loading...