Repository navigation
Rendering API
The melonJS rendering API is designed to feel familiar to anyone who has used the HTML5 Canvas 2D API (CanvasRenderingContext2D). Whether you choose the Canvas, WebGL or WebGPU renderer, the API remains the same — write your game once, and it runs on every backend with zero code changes.
// This code works identically on Canvas, WebGL and WebGPU
renderer.save();
renderer.translate(100, 50);
renderer.rotate(Math.PI / 4);
renderer.setColor("#FF0000");
renderer.fillRect(0, 0, 64, 64);
renderer.restore();If you've used ctx.save(), ctx.translate(), ctx.fillRect() on a Canvas 2D context, you already know the melonJS rendering API.
See these features in action:
- Graphics — shapes, paths, bezier curves, dashed lines, masks, transforms
- Gradients — linear/radial gradients on rects, ellipses, polygons, rounded rects
- Blend Modes — all supported composite operations
The table below maps every melonJS renderer method to its Canvas 2D equivalent.
| melonJS | Canvas 2D Equivalent | Description |
|---|---|---|
save() |
ctx.save() |
Push the current renderer state onto a stack |
restore() |
ctx.restore() |
Pop and restore the most recently saved state |
reset() |
— | Reset the entire renderer context to its default state |
clear() |
— | Prepare the framebuffer for a new frame |
flush() |
— | Flush the render pipeline (WebGL batches; no-op on Canvas) |
| melonJS | Canvas 2D Equivalent | Description |
|---|---|---|
translate(x, y) |
ctx.translate(x, y) |
Add a translation transformation |
rotate(angle) |
ctx.rotate(angle) |
Add a rotation (radians) to the transformation matrix |
scale(x, y) |
ctx.scale(x, y) |
Add a scaling transformation |
transform(a, b, c, d, e, f) |
ctx.transform(a, b, c, d, e, f) |
Multiply the current matrix by the given one |
setTransform(a, b, c, d, e, f) |
ctx.setTransform(a, b, c, d, e, f) |
Reset the matrix then apply the given one |
resetTransform() |
ctx.setTransform(1,0,0,1,0,0) |
Reset the transformation matrix to identity |
setProjection(matrix) |
— | Set the projection matrix (orthographic) |
| melonJS | Canvas 2D Equivalent | Description |
|---|---|---|
setColor(color) |
ctx.fillStyle / ctx.strokeStyle
|
Set the current fill and stroke color (accepts Color, string, or Gradient) |
getColor() |
— | Get the current fill and stroke color |
createLinearGradient(x0, y0, x1, y1) |
ctx.createLinearGradient(x0, y0, x1, y1) |
Create a linear gradient fill |
createRadialGradient(x0, y0, r0, x1, y1, r1) |
ctx.createRadialGradient(x0, y0, r0, x1, y1, r1) |
Create a radial gradient fill |
gradient.addColorStop(offset, color) |
gradient.addColorStop(offset, color) |
Add a color stop to a gradient |
setGlobalAlpha(alpha) |
ctx.globalAlpha = alpha |
Set the global alpha (opacity) |
getGlobalAlpha() |
ctx.globalAlpha |
Get the current global alpha |
setTint(tint, alpha) |
— | Set a coloring tint for sprite rendering |
clearTint() |
— | Clear the current rendering tint |
setBlendMode(mode) |
ctx.globalCompositeOperation |
Set the blend/composite mode |
getBlendMode() |
ctx.globalCompositeOperation |
Get the current blend mode |
Gradient example:
const gradient = renderer.createLinearGradient(0, 0, 200, 0);
gradient.addColorStop(0, "#00FF00");
gradient.addColorStop(0.5, "#FFFF00");
gradient.addColorStop(1, "#FF0000");
renderer.setColor(gradient);
renderer.fillRect(10, 10, 200, 24);| melonJS | Canvas 2D Equivalent | Description |
|---|---|---|
fillRect(x, y, w, h) |
ctx.fillRect(x, y, w, h) |
Fill a rectangle |
strokeRect(x, y, w, h) |
ctx.strokeRect(x, y, w, h) |
Stroke a rectangle outline |
clearRect(x, y, w, h) |
ctx.clearRect(x, y, w, h) |
Erase pixels in a rectangular area |
clearColor(color, opaque) |
— | Clear the framebuffer with a solid color |
fillRoundRect(x, y, w, h, r) |
ctx.roundRect() + ctx.fill()
|
Fill a rounded rectangle |
strokeRoundRect(x, y, w, h, r) |
ctx.roundRect() + ctx.stroke()
|
Stroke a rounded rectangle outline |
| melonJS | Canvas 2D Equivalent | Description |
|---|---|---|
beginPath() |
ctx.beginPath() |
Start a new path |
closePath() |
ctx.closePath() |
Close the current sub-path |
moveTo(x, y) |
ctx.moveTo(x, y) |
Move to a point without drawing |
lineTo(x, y) |
ctx.lineTo(x, y) |
Draw a straight line to a point |
quadraticCurveTo(cpx, cpy, x, y) |
ctx.quadraticCurveTo(cpx, cpy, x, y) |
Add a quadratic Bezier curve to the path |
bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y) |
ctx.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y) |
Add a cubic Bezier curve to the path |
arcTo(x1, y1, x2, y2, radius) |
ctx.arcTo(x1, y1, x2, y2, radius) |
Add a circular arc using control points and radius |
rect(x, y, w, h) |
ctx.rect(x, y, w, h) |
Add a rectangle to the current path |
roundRect(x, y, w, h, radii) |
ctx.roundRect(x, y, w, h, radii) |
Add a rounded rectangle to the current path |
stroke(shape) |
ctx.stroke() |
Stroke the current path or a given shape |
fill(shape) |
ctx.fill() |
Fill the current path or a given shape |
Bezier curve example:
renderer.beginPath();
renderer.setColor("#10b981");
renderer.moveTo(0, 100);
renderer.bezierCurveTo(100, 0, 200, 200, 300, 100);
renderer.stroke();| melonJS | Canvas 2D Equivalent | Description |
|---|---|---|
strokeArc(x, y, r, start, end) |
ctx.arc() + ctx.stroke()
|
Stroke an arc |
fillArc(x, y, r, start, end) |
ctx.arc() + ctx.fill()
|
Fill an arc |
strokeEllipse(x, y, w, h) |
ctx.ellipse() + ctx.stroke()
|
Stroke an ellipse |
fillEllipse(x, y, w, h) |
ctx.ellipse() + ctx.fill()
|
Fill an ellipse |
strokeLine(x1, y1, x2, y2) |
ctx.moveTo() + ctx.lineTo() + ctx.stroke()
|
Stroke a line between two points |
fillLine(x1, y1, x2, y2) |
ctx.moveTo() + ctx.lineTo() + ctx.fill()
|
Fill a line between two points |
strokePolygon(poly) |
ctx.lineTo() loop + ctx.stroke()
|
Stroke a polygon |
fillPolygon(poly) |
ctx.lineTo() loop + ctx.fill()
|
Fill a polygon |
strokePoint(x, y) |
— | Stroke a single point |
fillPoint(x, y) |
— | Fill a single point |
| melonJS | Canvas 2D Equivalent | Description |
|---|---|---|
drawImage(image, ...) |
ctx.drawImage(image, ...) |
Draw an image (supports all 3/5/9 argument forms) |
createPattern(image, repeat) |
ctx.createPattern(image, repeat) |
Create a repeating image pattern |
drawPattern(pattern, x, y, w, h) |
ctx.fillStyle = pattern + ctx.fillRect()
|
Draw a pattern within a rectangle |
| melonJS | Canvas 2D Equivalent | Description |
|---|---|---|
clipRect(x, y, w, h) |
ctx.rect() + ctx.clip()
|
Clip rendering to a rectangular region |
setMask(mask, invert) |
ctx.clip() / gl.stencilFunc()
|
Apply an arbitrary shape as a rendering mask |
clearMask() |
— | Remove the current rendering mask |
| melonJS | Canvas 2D Equivalent | Description |
|---|---|---|
setLineDash(segments) |
ctx.setLineDash(segments) |
Set the dash pattern for stroke operations |
getLineDash() |
ctx.getLineDash() |
Get the current dash pattern |
lineWidth |
ctx.lineWidth |
Line thickness (property, not a method) |
Dashed line example:
renderer.setLineDash([10, 5]);
renderer.strokeLine(0, 50, 300, 50);
renderer.setLineDash([]); // back to solid| melonJS | Canvas 2D Equivalent | Description |
|---|---|---|
setAntiAlias(enable) |
ctx.imageSmoothingEnabled |
Enable or disable image smoothing/anti-aliasing |
| melonJS | Canvas 2D Equivalent | Description |
|---|---|---|
getCanvas() |
canvas |
Return the underlying canvas element |
getContext() |
canvas.getContext('2d') |
Return the underlying rendering context |
resize(w, h) |
Setting canvas.width / canvas.height
|
Resize the rendering canvas |
overlaps(bounds) |
— | Check if a bounding box overlaps the visible area |
toBlob(type, quality) |
canvas.toBlob() |
Export the current frame as a Blob |
toDataURL(type, quality) |
canvas.toDataURL() |
Export the current frame as a data URL |
toImageBitmap(type, quality) |
createImageBitmap(canvas) |
Export the current frame as an ImageBitmap |
These methods are available on every renderer but only do meaningful work on the GPU backends (WebGL and WebGPU). On Canvas they are safe to call but have no effect or return empty/default values:
| melonJS | Description |
|---|---|
addBatcher(batcher, name) |
Add a custom batcher for specialized rendering (extend WebGLBatcher / WebGPUBatcher to match the active backend) |
setBatcher(name, shader) |
Switch the active rendering batcher |
setViewport(x, y, w, h) |
Set the viewport rectangle (split-screen cameras) |
getSupportedCompressedTextureFormats() |
List supported GPU compressed texture formats (returns empty on Canvas) |
While the API mirrors Canvas 2D closely, there are a few design differences:
-
Unified color setter — melonJS uses
setColor(color)to set bothfillStyleandstrokeStyleat once, rather than having two separate properties. -
Convenience shape methods — Instead of building paths manually, melonJS provides direct
strokeRect,fillEllipse,strokePolygon, etc. methods that accept melonJS shape objects (Rect, Ellipse, Polygon). -
Tinting —
setTint()/clearTint()provide sprite-level color tinting with no Canvas 2D equivalent. -
Automatic batching — The GPU renderers automatically batch draw calls. Call
flush()explicitly only when you need to force a batch submission (e.g. before reading pixels). -
Blend modes — Every renderer supports the same blend mode names (
normal,multiply,screen,additive,darken,lighten,none, etc.), abstracting away the difference betweenglobalCompositeOperation(Canvas), GL blend functions (WebGL), and pipeline blend states (WebGPU).
import { Application, video } from "melonjs";
// Auto-negotiate the best backend: WebGPU → WebGL 2 → Canvas
const app = new Application(800, 600, { renderer: video.AUTO });
// mandatory since 20.0 — the WebGPU device is acquired asynchronously
await app.init();
// Force one backend — app.init() rejects if it's unavailable (no substitution)
const app = new Application(800, 600, { renderer: video.WEBGPU });
const app = new Application(800, 600, { renderer: video.WEBGL });
// Force Canvas
const app = new Application(800, 600, { renderer: video.CANVAS });The renderer is accessed via app.renderer and provides the full API listed above regardless of which backend is active. Code that needs to know what it got should read the capability flags rather than sniff types:
| Flag | Canvas | WebGL | WebGPU |
|---|---|---|---|
renderer.type |
"CANVAS" |
"WebGL2" |
"WebGPU" |
renderer.shaderLanguage |
null |
"glsl" |
"wgsl" |
renderer.supportsDepthBuffer (Camera3d / 3D meshes) |
false |
true |
true |
renderer.supportsRetainedMesh (GPU-resident mesh geometry) |
false |
true |
true |
renderer.supportsShaderTileLayers (GPU tilemap path) |
false |
true |
true |
melonJS uses an internal Path2D class to build and tessellate 2D paths for the WebGL renderer. On Canvas, path methods (moveTo, lineTo, bezierCurveTo, etc.) are direct pass-throughs to the native context. On WebGL, they are routed through Path2D which tessellates curves into line segments for the primitive batcher.
Path2D also supports SVG path strings for defining shapes:
import Path2D from "melonjs";
// a heart shape using arcs and quadratic curves
const heart = new Path2D(
"M 10 30 A 20 20 0 0 1 50 30 A 20 20 0 0 1 90 30 Q 90 60 50 90 Q 10 60 10 30 Z"
);Supported SVG commands: M (moveTo), L (lineTo), H (horizontal line), V (vertical line), Q (quadratic Bezier), C (cubic Bezier), A (arc), Z (close path).
To draw custom graphics, override the draw method of a Renderable:
import { Renderable } from "melonjs";
class MyGraphics extends Renderable {
constructor() {
super(0, 0, 200, 200);
this.anchorPoint.set(0, 0);
}
draw(renderer) {
// sky gradient
const sky = renderer.createLinearGradient(0, 0, 0, 100);
sky.addColorStop(0, "#1a1a6e");
sky.addColorStop(1, "#FF6B35");
renderer.setColor(sky);
renderer.fillRect(0, 0, 200, 100);
// dashed horizon line
renderer.setLineDash([8, 4]);
renderer.setColor("#FFFFFF");
renderer.strokeLine(0, 100, 200, 100);
renderer.setLineDash([]);
// bezier curve hill
renderer.beginPath();
renderer.setColor("#2d5016");
renderer.moveTo(0, 150);
renderer.bezierCurveTo(50, 80, 150, 80, 200, 150);
renderer.lineTo(200, 200);
renderer.lineTo(0, 200);
renderer.fill();
}
}melonJS renders textured 3D triangle meshes, loaded from Wavefront OBJ files or created from raw geometry data. Meshes are built for the GPU backends, WebGPU and WebGL 2: hardware depth testing, lighting, the full material set and Camera3d. The Canvas renderer still draws a mesh under a 2D camera, as a last-resort fallback for a device with no GPU backend, not as a target (see Canvas below).
await app.init();
if (!app.renderer.supportsDepthBuffer) {
// the Canvas fallback: 2D-camera meshes still draw, CPU-projected and
// unlit; a Camera3d scene cannot, so tell the player instead
}- 3D Mesh — rotating 3D objects (cube, sphere, teapot) with perspective projection over a 2D background
import { loader, Mesh } from "melonjs";
// preload the OBJ model and its texture
loader.preload([
{ name: "myModel", type: "obj", src: "models/cube.obj" },
{ name: "myModel", type: "image", src: "models/texture.png" },
], () => {
const mesh = new Mesh(400, 300, {
model: "myModel",
texture: "myModel",
width: 200,
height: 200,
});
app.world.addChild(mesh);
});const mesh = new Mesh(400, 300, {
vertices: new Float32Array([...]), // x, y, z triplets
uvs: new Float32Array([...]), // u, v pairs
indices: new Uint16Array([...]), // triangle indices
texture: myTextureAtlas,
width: 200,
height: 200,
});The Mesh class extends Renderable and supports all standard transform methods, plus 3D rotation and translation:
import { Vector3d } from "melonjs";
// 2D rotation (Z axis, same as Sprite)
mesh.rotate(Math.PI / 4);
// 3D rotation around any axis
mesh.rotate(Math.PI / 4, new Vector3d(0, 1, 0)); // Y axis
mesh.rotate(0.5, new Vector3d(1, 0, 0)); // X axis
// scale (z defaults to 1, preserving depth)
mesh.scale(2, 2);
// translate in 3D
mesh.translate(10, 20, 5);
// all Renderable properties work
mesh.setOpacity(0.8);
mesh.tint.setColor(128, 196, 255);
mesh.flipX(true);Each Mesh has a built-in projectionMatrix that defaults to a perspective projection. Objects farther from the camera appear smaller:
// customize the projection (optional — default works for most cases)
mesh.projectionMatrix.identity();
mesh.projectionMatrix.perspective(
Math.PI / 4, // 45° field of view
1, // aspect ratio
0.1, // near plane
10, // far plane
);
mesh.projectionMatrix.translate(0, 0, -3); // camera distanceEnabled by default. Triangles facing away from the camera are not rendered:
mesh.cullBackFaces = true; // default
mesh.cullBackFaces = false; // render both sidesThe low-level drawMesh(mesh, modelMatrix?) method is available on every renderer:
| melonJS | Description |
|---|---|
drawMesh(mesh) |
Draw a textured triangle mesh from CPU-projected vertices (the 2D-camera path) |
drawMesh(mesh, modelMatrix) |
GPU backends: draw the mesh from retained GPU-resident geometry, placed by the matrix — redrawing never re-uploads vertices (renderer.supportsRetainedMesh) |
GPU backends (WebGL / WebGPU): Hardware depth buffer for correct Z-ordering, GPU backface culling, and batched indexed drawing. Large CPU-projected meshes are automatically chunked to fit buffer limits; retained meshes draw whole in one call. Mesh.draw picks the right form automatically — see Working in 3D → Retained rendering.
Canvas (a last-resort fallback, 2D camera only): uses the painter's algorithm (back-to-front triangle sorting), per-triangle affine texture mapping with clip paths, and winding-order backface culling. The texture is multiplied by each triangle's MTL color, and a triangle whose UVs collapse to a line (a palette model, such as the Kenney kits) is filled with the texels along that line, as the GPU interpolates them (both since 20.14). Best suited for convex shapes; concave or self-overlapping geometry may show slivers of the wrong triangle, large faces are mapped without perspective correction, and the cost grows with the triangle count. Canvas has no lighting, per-material textures, texture wrap, textureFilter, alphaCutoff or emissive.
The OBJ parser supports:
-
v— vertex positions (x, y, z) -
vt— texture coordinates (u, v) -
f— faces inv,v/vt,v//vnorv/vt/vnformat - Quad and n-gon triangulation (fan from first vertex)
- Automatic CW → CCW winding correction via signed volume test
Normals (vn) are parsed and used by the lighting path (mesh.lit + Light3d); when absent they are generated smooth (angle-weighted per position, ignoring s groups), so author vn for hard edges. The mtllib reference is extracted and stored with the parsed data.
melonJS supports Wavefront MTL material files for automatic texture and color assignment:
import { loader, Mesh } from "melonjs";
// preload the OBJ and its MTL: the MTL's map_Kd textures load with it,
// resolved next to the .mtl file
loader.preload([
{ name: "fox", type: "obj", src: "models/fox.obj" },
{ name: "fox", type: "mtl", src: "models/fox.mtl" },
], () => {
// texture(s), colors and opacity come from the MTL
const mesh = new Mesh(400, 300, {
model: "fox",
material: "fox",
width: 200,
height: 200,
});
app.world.addChild(mesh);
});Passing texture: as well overrides the material: that one texture is drawn over the whole model, and per-material textures are turned off.
// one texture for the whole model, whatever the MTL says
const winterFox = new Mesh(400, 300, {
model: "fox",
material: "fox",
texture: "fox-winter",
width: 200,
height: 200,
});Supported MTL properties:
-
newmtl— material name -
Kd— diffuse color: the mesh tint on a single-material model, baked per vertex on a multi-material one -
d/Tr— opacity / transparency (fades through the transparent pass on the GPU backends underCamera3d) -
map_Kd— diffuse texture, resolved relative to the MTL file and loaded with it. Each material's own texture is bound for its slice on the GPU backends, one draw per distinct texture -
map_bump/map_Bump/bump/norm— tangent-space normal map, per material (lit meshes underCamera3d, GPU backends) -
Ks+Ns— specular color and exponent (Blinn-Phong);Ns 0means no highlight -
Pr/Pm— PBR roughness / metalness, approximated as specular when there is noKs/Ns -
Ke— emissive color (applied asMesh.emissive— self-illumination) -
map_d— alpha map, per-texel opacity combined with analphaCutoffyou set -
Kaandillum— read onto the material, not used for shading;Niis accepted and ignored - Map options (
-bm,-s, …) are skipped; the file name is what follows them -
Multiple materials per mesh (
usemtlgroups) — each group'sKdis baked into a per-vertex color buffer, and the draw splits only where the texture changes (see the Multi-Material Mesh example)
Ke, Ks/Ns, Pr/Pm and map_d are read for single-material models only.
Limitations:
- The Canvas fallback draws one texture over the whole model (the first
map_Kd), with no lighting, normal map, specular or alpha map - Unsupported, with a console warning for each line the parser meets:
map_Ka,map_Ke,map_Ks,map_Ns,map_refl/refl,disp,map_Pr,map_Pm; any other unknown keyword warns too
- 3D Mesh — rotating textured 3D objects (cube, sphere, teapot) loaded from OBJ files
- 3D Material — Kenney cube pet models with MTL material support