matterjs
2D physics engine for interactive UI, games, and dynamic visual effects. Covers Engine/World setup, Render/Runner config, bodies, constraints, mouse interaction, SPA cleanup, and offscreen pause. Trigger: When implementing 2D physics interactions, gravity simulations, draggable physics objects, or any Matter.js physics scene.
- License 许可
- Apache-2.0
- 最近更新
- 2026-08-26
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- matterjs
- license
- Apache-2.0
- metadata
- { "author": "gentleman-programming (inspired by MengTo/Skills)", "version": "1.0" }
- description
- 2D physics engine for interactive UI, games, and dynamic visual effects. Covers Engine/World setup, Render/Runner config, bodies, constraints, mouse interaction, SPA cleanup, and offscreen pause. Trigger: When implementing 2D physics interactions, gravity simulations, draggable physics objects, or any Matter.js physics scene.
03 SKILL.md 正文
When to Use
- Interactive 2D physics (falling, bouncing, colliding elements)
- Draggable objects with physics behavior
- Gravity-based UI elements or games
- Physics sandbox, simulations, or data visualizations
Core Setup
Minimal (quick start)
<script src="https://cdnjs.cloudflare.com/ajax/libs/matter-js/0.19.0/matter.min.js"></script>
<script>
const { Engine, Render, Runner, Bodies, Composite } = Matter;
const engine = Engine.create();
const render = Render.create({
element: document.body,
engine: engine,
options: { width: 800, height: 600, wireframes: false },
});
const runner = Runner.create();
Runner.run(runner, engine);
Render.run(render);
// Static ground
const ground = Bodies.rectangle(400, 610, 810, 60, { isStatic: true });
// Dynamic box
const box = Bodies.rectangle(400, 200, 80, 80);
Composite.add(engine.world, [ground, box]);
</script>
ES Module (npm)
npm i matter-js
import Matter from "matter-js";
const { Engine, Render, Runner, Bodies, Composite } = Matter;
Common Patterns
Bodies
// Rectangle (static: platform, dynamic: falling)
const platform = Bodies.rectangle(x, y, width, height, { isStatic: true });
const box = Bodies.rectangle(x, y, width, height);
// Circle
const ball = Bodies.circle(x, y, radius);
// Polygon (sides = 3 for triangle, 6 for hexagon, etc.)
const hex = Bodies.polygon(x, y, 6, radius);
// Compound body (multiple parts as one physics object)
const compound = Body.create({
parts: [
Bodies.rectangle(0, 0, 100, 20),
Bodies.rectangle(0, -20, 20, 40),
],
});
Adding to World
// Single
Composite.add(engine.world, body);
// Multiple
Composite.add(engine.world, [bodyA, bodyB, bodyC]);
Mouse Interaction
const { Mouse, MouseConstraint } = Matter;
const mouse = Mouse.create(render.canvas);
const mouseConstraint = MouseConstraint.create(engine, {
mouse,
constraint: {
stiffness: 0.2,
render: { visible: false },
},
});
Composite.add(engine.world, mouseConstraint);
render.mouse = mouse;
Mouse Constraint Options
{
mouse: mouse,
constraint: {
stiffness: 0.2, // lower = more elastic
damping: 0.1, // resistance to motion
render: { visible: false },
// angularStiffness: 0.1, // for rotation
},
}
Constraints & Joints
const { Constraint } = Matter;
// Pin body to a point in space
const constraint = Constraint.create({
pointA: { x: 400, y: 100 },
bodyB: box,
pointB: { x: 0, y: 0 },
stiffness: 0.9,
length: 0,
});
Composite.add(engine.world, constraint);
// Connect two bodies
const rope = Constraint.create({
bodyA: body1,
bodyB: body2,
stiffness: 0.8,
length: 100,
});
Collision Events
const { Events } = Matter;
Events.on(engine, "collisionStart", (event) => {
event.pairs.forEach((pair) => {
console.log("Collision:", pair.bodyA.label, pair.bodyB.label);
});
});
Events.on(engine, "collisionEnd", (event) => { /* ... */ });
Render Options
Render.create({
element: container,
engine,
options: {
width: 800,
height: 600,
wireframes: false, // true = debug outlines
background: "#0f0f0f",
// showAngleIndicator: true,
// showVelocity: true,
// showCollisions: true,
},
});
Custom Rendering (no Matter.Render)
Use this when you want to draw bodies yourself (e.g., with canvas, PixiJS, Three.js).
function customUpdate() {
Engine.update(engine, 1000 / 60);
// Your custom render loop here
requestAnimationFrame(customUpdate);
}
customUpdate();
SPA Cleanup
function cleanupPhysics() {
Runner.stop(runner);
Render.stop(render);
if (render.canvas.parentNode) {
render.canvas.parentNode.removeChild(render.canvas);
}
Engine.clear(engine);
Composite.clear(engine.world, false);
}
Offscreen Pause (performance)
const observer = new IntersectionObserver(
([entry]) => {
if (entry.isIntersecting) {
Runner.run(runner, engine);
} else {
Runner.stop(runner);
}
},
{ threshold: 0 }
);
observer.observe(container);
// Cleanup observer when component unmounts
// observer.disconnect();
Performance Rules
- ✅ Use
isStatic: truefor scenery/ground (doesn't simulate) - ✅ Pause runner when offscreen (IntersectionObserver)
- ✅ Limit total bodies (< 200 for mobile)
- ❌ No wireframes in production (set
wireframes: false) - ❌ No
Render.run()+ custom render simultaneously - ❌ No high
stiffnesson mouse constraints (feels janky)
What to Ask the User
- Viewport size and canvas dimensions?
- Are we using Matter.Render or custom rendering?
- Mouse/touch drag interaction needed?
- Should physics pause when offscreen?
- Gravity direction (default: down)?
04 同仓库更多 Skills
zustand-5
Zustand 5 state management patterns. Trigger: When managing React state with Zustand.
zod-4
Zod 4 schema validation patterns. Trigger: When using Zod for validation - breaking changes from v3.
x-bookmark-quote-posts
Workflow para revisar bookmarks de X/Twitter y convertirlos en drafts de quote posts. Accede a la sección de bookmarks vía browser headless, extrae posts recientes, y genera drafts con voz personal del usuario. No publica ni muta X — solo genera contenido para revisión. Trigger: X bookmarks, Twitter bookmarks, quote posts, bookmark automation, crear quote posts, revisar bookmarks, growth content X.
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
work-unit-commits
Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.