html5-canvas-game

Builds no-engine browser games with Canvas2D (raw WebGL2 only when Canvas stalls), a fixed-timestep loop, sprites, AABB, scenes, and WebAudio unlock-on-gesture. Use when the user wants a lightweight HTML5 canvas game without Phaser or Three.js. Not for Phaser scenes/physics (phaser-game-development) or 3D scene graphs (three-js-web-game). Never move in pixels-per-frame or blit an Image before onload.

跳到安装

仓库: Kayforkind/skill-slice
最近来源活动: 2026年8月14日 22:54
检测到的 SKILL.md 语言: 英语
星标: 0
分支: 0

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

直接命令不会经过审查 Prompt；运行前请先检查来源。

npx skills add https://github.com/Kayforkind/skill-slice --skill html5-canvas-game

命令会保持在同一行。复制前请横向滚动并检查完整内容。

想先保存到本地？可下载 SkillsMP 当前能够提供的文件。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

SKILL.md

来源说明 · 只读预览

返回搜索返回安装

SKILL.md

来源说明 · 只读预览

name	html5-canvas-game
description	Builds no-engine browser games with Canvas2D (raw WebGL2 only when Canvas stalls), a fixed-timestep loop, sprites, AABB, scenes, and WebAudio unlock-on-gesture. Use when the user wants a lightweight HTML5 canvas game without Phaser or Three.js. Not for Phaser scenes/physics (phaser-game-development) or 3D scene graphs (three-js-web-game). Never move in pixels-per-frame or blit an Image before onload.
version	1.0.1

When to Use

Use this skill when building a browser game with hand-controlled rendering: 2D sprites, particles, custom shaders, or pixel-precise visuals from AI-art/SVG assets. This is the lightest web-delivery path (zero framework, zero build step).

Prefer this over three-js-web-game when you don't need a 3D scene graph. Reach for Canvas2D first; drop to raw WebGL only when Canvas2D stalls (see Procedure Step 10).

Trauma-informed default: every scene must be pausable and interruptible. Never lock the player in an unskippable sequence, never autoplay loud audio, and keep pacing under the player's control. Wire Escape/P → pause on day one, not later.

Prerequisites

Host: Windows (PowerShell primary)
Browser: Google Chrome (for standard and headless verification)
Server: Node.js (for npx serve) or Python (for python -m http.server)
Assets: Rasterized images/SVGs from game-art-pipeline

Procedure

1. Project shape

Create a static file structure. No build step. TypeScript is optional — if used, run npx tsc --watch in one terminal and serve the emitted JS.

game/
  index.html      ← canvas + one <script type="module">
  main.js         ← loop, scenes
  engine.js       ← Assets, Input, Audio, math helpers (reusable)
  assets/
    hero.png      ← from game-art-pipeline (AI art / rasterized SVG)
    tiles.png
    hit.wav

index.html:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <style>
    html, body { margin: 0; height: 100%; background: #0b0e14; overflow: hidden; }
    #game { display: block; width: 100vw; height: 100vh; touch-action: none; }
  </style>
</head>
<body>
  <canvas id="game"></canvas>
  <script type="module" src="./main.js"></script>
</body>
</html>

touch-action: none stops the browser stealing pointer gestures for scroll/zoom.

2. The render loop — fixed update, dt-scaled

Never move things by "pixels per frame." Frame rate varies. Move by pixels per second × dt. Use a fixed-timestep accumulator so physics/collision are deterministic, and interpolate the draw.

// main.js
import { Assets, Input, Audio } from './engine.js';

const canvas = document.getElementById('game');
const ctx = canvas.getContext('2d');

function resize() {
  const dpr = window.devicePixelRatio || 1;
  canvas.width  = Math.round(canvas.clientWidth  * dpr);
  canvas.height = Math.round(canvas.clientHeight * dpr);
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);   // draw in CSS pixels, render crisp
  ctx.imageSmoothingEnabled = false;        // crisp pixel art; set true for painterly art
}
addEventListener('resize', resize);
resize();

const STEP = 1 / 60;        // fixed sim step, seconds
let last = performance.now();
let acc = 0;
 paused = ;

 () {
   dt = (now - last) / ;
  last = now;
   (dt > ) dt = ;             

   (!paused) {
    acc += dt;
     (acc >= ) {
      ();                     
      acc -= ;
    }
  }
  (acc / );                    
  (frame);
}
(frame);


(,  { paused = ; });
(,  {
   (e. ===  || e. === ) paused = !paused;
});

Keep update(dt) and render(alpha) separate.

3. Drawing primitives

Canvas2D is an immediate-mode painter's-algorithm API: clear and redraw the whole frame every time.

function render(alpha) {
  ctx.clearRect(0, 0, canvas.clientWidth, canvas.clientHeight);

  // rect
  ctx.fillStyle = '#4cc9f0';
  ctx.fillRect(20, 20, 64, 64);

  // stroked path
  ctx.strokeStyle = '#f72585';
  ctx.lineWidth = 3;
  ctx.beginPath();
  ctx.moveTo(120, 40);
  ctx.lineTo(180, 90);
  ctx.lineTo(120, 90);
  ctx.closePath();
  ctx.stroke();

  // circle
  ctx.beginPath();
  ctx.arc(240, 60, 30, 0, Math.PI * 2);
  ctx.fill();

  // text
  ctx.fillStyle = '#e8eef7';
  ctx.font = '16px system-ui, sans-serif';
  ctx.textBaseline = 'top';
  ctx.fillText(, , );

  
  ctx.();
  ctx.(, );
  ctx.(alpha * .);   
  ctx.(-, -, , );
  ctx.();
}

Rules: batch state changes; always pair save()/restore(); translate then rotate/scale then draw at the origin. Gradients and globalAlpha are cheap; per-pixel getImageData/putImageData is not — avoid it in the hot loop.

4. Sprites from AI-art textures

Draw with the 9-argument drawImage to blit a sub-rectangle (a frame out of a sheet):

// drawImage(img, sx, sy, sw, sh, dx, dy, dw, dh)
//           source rect on the sheet   →   dest rect on canvas
const sheet = Assets.img('hero');
const FW = 48, FH = 48;                 // frame size in the sheet
const frame = Math.floor(animTime * 10) % 6;   // 6-frame walk @ 10 fps
ctx.drawImage(sheet, frame * FW, 0, FW, FH,  x, y, FW, FH);

Guidelines:

Power-of-two-ish sheets, integer frame sizes. Keep frames on a clean grid.
Snap dest to integers for pixel art: Math.round(x).
Pre-render static composites. Draw a rarely-changing background once into an offscreen document.createElement('canvas') and blit that single image each frame.
SVG assets: pre-rasterize SVGs to PNG at target resolution, or draw the SVG into an offscreen canvas at the size you need once.
Flip by ctx.scale(-1, 1) inside a save/restore (translate to the sprite center first).

5. Input — pointer + keyboard

Keyboard as a held-state set (poll it in update), pointer as events. Track listeners to remove them on scene teardown.

// engine.js
export const Input = (() => {
  const down = new Set();
  const pointer = { x: 0, y: 0, down: false };

  addEventListener('keydown', e => { down.add(e.code); });
  addEventListener('keyup',   e => { down.delete(e.code); });
  // guard against stuck keys when focus is lost:
  addEventListener('blur', () => down.clear());

  function bindPointer(canvas) {
    const to = e => {
      const r = canvas.getBoundingClientRect();
      pointer.x = e.clientX - r.left;    // CSS pixels — matches your setTransform space
      pointer.y = e.clientY - r.top;
    };
    canvas.addEventListener('pointermove', to);
    canvas.addEventListener('pointerdown',  => { (e); pointer. = ; });
    (,  { pointer. = ; });
  }

   {
    bindPointer,
    :  down.(code),
    pointer,
  };
})();

Poll in update:

function update(dt) {
  const speed = 200;                      // px per second
  if (Input.held('ArrowLeft')  || Input.held('KeyA')) player.x -= speed * dt;
  if (Input.held('ArrowRight') || Input.held('KeyD')) player.x += speed * dt;
}

6. Game state & scenes

A scene = { enter, update(dt), render(alpha), exit }. A tiny manager swaps them and guarantees exit runs (remove listeners and free assets here).

// engine.js
export class SceneManager {
  #current = null;
  set(scene) {
    if (this.#current?.exit) this.#current.exit();
    this.#current = scene;
    if (scene.enter) scene.enter();
  }
  update(dt)     { this.#current?.update?.(dt); }
  render(alpha)  { this.#current?.render?.(alpha); }
}

const scenes = new SceneManager();

const Play = {
  enter() { Audio.play('music', { loop: true, volume: 0.4 }); },
  update(dt) { /* game logic */ if (dead) scenes.set(GameOver); },
  render(a) { /* draw world */ },
  exit() { Audio.stop('music'); },
};

scenes.set(Title);   // Title → Play → GameOver, each self-contained

7. Collision — AABB

An entity is {x, y, w, h}.

export function aabb(a, b) {
  return a.x < b.x + b.w && a.x + a.w > b.x &&
         a.y < b.y + b.h && a.y + a.h > b.y;
}

// resolve overlap by pushing out on the smaller axis (player vs solid wall):
export function resolve(a, b) {
  const dx = (a.x + a.w / 2) - (b.x + b.w / 2);
  const dy = (a.y + a.h / 2) - (b.y + b.h / 2);
  const ox = (a.w + b.w) / 2 - Math.abs(dx);   // x overlap
  const oy = (a.h + b.h) / 2 - Math.abs(dy);   // y overlap
  if (ox <= 0 || oy <= 0) return;
  if (ox < oy) a. += dx <  ? -ox : ox;       
           a. += dy <  ? -oy : oy;
}

For many entities, spatial-hash into a grid before pairwise tests. Do collision inside the fixed-step update, never in render.

8. Audio — WebAudio, autoplay-safe

WebAudio is sample-accurate and mixable. Browsers suspend the AudioContext until a user gesture — resume it on the first click/keypress or nothing plays.

// engine.js
export const Audio = (() => {
  const ctx = new (window.AudioContext || window.webkitAudioContext)();
  const buffers = new Map();
  const master = ctx.createGain();
  master.gain.value = 0.8;
  master.connect(ctx.destination);

  // unlock on first gesture — required by autoplay policy
  const unlock = () => {
    if (ctx.state === 'suspended') ctx.resume();
    removeEventListener('pointerdown', unlock);
    removeEventListener('keydown', unlock);
  };
  addEventListener('pointerdown', unlock);
  addEventListener('keydown', unlock);

  async function load(name, url) {
    const buf = await fetch(url).then(r => r.arrayBuffer());
    buffers.set(name,  ctx.(buf));
  }

   active =  ();               
   () {
     buf = buffers.(name);
     (!buf) ;
     src = ctx.();
    src. = buf; src. = loop;
     g = ctx.(); g.. = volume;
    src.(g).(master);
    src.();
     (loop) active.(name, src);
     src;
  }
   () { active.(name)?.(); active.(name); }

   { load, play, stop, ctx, master };
})();

Trauma-safe: start master.gain low, expose a volume slider, and never trigger a loud stinger without the player having interacted. Fade with gain.linearRampToValueAtTime.

9. Asset loading manager

Load everything up front behind a progress bar — never blit an Image that hasn't finished decoding.

// engine.js
export const Assets = (() => {
  const images = new Map();

  async function loadAll(manifest, onProgress) {
    const img = manifest.images ?? {};
    const snd = manifest.sounds ?? {};
    const tasks = [
      ...Object.entries(img).map(([k, url]) => () => loadImage(k, url)),
      ...Object.entries(snd).map(([k, url]) => () => Audio.load(k, url)),
    ];
    let done = 0;
    await Promise.all(tasks.map(t => t().then(() => {
      onProgress?.(++done / tasks.length);
    })));
  }

  function loadImage(key, url) {
    return new Promise((res, rej) => {
       im =  ();
      im.  =  { images.(key, im); (); };
      im. =  ( ());
      im. = ;
      im. = url;
    });
  }

   { loadAll, :  images.(k) };
})();

// boot
await Assets.loadAll({
  images: { hero: './assets/hero.png', tiles: './assets/tiles.png' },
  sounds: { hit: './assets/hit.wav',   music: './assets/music.ogg' },
}, p => drawLoadingBar(p));
scenes.set(Title);
requestAnimationFrame(frame);

10. When to drop to raw WebGL

Stay on Canvas2D until you hit a wall, then switch the rendering layer only. Escalate to WebGL when you need:

Thousands of moving sprites / particles.
Fragment shaders — CRT/scanline, bloom, chromatic aberration, water, etc.
Post-processing — render the scene to a framebuffer, then a full-screen shader pass.
Additive/blend-heavy effects at scale (fire, magic, glow).

Minimal WebGL bootstrap:

const gl = canvas.getContext('webgl2', { antialias: false, alpha: false });
const vs = `#version 300 es
in vec2 a_pos; in vec2 a_uv; out vec2 v_uv;
uniform vec2 u_res;
void main(){ v_uv=a_uv; vec2 c=(a_pos/u_res)*2.0-1.0; gl_Position=vec4(c.x,-c.y,0,1);} `;
const fs = `#version 300 es
precision highp float; in vec2 v_uv; out vec4 o; uniform sampler2D u_tex;
void main(){ o = texture(u_tex, v_uv); }`;

function compile(type, src){ const s=gl.createShader(type); gl.shaderSource(s,src);
  gl.compileShader(s); if(!gl.getShaderParameter(s,gl.COMPILE_STATUS))
  throw new Error(gl.getShaderInfoLog(s)); return s; }
const prog = gl.createProgram();
gl.attachShader(prog, compile(gl.VERTEX_SHADER, vs));
gl.attachShader(prog, compile(gl.FRAGMENT_SHADER, fs));
gl.linkProgram(prog); gl.useProgram(prog);
// … upload a quad VBO + texture, set u_res, gl.drawArrays. Then batch/instance sprites.

Hybrid is common: WebGL for the particle/effect layer, a second stacked Canvas2D for crisp UI/text.

Pitfalls

No dt scaling. Moving by fixed px/frame makes the game run at different speeds on 60 vs 144 Hz displays. Always pos += speed * dt, and use a fixed-step accumulator for physics.
Canvas DPI blur. Setting only CSS size (not canvas.width/height × devicePixelRatio + setTransform(dpr,…)) gives a soft, upscaled image on HiDPI screens. Resize the backing store to DPR and redo it on resize.
Blocking / racing asset load. Blitting an Image before onload draws nothing (silent). Await all assets behind a loader + progress bar before starting the loop.
Leaking listeners. Adding keydown/pointer/resize handlers per scene without removing them stacks duplicates → ghost input and memory growth. Track and remove in scene.exit(); clear held-keys on blur.
Ignoring the WebAudio autoplay policy. The AudioContext starts suspended; sound is silent until you ctx.resume() inside a user gesture. Wire an unlock handler on first click/keypress.
No pause / no interruptibility. Beyond the bug of physics spiraling after a backgrounded tab (clamp dt), an unpausable game is trauma-unsafe. Ship Escape/P pause and pause-on-blur from the start.

Verification

No build step. Serve the folder statically and open Chrome. In Windows (PowerShell):

# from the game/ folder — pick one:
npx serve -l 5000 .
# or, no Node:
python -m http.server 5000

Open it:

start chrome "http://localhost:5000"

Verify a change actually rendered — capture a screenshot with headless Chrome. --virtual-time-budget lets rAF frames advance before the shot:

chrome --headless=new --disable-gpu `
  --window-size=1280,720 `
  --virtual-time-budget=2000 `
  --screenshot=shot.png `
  "http://localhost:5000"

Then Read shot.png to confirm the frame looks right (sprites placed, no blank canvas, no DPI blur). Also open Chrome DevTools → Console (catch asset 404s / shader compile errors) and Performance (confirm a steady 16.6 ms frame). For scripted interaction, use Playwright:

npx playwright screenshot --wait-for-timeout=2000 http://localhost:5000 shot.png

Sanity loop: serve → open → screenshot → Read → DevTools console on every visual change.

name	html5-canvas-game
description	Builds no-engine browser games with Canvas2D (raw WebGL2 only when Canvas stalls), a fixed-timestep loop, sprites, AABB, scenes, and WebAudio unlock-on-gesture. Use when the user wants a lightweight HTML5 canvas game without Phaser or Three.js. Not for Phaser scenes/physics (phaser-game-development) or 3D scene graphs (three-js-web-game). Never move in pixels-per-frame or blit an Image before onload.
version	1.0.1

When to Use

Prefer this over three-js-web-game when you don't need a 3D scene graph. Reach for Canvas2D first; drop to raw WebGL only when Canvas2D stalls (see Procedure Step 10).

Trauma-informed default: every scene must be pausable and interruptible. Never lock the player in an unskippable sequence, never autoplay loud audio, and keep pacing under the player's control. Wire Escape/P → pause on day one, not later.

Prerequisites

Host: Windows (PowerShell primary)
Browser: Google Chrome (for standard and headless verification)
Server: Node.js (for npx serve) or Python (for python -m http.server)
Assets: Rasterized images/SVGs from game-art-pipeline

Procedure

1. Project shape

Create a static file structure. No build step. TypeScript is optional — if used, run npx tsc --watch in one terminal and serve the emitted JS.

game/
  index.html      ← canvas + one <script type="module">
  main.js         ← loop, scenes
  engine.js       ← Assets, Input, Audio, math helpers (reusable)
  assets/
    hero.png      ← from game-art-pipeline (AI art / rasterized SVG)
    tiles.png
    hit.wav

index.html:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <style>
    html, body { margin: 0; height: 100%; background: #0b0e14; overflow: hidden; }
    #game { display: block; width: 100vw; height: 100vh; touch-action: none; }
  </style>
</head>
<body>
  <canvas id="game"></canvas>
  <script type="module" src="./main.js"></script>
</body>
</html>

touch-action: none stops the browser stealing pointer gestures for scroll/zoom.

2. The render loop — fixed update, dt-scaled

Never move things by "pixels per frame." Frame rate varies. Move by pixels per second × dt. Use a fixed-timestep accumulator so physics/collision are deterministic, and interpolate the draw.

// main.js
import { Assets, Input, Audio } from './engine.js';

const canvas = document.getElementById('game');
const ctx = canvas.getContext('2d');

function resize() {
  const dpr = window.devicePixelRatio || 1;
  canvas.width  = Math.round(canvas.clientWidth  * dpr);
  canvas.height = Math.round(canvas.clientHeight * dpr);
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);   // draw in CSS pixels, render crisp
  ctx.imageSmoothingEnabled = false;        // crisp pixel art; set true for painterly art
}
addEventListener('resize', resize);
resize();

const STEP = 1 / 60;        // fixed sim step, seconds
let last = performance.now();
let acc = 0;
 paused = ;

 () {
   dt = (now - last) / ;
  last = now;
   (dt > ) dt = ;             

   (!paused) {
    acc += dt;
     (acc >= ) {
      ();                     
      acc -= ;
    }
  }
  (acc / );                    
  (frame);
}
(frame);


(,  { paused = ; });
(,  {
   (e. ===  || e. === ) paused = !paused;
});

Keep update(dt) and render(alpha) separate.

3. Drawing primitives

Canvas2D is an immediate-mode painter's-algorithm API: clear and redraw the whole frame every time.

function render(alpha) {
  ctx.clearRect(0, 0, canvas.clientWidth, canvas.clientHeight);

  // rect
  ctx.fillStyle = '#4cc9f0';
  ctx.fillRect(20, 20, 64, 64);

  // stroked path
  ctx.strokeStyle = '#f72585';
  ctx.lineWidth = 3;
  ctx.beginPath();
  ctx.moveTo(120, 40);
  ctx.lineTo(180, 90);
  ctx.lineTo(120, 90);
  ctx.closePath();
  ctx.stroke();

  // circle
  ctx.beginPath();
  ctx.arc(240, 60, 30, 0, Math.PI * 2);
  ctx.fill();

  // text
  ctx.fillStyle = '#e8eef7';
  ctx.font = '16px system-ui, sans-serif';
  ctx.textBaseline = 'top';
  ctx.fillText(, , );

  
  ctx.();
  ctx.(, );
  ctx.(alpha * .);   
  ctx.(-, -, , );
  ctx.();
}

4. Sprites from AI-art textures

Draw with the 9-argument drawImage to blit a sub-rectangle (a frame out of a sheet):

// drawImage(img, sx, sy, sw, sh, dx, dy, dw, dh)
//           source rect on the sheet   →   dest rect on canvas
const sheet = Assets.img('hero');
const FW = 48, FH = 48;                 // frame size in the sheet
const frame = Math.floor(animTime * 10) % 6;   // 6-frame walk @ 10 fps
ctx.drawImage(sheet, frame * FW, 0, FW, FH,  x, y, FW, FH);

Guidelines:

Power-of-two-ish sheets, integer frame sizes. Keep frames on a clean grid.
Snap dest to integers for pixel art: Math.round(x).
Pre-render static composites. Draw a rarely-changing background once into an offscreen document.createElement('canvas') and blit that single image each frame.
SVG assets: pre-rasterize SVGs to PNG at target resolution, or draw the SVG into an offscreen canvas at the size you need once.
Flip by ctx.scale(-1, 1) inside a save/restore (translate to the sprite center first).

5. Input — pointer + keyboard

Keyboard as a held-state set (poll it in update), pointer as events. Track listeners to remove them on scene teardown.

// engine.js
export const Input = (() => {
  const down = new Set();
  const pointer = { x: 0, y: 0, down: false };

  addEventListener('keydown', e => { down.add(e.code); });
  addEventListener('keyup',   e => { down.delete(e.code); });
  // guard against stuck keys when focus is lost:
  addEventListener('blur', () => down.clear());

  function bindPointer(canvas) {
    const to = e => {
      const r = canvas.getBoundingClientRect();
      pointer.x = e.clientX - r.left;    // CSS pixels — matches your setTransform space
      pointer.y = e.clientY - r.top;
    };
    canvas.addEventListener('pointermove', to);
    canvas.addEventListener('pointerdown',  => { (e); pointer. = ; });
    (,  { pointer. = ; });
  }

   {
    bindPointer,
    :  down.(code),
    pointer,
  };
})();

Poll in update:

function update(dt) {
  const speed = 200;                      // px per second
  if (Input.held('ArrowLeft')  || Input.held('KeyA')) player.x -= speed * dt;
  if (Input.held('ArrowRight') || Input.held('KeyD')) player.x += speed * dt;
}

6. Game state & scenes

A scene = { enter, update(dt), render(alpha), exit }. A tiny manager swaps them and guarantees exit runs (remove listeners and free assets here).

// engine.js
export class SceneManager {
  #current = null;
  set(scene) {
    if (this.#current?.exit) this.#current.exit();
    this.#current = scene;
    if (scene.enter) scene.enter();
  }
  update(dt)     { this.#current?.update?.(dt); }
  render(alpha)  { this.#current?.render?.(alpha); }
}

const scenes = new SceneManager();

const Play = {
  enter() { Audio.play('music', { loop: true, volume: 0.4 }); },
  update(dt) { /* game logic */ if (dead) scenes.set(GameOver); },
  render(a) { /* draw world */ },
  exit() { Audio.stop('music'); },
};

scenes.set(Title);   // Title → Play → GameOver, each self-contained

7. Collision — AABB

An entity is {x, y, w, h}.

export function aabb(a, b) {
  return a.x < b.x + b.w && a.x + a.w > b.x &&
         a.y < b.y + b.h && a.y + a.h > b.y;
}

// resolve overlap by pushing out on the smaller axis (player vs solid wall):
export function resolve(a, b) {
  const dx = (a.x + a.w / 2) - (b.x + b.w / 2);
  const dy = (a.y + a.h / 2) - (b.y + b.h / 2);
  const ox = (a.w + b.w) / 2 - Math.abs(dx);   // x overlap
  const oy = (a.h + b.h) / 2 - Math.abs(dy);   // y overlap
  if (ox <= 0 || oy <= 0) return;
  if (ox < oy) a. += dx <  ? -ox : ox;       
           a. += dy <  ? -oy : oy;
}

For many entities, spatial-hash into a grid before pairwise tests. Do collision inside the fixed-step update, never in render.

8. Audio — WebAudio, autoplay-safe

WebAudio is sample-accurate and mixable. Browsers suspend the AudioContext until a user gesture — resume it on the first click/keypress or nothing plays.

// engine.js
export const Audio = (() => {
  const ctx = new (window.AudioContext || window.webkitAudioContext)();
  const buffers = new Map();
  const master = ctx.createGain();
  master.gain.value = 0.8;
  master.connect(ctx.destination);

  // unlock on first gesture — required by autoplay policy
  const unlock = () => {
    if (ctx.state === 'suspended') ctx.resume();
    removeEventListener('pointerdown', unlock);
    removeEventListener('keydown', unlock);
  };
  addEventListener('pointerdown', unlock);
  addEventListener('keydown', unlock);

  async function load(name, url) {
    const buf = await fetch(url).then(r => r.arrayBuffer());
    buffers.set(name,  ctx.(buf));
  }

   active =  ();               
   () {
     buf = buffers.(name);
     (!buf) ;
     src = ctx.();
    src. = buf; src. = loop;
     g = ctx.(); g.. = volume;
    src.(g).(master);
    src.();
     (loop) active.(name, src);
     src;
  }
   () { active.(name)?.(); active.(name); }

   { load, play, stop, ctx, master };
})();

Trauma-safe: start master.gain low, expose a volume slider, and never trigger a loud stinger without the player having interacted. Fade with gain.linearRampToValueAtTime.

9. Asset loading manager

Load everything up front behind a progress bar — never blit an Image that hasn't finished decoding.

// engine.js
export const Assets = (() => {
  const images = new Map();

  async function loadAll(manifest, onProgress) {
    const img = manifest.images ?? {};
    const snd = manifest.sounds ?? {};
    const tasks = [
      ...Object.entries(img).map(([k, url]) => () => loadImage(k, url)),
      ...Object.entries(snd).map(([k, url]) => () => Audio.load(k, url)),
    ];
    let done = 0;
    await Promise.all(tasks.map(t => t().then(() => {
      onProgress?.(++done / tasks.length);
    })));
  }

  function loadImage(key, url) {
    return new Promise((res, rej) => {
       im =  ();
      im.  =  { images.(key, im); (); };
      im. =  ( ());
      im. = ;
      im. = url;
    });
  }

   { loadAll, :  images.(k) };
})();

// boot
await Assets.loadAll({
  images: { hero: './assets/hero.png', tiles: './assets/tiles.png' },
  sounds: { hit: './assets/hit.wav',   music: './assets/music.ogg' },
}, p => drawLoadingBar(p));
scenes.set(Title);
requestAnimationFrame(frame);

10. When to drop to raw WebGL

Stay on Canvas2D until you hit a wall, then switch the rendering layer only. Escalate to WebGL when you need:

Thousands of moving sprites / particles.
Fragment shaders — CRT/scanline, bloom, chromatic aberration, water, etc.
Post-processing — render the scene to a framebuffer, then a full-screen shader pass.
Additive/blend-heavy effects at scale (fire, magic, glow).

Minimal WebGL bootstrap:

const gl = canvas.getContext('webgl2', { antialias: false, alpha: false });
const vs = `#version 300 es
in vec2 a_pos; in vec2 a_uv; out vec2 v_uv;
uniform vec2 u_res;
void main(){ v_uv=a_uv; vec2 c=(a_pos/u_res)*2.0-1.0; gl_Position=vec4(c.x,-c.y,0,1);} `;
const fs = `#version 300 es
precision highp float; in vec2 v_uv; out vec4 o; uniform sampler2D u_tex;
void main(){ o = texture(u_tex, v_uv); }`;

function compile(type, src){ const s=gl.createShader(type); gl.shaderSource(s,src);
  gl.compileShader(s); if(!gl.getShaderParameter(s,gl.COMPILE_STATUS))
  throw new Error(gl.getShaderInfoLog(s)); return s; }
const prog = gl.createProgram();
gl.attachShader(prog, compile(gl.VERTEX_SHADER, vs));
gl.attachShader(prog, compile(gl.FRAGMENT_SHADER, fs));
gl.linkProgram(prog); gl.useProgram(prog);
// … upload a quad VBO + texture, set u_res, gl.drawArrays. Then batch/instance sprites.

Hybrid is common: WebGL for the particle/effect layer, a second stacked Canvas2D for crisp UI/text.

Pitfalls

No dt scaling. Moving by fixed px/frame makes the game run at different speeds on 60 vs 144 Hz displays. Always pos += speed * dt, and use a fixed-step accumulator for physics.
Canvas DPI blur. Setting only CSS size (not canvas.width/height × devicePixelRatio + setTransform(dpr,…)) gives a soft, upscaled image on HiDPI screens. Resize the backing store to DPR and redo it on resize.
Blocking / racing asset load. Blitting an Image before onload draws nothing (silent). Await all assets behind a loader + progress bar before starting the loop.
Leaking listeners. Adding keydown/pointer/resize handlers per scene without removing them stacks duplicates → ghost input and memory growth. Track and remove in scene.exit(); clear held-keys on blur.
Ignoring the WebAudio autoplay policy. The AudioContext starts suspended; sound is silent until you ctx.resume() inside a user gesture. Wire an unlock handler on first click/keypress.
No pause / no interruptibility. Beyond the bug of physics spiraling after a backgrounded tab (clamp dt), an unpausable game is trauma-unsafe. Ship Escape/P pause and pause-on-blur from the start.

Verification

No build step. Serve the folder statically and open Chrome. In Windows (PowerShell):

# from the game/ folder — pick one:
npx serve -l 5000 .
# or, no Node:
python -m http.server 5000

Open it:

start chrome "http://localhost:5000"

Verify a change actually rendered — capture a screenshot with headless Chrome. --virtual-time-budget lets rAF frames advance before the shot:

chrome --headless=new --disable-gpu `
  --window-size=1280,720 `
  --virtual-time-budget=2000 `
  --screenshot=shot.png `
  "http://localhost:5000"

npx playwright screenshot --wait-for-timeout=2000 http://localhost:5000 shot.png

Sanity loop: serve → open → screenshot → Read → DevTools console on every visual change.

html5-canvas-game

来源信息

安装方式

检查来源文件

同仓库更多 Skills

同仓库更多 Skills

When to Use

Prerequisites

Procedure

1. Project shape

2. The render loop — fixed update, dt-scaled

3. Drawing primitives

4. Sprites from AI-art textures

5. Input — pointer + keyboard

6. Game state & scenes

7. Collision — AABB

8. Audio — WebAudio, autoplay-safe

9. Asset loading manager

10. When to drop to raw WebGL

Pitfalls

Verification

When to Use

Prerequisites

Procedure

1. Project shape

2. The render loop — fixed update, dt-scaled

3. Drawing primitives

4. Sprites from AI-art textures

5. Input — pointer + keyboard

6. Game state & scenes

7. Collision — AABB

8. Audio — WebAudio, autoplay-safe

9. Asset loading manager

10. When to drop to raw WebGL

Pitfalls

Verification