docs: write down the changelog convention, and apply it to 20.2.0

CONTRIBUTING.md

@@ -116,6 +116,41 @@ melonJS uses [ESLint](https://eslint.org) and [Biome](https://biomejs.dev) to en
 - Follow the existing patterns in the codebase
 - If you fix a bug, consider adding a test to prevent it from recurring
 
+## Changelog entries
+
+User-facing changes go in `packages/melonjs/CHANGELOG.md`, under the current
+`_unreleased_` heading. Entries read `Subsystem: what changed`, in one or two
+sentences:
+
+```markdown
+- Renderer: `setLineDash()` and `getLineDash()` — set dash patterns for stroke
+  operations, matching the Canvas 2D API. Works on both Canvas and WebGL.
+- Path2D: fix `quadraticCurveTo()` using a reference to `startPoint` instead of
+  capturing coordinates — `lineTo()` mutates it on each call, deforming the
+  curve as it was tessellated.
+```
+
+Say what changed and what it means for someone using the engine. A bug entry
+needs the mechanism and the symptom; it does not need how it was found, why it
+went unnoticed, or what else was tried.
+
+**Only write down what affects a released version.** A bug introduced and fixed
+within the same unreleased cycle never reached anyone, so it does not belong in
+the changelog — nor do changes to the test suite or other internals.
+
+Some other rules worth knowing:
+
+- The sections are `Added`, `Performance`, `Fixed`, `Changed` and
+  `Deprecated`. `Changed` is for **user-facing API changes only** — a game
+  looking different because of something under `Added` is not a change.
+- Anything that alters existing behaviour must say so plainly, with what to do
+  about it.
+- A feature release opens with a short `**Highlights:**` paragraph.
+- Quote measurements only as precisely as they were measured, and say what
+  hardware produced them.
+- Credit external contributors with a bare handle at the end: `(thanks @user)`.
+- Examples are not part of the engine and do not appear here.
+
 ## Submitting changes
 
 1. Fork the repository and create a new branch from `master`

packages/melonjs/DOC_README.md → DOC_README.md

@@ -30,24 +30,31 @@ const app = new Application(1218, 562, {
     backgroundColor: "#202020",
 });
 
+// initialize it (builds the renderer and appends the canvas)
+await app.init();
+
 // load and add a sprite
 loader.preload([{ name: "player", type: "image", src: "player.png" }], () => {
     app.world.addChild(new Sprite(609, 281, { image: "player" }));
 });
 ```
 
+> **Note:** since version 20.0, `await app.init()` is **required** after constructing the `Application`. The WebGPU backend, which `AUTO` tries first where available, acquires its GPU device asynchronously; the call resolves without suspending on the WebGL and Canvas backends.
+
 ## Features
 
 | Feature | Description |
 |---------|-------------|
-| **Rendering** | WebGL & Canvas 2D with automatic fallback, 3D mesh rendering with OBJ/MTL support |
-| **Tiled Maps** | First-class [Tiled](https://www.mapeditor.org/) map editor support (TMX/JSON) |
+| **Rendering** | WebGPU, WebGL 2 and Canvas 2D with automatic fallback — the same feature set on every backend |
+| **3D** | Perspective [Camera3d](classes/Camera3d.html), mesh instancing, ground shadows, point and spot lights, glTF/GLB and OBJ/MTL loading |
+| **Tiled Maps** | First-class [Tiled](https://www.mapeditor.org/) map editor support (TMX/JSON), with GPU-accelerated tile rendering for orthogonal maps |
 | **Sprites** | Texture atlas, animation, TexturePacker & Aseprite support |
-| **Physics** | Built-in collision detection (SAT), gravity, friction |
-| **Audio** | Web Audio API with format fallback |
+| **Physics** | Built-in SAT collision with gravity and friction, shape-level collision events, and a [PhysicsAdapter](interfaces/PhysicsAdapter.html) interface for Box2D (planck) or Matter.js |
+| **Audio** | Web Audio API with format fallback, plus procedural tone and noise generation |
 | **Input** | Keyboard, mouse, touch, gamepad |
-| **Particles** | Configurable particle emitter system |
-| **Custom Shaders** | Per-sprite [ShaderEffect](classes/ShaderEffect.html) for WebGL fragment effects |
+| **Particles** | Configurable [ParticleEmitter](classes/ParticleEmitter.html), with a reference space so particles can be measured from the emitter, the world, or any container |
+| **Effects** | All thirteen CSS blend modes on every renderer, tinting, masking, and camera post-processing chains |
+| **Custom Shaders** | Per-sprite [ShaderEffect](classes/ShaderEffect.html) carrying both GLSL and WGSL, so one effect runs on either GPU backend |
 | **UI** | Built-in UI components (buttons, text input, containers) |
 
 ## Common Tasks
@@ -110,19 +117,19 @@ this.body.setFriction(0.4, 0);
 See: [`Body`](classes/Body.html), [`collision`](modules/collision.html)
 
 #### Apply a custom shader effect to a sprite
-Apply a per-sprite fragment shader using `ShaderEffect`. You only need to write the color transformation — the vertex shader and texture sampling are handled automatically. Works with WebGL, silently ignored in Canvas mode.
+Apply a per-sprite fragment shader using `ShaderEffect`. You only need to write the color transformation — the vertex shader and texture sampling are handled automatically. Runs on both GPU backends — write the body once and it is realized as GLSL or WGSL for the active renderer — and is silently ignored in Canvas mode.
 ```javascript
 import { ShaderEffect } from "melonjs";
 
 // apply a grayscale effect to a sprite
-mySprite.shader = new ShaderEffect(renderer, `
+mySprite.addPostEffect(new ShaderEffect(renderer, `
     vec4 apply(vec4 color, vec2 uv) {
         float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));
         return vec4(vec3(gray), color.a);
     }
-`);
+`));
 ```
-See: [`ShaderEffect`](classes/ShaderEffect.html), [`GLShader`](classes/GLShader.html)
+See: [`ShaderEffect`](classes/ShaderEffect.html), [`addPostEffect`](classes/Renderable.html#addposteffect)
 
 ## Links
 

README.md

@@ -51,7 +51,7 @@ Graphics
 - Extensible batcher system for custom rendering pipelines, with backend-neutral vertex formats and draw topologies (declare a layout once, describe it to either GPU backend)
 - High DPI resolution & Canvas advanced auto scaling
 - Sprite with 9-slice scaling option and frame animation
-- Built-in effects such as tinting, masking, and CSS-style blend modes (normal, none, additive, multiply, screen, darken, lighten)
+- Built-in effects such as tinting, masking, and the full set of CSS-style blend modes (normal, none, additive, multiply, screen, exclusion, darken, lighten, overlay, hard-light, color-dodge, color-burn, soft-light, difference) — all of them supported identically on WebGPU, WebGL 2 and Canvas since 20.2
 - Standard spritesheet, single and multiple Packed Textures support
 - Compressed texture support (DDS, KTX, KTX2, PVR, PKM) with automatic format detection and fallback
 - Hardware antialiasing (`antiAlias: true`) on both GPU backends — and it survives post-processing, since the offscreen targets a post-effect chain renders into are multisampled to match
@@ -138,7 +138,7 @@ Core
 - Tween effects with multiple easing functions (Quadratic, Cubic, Elastic, Bounce, etc.) and Bezier/Catmull-Rom interpolation
 - Transition effects
 - Pooling support for object recycling
-- Particle system with `ParticleEmitter` (emission rate, lifetime, velocity, gravity, blend modes)
+- Particle system with `ParticleEmitter` (emission rate, lifetime, velocity, gravity, blend modes), and a reference space so particles can be measured from the emitter, from the world, or from any container — a moving emitter leaves a trail instead of dragging its cloud along
 - EventEmitter based event system
 - Persistent data storage (save/load via localStorage)
 - Plugin system for extending engine capabilities