Skip to content
Back to search

melonjs

MarketplaceWorks with Claude CodeGitHub

Skills for building games with melonJS, the open source 2D, 2.5D and 3D HTML5 game engine.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 13 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/melonjs/melonJS with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/melonjs/melonJS'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/melonjs--melonjs/badge.svg)](/listings/melonjs--melonjs)

HTML

<a href="/listings/melonjs--melonjs"><img src="/api/listings/melonjs--melonjs/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The fastest way to create a new game:

npm create melonjs my-game cd my-game npm install npm run dev

This scaffolds a ready-to-run project with TypeScript, Vite, and the debug plugin. It also works with plain JavaScript — just rename `.ts` files to `.js`.

You can also start from the [boilerplate](https://github.com/melonjs/typescript-boilerplate) directly, or follow the step-by-step [Platformer Tutorial](https://melonjs.org/tutorial/).

For more details, check the wiki [Details & Usage](https://github.com/melonjs/melonJS/wiki#details--usage) guide.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines
  1. {
  2. "name": "melonjs",
  3. "description": "Skills for building games with melonJS, the open source 2D, 2.5D and 3D HTML5 game engine.",
  4. "owner": { "name": "melonJS", "url": "https://melonjs.org" },
  5. "plugins": [
  6. {
  7. "name": "melonjs",
  8. "source": "./",
  9. "description": "Build games with melonJS — 26 guides to the 2D, 2.5D and 3D HTML5 game engine, its conventions and idioms, so generated code runs the first time."
  10. }
  11. ]
  12. }
README.md · README · 437 lines
  1. melonJS 2
  2. =========
  3. ![melonJS: fast & light 2D & 3D games for the web, running on WebGPU, WebGL 2 or Canvas](https://github.com/melonjs/melonJS/raw/master/media/readme/hero.webp)
  4. [![Build Status](https://github.com/melonjs/melonJS/actions/workflows/main.yml/badge.svg)](https://github.com/melonjs/melonJS/actions/workflows/main.yml)
  5. [![NPM Package](https://img.shields.io/npm/v/melonjs)](https://www.npmjs.com/package/melonjs)
  6. [![NPM Downloads](https://img.shields.io/npm/dm/melonjs)](https://www.npmjs.com/package/melonjs)
  7. [![Build Size](https://img.shields.io/bundlejs/size/melonjs?label=minzip)](https://bundlejs.com/?q=melonjs)
  8. [![jsDelivr](https://data.jsdelivr.com/v1/package/npm/melonjs/badge?style=rounded)](https://www.jsdelivr.com/package/npm/melonjs)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
  10. [![Discord](https://img.shields.io/discord/608636676461428758?color=7289da&label=discord)](https://discord.gg/aur7JMk)
  11. [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
  12. A modern & fully featured HTML5 game engine
  13. -------------------------------------------------------------------------------
  14. [melonJS](https://melonjs.org/) is an open-source 2D & 3D game engine designed for indie developers — perspective and orthogonal cameras, GPU-accelerated tilemap rendering, post-processing effects, custom shaders, 3D mesh support, polygon-accurate physics, modern Tiled workflows, and high performance. Runs on WebGPU, WebGL 2 or Canvas2D with automatic fallback. The whole engine is ~250 KB minzipped of vanilla JS/TS, with no dependencies and no toolchain lock-in. Built with modern class syntax and bundled with [esbuild](https://esbuild.github.io).
  15. [melonJS](https://melonjs.org/) is licensed under the [MIT License](LICENSE.md) and actively maintained by the team at AltByte in Singapore.
  16. Why melonJS
  17. -------------------------------------------------------------------------------
  18. melonJS is designed so you can **focus on making games, not on graphics plumbing**.
  19. - **[Canvas2D-inspired rendering API](https://github.com/melonjs/melonJS/wiki/Rendering-API)** — If you've used the HTML5 Canvas, you already know melonJS. The rendering API (`save`, `restore`, `translate`, `rotate`, `setColor`, `fillRect`, ...) follows the same familiar patterns — no render graphs, no shader pipelines, no instruction sets to learn.
  20. - **True renderer abstraction** — Write your game once, run it on WebGPU, WebGL 2 or Canvas2D with zero code changes. The engine handles all GPU complexity behind a unified API: the default `AUTO` mode tries WebGPU first at startup, falls back to WebGL 2 if that is unavailable, and ultimately to Canvas, and the entire feature set renders identically on both GPU backends.
  21. - **Complete engine, minimal footprint** — Physics, tilemaps, audio, input, cameras, tweens, particles, UI — a full game stack in a single tree-shakeable ES module. No dependency sprawl, no library stitching.
  22. - **Scenes, loaded in one call** — `level.load(name)` brings an authored scene straight into your world. [Tiled](https://www.mapeditor.org) is a first-class citizen for **2D** — orthogonal, isometric, hexagonal & staggered maps, animated tilesets, collision shapes, object properties, compressed formats, with GPU-accelerated tile rendering on the GPU backends — and **glTF / GLB** is the equivalent for **3D scenes**: author in Blender (or any DCC tool), export a `.glb`, and the whole scene — meshes, materials, cameras, lights, and node animation — loads under a `Camera3d`, no per-mesh wiring. Animated models play back through the same animation API as a 2D `Sprite`.
  23. - **Batteries included, hackable by design** — Get started in minutes with minimal setup. When you need to go deeper: modern class-based architecture, a plugin system for engine extensions, and a clean architecture that's easy to extend without fighting the framework.
  24. About melonJS
  25. -------------------------------------------------------------------------------
  26. [melonJS](https://melonjs.org/) is a fully featured game engine :
  27. Compatibility
  28. - Standalone library (does not rely on anything else, except a HTML5 capable browser)
  29. - Compatible with all major browsers (Chrome, Safari, Firefox, Opera, Edge) and mobile devices
  30. Graphics
  31. - Fast GPU renderers (WebGPU and WebGL 2) for desktop and mobile devices, with fallback to Canvas rendering
  32. - Since 20.0 the aging WebGL 1 path is retired and WebGL 2 is the baseline; devices offering only WebGL 1 fall back to the Canvas renderer under `AUTO`
  33. - 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)
  34. - High DPI resolution & Canvas advanced auto scaling
  35. - Sprite with 9-slice scaling option and frame animation (with per-frame callbacks)
  36. - `Sprite3d` billboards, turning to face a `Camera3d` (cylindrical or spherical), for 2.5D characters and props
  37. - 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) — supported identically on WebGPU, WebGL 2 and Canvas since 20.2, except `none`, which Canvas cannot do and draws as `normal`
  38. - Standard spritesheet, single and multiple Packed Textures support
  39. - Compressed texture support (DDS, KTX, KTX2, PVR, PKM) with automatic format detection and fallback
  40. - 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
  41. - Procedural noise textures: `Noise` (simplex/perlin/value/cellular, fBm / ridged / ping-pong fractal, domain warp; renderer-free and CPU-samplable for heightmaps, terrain, and spawn jitter) and `NoiseTexture2d` — bake a noise field into a sprite image, a `Gradient` color ramp, or a live-animated tangent-space normal map for lit water and surfaces; unified under a new `Texture2d` base alongside `TextureAtlas`
  42. - 3D mesh rendering with OBJ/MTL model loading, multi-material support, hardware depth testing, and perspective projection via `Camera3d` — retained-mode geometry, uploaded to the GPU once and re-drawn from there, so moving, rotating, scaling or re-tinting a mesh costs no vertex upload and no per-vertex CPU work at all. 3D is built for the GPU backends; the Canvas fallback still draws a mesh under a 2D camera, as a last resort
  43. - Mipmapped and anisotropically-filtered mesh textures on both GPU backends, so distant and grazing-angle geometry stops shimmering (opt out per mesh with `textureFilter: "nearest"` for crisp pixel-art models)
  44. - Crisp or smooth, application-wide: `textureFilter` (`"nearest"`, `"linear"`, or `"linear-mipmap"`, which mipmaps sprites, text and tile layers too), and integer scaling with letterboxing (`scaleRounding: "integer"`) for pixel art
  45. - 3D mesh materials: tangent-space normal maps, specular, emissive, alpha cutout, per-vertex colors, and a back-to-front transparent pass for glass and additive glows; GPU instancing draws one mesh many times in one call (`InstancedMesh`, and glTF `EXT_mesh_gpu_instancing`)
  46. - Lighting, in 2D and 3D:
  47. - **2D** — `Light2d` as a first-class `Renderable` (multiple dynamic lights, radial-gradient falloff, adjustable edge `softness`, illumination-only mode, procedural rendering via `drawLight`), plus optional per-pixel normal-map shading and specular highlights (`shininess`) on sprites for 3D-looking dynamic lights
  48. - **3D** — `Light3d` directional, point, spot and ambient lights, added to the world like `Light2d` (half-Lambert diffuse + ambient fill, quadratic falloff and cone angles on the punctual types, runtime-manipulable for day/night), auto-loaded from a glTF scene's authored suns and lamps
  49. - up to **32 simultaneous lights** on either path, with light data travelling in a uniform buffer — a static light rig costs zero GPU state changes per frame
  50. - Ground ("blob") shadows for 3D objects — **on by default** — so characters and props read as standing on the floor instead of hovering. An ellipse matching the caster's own footprint and rotation, shrinking and fading with height above the ground; one extra draw per object, and **one for an entire `InstancedMesh` scatter regardless of instance count**. Shaped by the light rather than always straight down: `shadowLight` points a blob at a `Light3d` and is re-read every draw, so a day/night cycle carries every shadow with it, while `shadowOffset` slides it out from the caster's feet, `shadowStretch` lengthens it for a low sun, `shadowScale` sizes it independently of the object, `shadowGroundNormal` lays it on a floor that is not level, and `shadowGroundPoint` on ground that is not flat at all, such as a planet. All of them work on an `InstancedMesh` too, as one value for the whole set. Controllable per object, per glTF scene (`level.load(name, { castGroundShadow, shadowLight, … })`) or application-wide. Deliberately not shadow mapping: it answers "where is this standing", which is what a 2.5D scene needs
  51. - Built-in shader effects (Flash, Outline, Glow, Bloom, ToneMapping, Dissolve, CRT, Hologram, Shine, Vignette, Squish, Sway, etc.) with multi-pass chaining via `addPostEffect()`, on sprites, cameras and meshes alike, plus custom shader support on both GPU backends: `ShaderEffect` for per-sprite fragment effects (GLSL and/or WGSL bodies) and complete custom mesh shader programs via `mesh.shader` (a dual-language `GLShader`: GLSL pair and/or WGSL module)
  52. - Optional HDR rendering (`hdr: true`) — the camera's render targets become half-float, so additive light stops saturating on every write and `BloomEffect` thresholds on genuinely over-bright pixels instead of merely bright ones, with `ToneMappingEffect` and a `toneMapping` setting to compress the result back into display range when your art calls for it. Off by default and additive: nothing is inserted into your effect chain, so turning it on does not restyle a game whose look is built on clipped whites. On WebGPU it goes one step further — `hdrOutput: true` presents the frame in the display's own dynamic range rather than clamping it to SDR at the last step
  53. - Screen-space effects (refraction, heat haze, water): `renderer.toFrameTexture()` captures the frame for a `ShaderEffect` to sample, through the `screen_texture` / `screen_uv` built-ins
  54. - Shaders preloaded like any other asset, and the built-in shader programs compiled behind the loading screen (`prewarm`), so the first frame of an effect does not stall
  55. - `Trail` and `Trail3d` renderables for fading, tapering ribbons behind moving objects (speed lines, sword slashes, magic trails)
  56. - System & Bitmap Text with built-in typewriter effect, per-glyph wave, shake and color effects on `BitmapText` (`glyphEffect`), gradient fills, and outline order and corner joins
  57. - Vector drawing through `Path2D`, from SVG path strings, with holes and compound fills
  58. - Automatic depth sorting by y or x that stays right as things move (`autoSort`), with a per-renderable `sortOffset`
  59. - Video sprite playback
  60. Sound
  61. - Web Audio support with 3D spatial audio and stereo panning, plus a procedural tone/noise API. Sounds can be placed in the world or follow a renderable, heard from a listener that tracks the camera or the player (`audio.play(name, { follow })`, `audio.setListener()`). The playback backend began as [howler.js](https://howlerjs.com) and is now a customized derivative vendored into the engine, so this is **not** a runtime dependency (see `src/audio/backend/LICENSE`)
  62. - Audio sprites: named regions of one file, played as sounds or looped as a track region
  63. - Built-in procedural audio primitives (envelope-shaped oscillators, white/pink/brown noise) for SFX without sample assets
  64. - Direct `AudioContext` / master-gain accessors for custom WebAudio graphs that mix with the engine's master volume / mute
  65. Physics
  66. - Polygon (SAT) based collision algorithm for accurate detection and response
  67. - Fast broad-phase collision detection using spatial partitioning (QuadTree in 2D, Octree in 3D, swapped automatically)
  68. - Raycast, AABB and sphere region queries with precise entry geometry, including 3D raycasts (`raycast3d`)
  69. - Collision lifecycle hooks on every `Renderable`
  70. - Collision filtering for optimized automatic collision detection
  71. - Multiple shapes per body, each with its own collision type, mask and trigger flag, and per-shape contact events (`onShapeCollisionStart`, …): a hitbox and a hurtbox on one body
  72. - Sensor bodies, which report contacts without pushing anything (`isSensor`)
  73. - 3D collision shapes (`Box3d`, `Sphere`) that push back along Z, for 2.5D
  74. - Collision shapes exported from PhysicsEditor, named in a `bodyDef` and loaded on every adapter
  75. - Pluggable `PhysicsAdapter` interface, with three official rigid-body adapters: [matter](https://github.com/melonjs/melonJS/tree/master/packages/matter-adapter), [planck (Box2D)](https://github.com/melonjs/melonJS/tree/master/packages/planck-adapter) and [Rapier](https://github.com/melonjs/melonJS/tree/master/packages/rapier2d-adapter), switchable while the game runs with `world.setAdapter()` (see [Physics Adapters](#physics-adapters))
  76. - Hinge, rope, weld and slider joints with `world.addJoint()`, the same on the planck and Rapier adapters and kept across `world.setAdapter()`
  77. Input
  78. - Mouse and Touch device support (with mouse emulation)
  79. - Gamepad support with button and axes binding, vibration, and active-pad detection
  80. - Keyboard event handling with key binding system
  81. - Device motion & accelerometer support
  82. Camera
  83. - Multi-camera support (split-screen, minimaps, multiple viewports)
  84. - Optional perspective camera (`Camera3d`) with frustum culling for 2.5D / 3D-projected scenes — drop-in subclass of the default 2D camera — with distance fog (linear or exp2, with height falloff), roll, and `worldToScreen()` to pin HUD elements to 3D points
  85. - Per-camera visibility layers (`visibilityLayer`, `cullMask`): a minimap without particles, a light shown in one camera only
  86. - Camera follow with configurable deadzone and frame-rate-independent damping
  87. - Built-in camera shake, fade and flash, and screen transitions: a fade, a mask in any shape, and a pixelate (WebGL and WebGPU); custom effects through `CameraEffect`
  88. - Per-camera post-processing pipeline with stackable shader effects and color grading (ColorMatrix)
  89. UI
  90. - `UIBaseElement` / `UISpriteElement` containers for clickable, hoverable and holdable elements with full pointer-event wiring
  91. - `Draggable` / `DropTarget` for drag-and-drop with configurable overlap or contains-check
  92. - `UITextButton` text button with hover, press, key-bind and `onClick` support, a nine-slice `skin`, on a `Text` or `BitmapText` label
  93. - `UIPanel` that lays out its children in a column, a row or a grid, scrolls them, and takes a nine-slice skin, a title and a drop shadow, and can be dragged
  94. - `UICheckbox` (a radio button with a `group`), `UISlider`, and `ProgressBar`
  95. - Keyboard and gamepad navigation between widgets, `enabled` states, and a hover and press bounce
  96. Scenes
  97. - Load a scene in one call with `level.load(name)` — 2D Tiled maps and 3D glTF scenes alike, auto-registered on preload
  98. - [Tiled](https://www.mapeditor.org) map format [up to 1.12](https://doc.mapeditor.org/en/stable/reference/tmx-changelog/) built-in support for easy level design
  99. - **GPU-accelerated tile rendering** for orthogonal maps on the GPU backends (WebGL 2 and WebGPU) — each layer draws as a single quad with no per-tile loop, ~5–8× faster than the legacy CPU renderer on dense maps. Honors animated tiles, flip bits, per-layer opacity/tint/blend, and oversized bottom-aligned tiles; falls back transparently to the CPU renderer on isometric/staggered/hexagonal layers or under the Canvas renderer
  100. - Uncompressed and [compressed](https://github.com/melonjs/melonJS/tree/master/packages/tiled-inflate-plugin) Plain, Base64, CSV and JSON encoded XML tilemap loading
  101. - Orthogonal, Isometric, Hexagonal (both normal and staggered) and Oblique maps
  102. - Multiple layers with per-layer alpha, tinting and blend modes (multiple background/foreground, collision and Image layers)
  103. - Parallax scrolling via Image layers, with parallax origin support
  104. - Animated and multiple Tileset support, tile sub-rectangles, embedded base64 images
  105. - Native `.aseprite` / `.ase` tileset images (Tiled 1.11+ qaseprite plugin workflow), with frame tags auto-mapped to per-tile animations — no PNG export step required
  106. - Tileset transparency settings
  107. - Rectangle, Ellipse, Polygon, Polyline and Capsule (round-rect) object shapes
  108. - Tiled Objects with custom properties (string, number, boolean, color, file, object, list/array and class-typed)
  109. - Per-object opacity and visibility
  110. - Concave collision polygons auto-decomposed via earcut triangulation
  111. - Flipped & rotated Tiles
  112. - Dynamic Layer and Object/Group ordering
  113. - Dynamic Entity loading via an extensible object factory registry — register custom handlers for any Tiled class name without modifying engine code
  114. - Tile objects take the class set on their tile in the tileset, and inherit its properties
  115. - Shape based Tile collision support
  116. - glTF / GLB 3D scenes — load an authored 3D scene with `level.load(...)`, the same one call as a Tiled map
  117. - The whole scene loads at once — meshes, materials, cameras and lights — viewed under a `Camera3d`
  118. - Automatically lit by the scene's authored lights — the sun plus any point/spot lamps set up in the authoring tool, each keeping its authored name so `getChildByName("Sun")` finds it for runtime tuning
  119. - Textured, solid-colored, and vertex-colored materials
  120. - Node animation — walk/idle/sprint characters, spinning pickups, doors, lifts — played through the same `setCurrentAnimation` / `play` / `pause` / `stop` API as a 2D `Sprite`
  121. - `.glb` and `.gltf` files, with embedded *or* external buffers & textures
  122. - Works with any glTF authoring tool (Blender, Maya, 3ds Max, Cinema 4D, …)
  123. Assets
  124. - Asynchronous asset loading with progress tracking, awaitable (`await loader.preload(...)`), and asynchronous `level.load`
  125. - Asset bundles, loaded and freed together: `loader.preload({ common: [...], level1: [...] })`, then `loader.load("level1")` / `loader.unload("level1")`; an asset shared by several bundles is fetched once
  126. - A fully customizable preloader
  127. - Support for images, JSON, TMX/TSX, glTF / GLB 3D scenes, OBJ / MTL models, shaders, `.aseprite` / `.ase` binary, audio, video, JavaScript, binary and fonts, and custom types through `loader.setParser()`
  128. Core
  129. - `Application` class as the modern entry point — construct it, then `await app.init()` (asynchronous since 20.0, so the WebGPU device can be acquired) — with built-in pause, resume, and `freeze()` (hit-stop) primitives
  130. - A state manager (to easily manage loading, menu, options, in-game state)
  131. - Tween effects with multiple easing functions (Quadratic, Cubic, Elastic, Bounce, etc.) and Bezier/Catmull-Rom interpolation
  132. - Screen transitions between states: `state.transition("fade" | "mask" | "pixelate")`
  133. - Steady motion on 60 and 120 Hz displays (`syncToDisplay`), and fullscreen (`app.requestFullscreen()`)
  134. - Pooling support for object recycling, with typed pools (`createPool()`)
  135. - Particle system with `ParticleEmitter` (emission rate, lifetime, velocity, gravity, blend modes, sprite-sheet frames, tint over life, 3D emission in a cone or a volume, removal once finished), 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, and a [Particle Editor](https://melonjs.github.io/melonJS/examples/#/particle-editor) to tune effects live and copy the code
  136. - EventEmitter based event system
  137. - Persistent data storage (save/load via localStorage)
  138. - Plugin system for extending engine capabilities
  139. Tools integration
  140. -------------------------------------------------------------------------------
  141. melonJS is supporting the below tools and frameworks natively or through our official plugin(s) :
  142. [![Free Texture Packer](https://user-images.githubusercontent.com/4033090/136762061-1d3a0dfe-dbe0-4d3d-808d-47a49ecf5309.png "Free Texture Packer")](http://free-tex-packer.com)
  143. [![TexturePacker](https://github.com/melonjs/melonJS/raw/master/media/icons/texturepacker.svg "TexturePacker")](https://www.codeandweb.com/texturepacker)
  144. [![SpriteIlluminator](https://github.com/melonjs/melonJS/raw/master/media/icons/spriteilluminator.svg "SpriteIlluminator")](https://www.codeandweb.com/spriteilluminator)
  145. [![PhysicsEditor](https://github.com/melonjs/melonJS/raw/master/media/icons/physicseditor.svg "PhysicsEditor")](https://www.codeandweb.com/physicseditor)
  146. [![ShoeBox](https://user-images.githubusercontent.com/4033090/136762705-92027d94-d87c-4a95-b051-26647410248d.png "ShoeBox")](https://renderhjs.net/shoebox/)
  147. [![Tiled](https://user-images.githubusercontent.com/4033090/136762999-5a7f377b-4136-4205-9fe0-83728c90cb9b.png "Tiled")](https://www.mapeditor.org)
  148. [![Cordova](https://user-images.githubusercontent.com/4033090/136763147-6d157ce6-6921-437e-bb8f-0287b86109da.png "Cordova")](https://cordova.apache.org)
  149. [![Capacitor](https://github.com/melonjs/melonJS/raw/master/media/icons/capacitor.svg "Capacitor")](https://capacitorjs.com)
  150. [![Spine](https://github.com/melonjs/melonJS/assets/4033090/7a8d81b8-bc80-47bd-80dc-d9a054c78c96 "Spine")](http://esotericsoftware.com)
  151. [![aseprite](https://github.com/melonjs/melonJS/assets/4033090/65d19fef-2eba-461a-b925-cc2ad3bb270c "aseprite")](https://www.aseprite.org)
  152. Tools integration and usage with melonJS is documented in our [Wiki](https://github.com/melonjs/melonJS/wiki#third-party-tools-usage).
  153. Getting Started
  154. -------------------------------------------------------------------------------
  155. The fastest way to create a new game:
  156. npm create melonjs my-game
  157. cd my-game
  158. npm install
  159. npm run dev
  160. This scaffolds a ready-to-run project with TypeScript, Vite, and the debug plugin. It also works with plain JavaScript — just rename `.ts` files to `.js`.
  161. You can also start from the [boilerplate](https://github.com/melonjs/typescript-boilerplate) directly, or follow the step-by-step [Platformer Tutorial](https://melonjs.org/tutorial/).
  162. For more details, check the wiki [Details & Usage](https://github.com/melonjs/melonJS/wiki#details--usage) guide.
  163. Examples
  164. -------------------------------------------------------------------------------
  165. * [Platformer](https://melonjs.github.io/melonJS/examples/#/platformer) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/platformer))
  166. * [Isometric Dungeon](https://melonjs.github.io/melonJS/examples/#/isometric-dungeon) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/isometricDungeon))
  167. * [SVG Shapes](https://melonjs.github.io/melonJS/examples/#/svg-shapes) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/svgShapes))
  168. * [Particle Editor](https://melonjs.github.io/melonJS/examples/#/particle-editor) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/particleEditor)) — tune a `ParticleEmitter` live in 2D or 3D, from presets or a random roll, and copy the matching code or JSON
  169. * [Graphics](https://melonjs.github.io/melonJS/examples/#/graphics) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/graphics))
  170. * [Hello World](https://melonjs.github.io/melonJS/examples/#/hello-world) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/helloWorld))
  171. * [Hello WebGPU](https://melonjs.github.io/melonJS/examples/#/webgpu) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/webgpu)) — the WebGPU backend in action, with the renderer negotiation surfaced on screen
  172. * [Whac-A-Mole](https://melonjs.github.io/melonJS/examples/#/whac-a-mole) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/whac-a-mole))
  173. * [Compressed Textures](https://melonjs.github.io/melonJS/examples/#/compressed-textures) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/compressedTextures))
  174. * [Aquarium](https://melonjs.github.io/melonJS/examples/#/aquarium) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/aquarium)) — screen-space water refraction with `renderer.toFrameTexture()`: fish swim across a seabed, then a water surface captures the live frame on the GPU and re-samples it through a scrolling `NoiseTexture2d` flow map (the standard screen-texture / opaque-frame-copy pattern)
  175. * [Heat Haze](https://melonjs.github.io/melonJS/examples/#/heat-haze) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/heatHaze)) — `renderer.toFrameTexture()` over a lit scene: normal-mapped tiles under a moving `Light2d`, distorted by a rising heat-haze that captures and ripples the lit frame
  176. * [3D Mesh](https://melonjs.github.io/melonJS/examples/#/mesh-3d) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/mesh3d))
  177. * [3D Mesh Material](https://melonjs.github.io/melonJS/examples/#/mesh-3d-material) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/mesh3dMaterial))
  178. * [AfterBurner Clone](https://melonjs.github.io/melonJS/examples/#/after-burner) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/afterBurner)) — `Camera3d` + 3D Mesh arcade shooter
  179. * [Earth Defender](https://melonjs.github.io/melonJS/examples/#/earth-defender) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/earthDefender)) — a Stardust tribute: a `Camera3d` posed from the player's own surface point, blob shadows lying on a sphere through `shadowGroundPoint`, mesh-hosted `ShaderEffect` shields, spatial audio and HDR bloom
  180. * [Ground Shadows](https://melonjs.github.io/melonJS/examples/#/ground-shadows) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/groundShadows)) — every blob-shadow setting side by side under an orbiting sun, including blobs lying on a slope and a 70-instance scatter that costs one extra draw
  181. * [Jungle Rabbit](https://melonjs.github.io/melonJS/examples/#/jungle-rabbit) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/jungleRabbit)) — a low-poly river endless runner: Blender-modelled props through `InstancedMesh`, a rigged paddling boat, a procedural valley and shadows laid on its banks
  182. * [glTF Scene](https://melonjs.github.io/melonJS/examples/#/gltf) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/gltf)) — a Blender-authored, lit 3D scene loaded with `level.load`
  183. * [glTF Animated Model](https://melonjs.github.io/melonJS/examples/#/gltf-character) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/gltf)) — a rigged character (Kenney Blocky Characters) with node animation, driven by the Sprite-aligned `setCurrentAnimation` / `play` / `pause` / `stop` API
  184. * [Trail](https://melonjs.github.io/melonJS/examples/#/trail) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/trail))
  185. * [Shader Effects](https://melonjs.github.io/melonJS/examples/#/shader-effects) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/shaderEffects))
  186. * [Spine](https://melonjs.github.io/melonJS/examples/#/spine) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/spine))
  187. Browse all examples [here](https://melonjs.github.io/melonJS/examples/)
  188. -------------------------------------------------------------------------------
  189. ### Basic Hello World Example
  190. ```JavaScript
  191. import { Application, Text } from "https://cdn.jsdelivr.net/npm/melonjs/+esm";
  192. // create a new melonJS application
  193. const app = new Application(1218, 562, {
  194. parent: "screen",
  195. scale: "auto",
  196. backgroundColor: "#202020",
  197. });
  198. // initialize it (builds the renderer and appends the canvas)
  199. await app.init();
  200. // set a gray background color
  201. app.world.backgroundColor.parseCSS("#202020");
  202. // add a font text display object
  203. app.world.addChild(new Text(609, 281, {
  204. font: "Arial",
  205. size: 160,
  206. fillStyle: "#FFFFFF",
  207. textBaseline: "middle",
  208. textAlign: "center",
  209. text: "Hello World !",
  210. }));
  211. ```
  212. > Simple hello world using melonJS
  213. > **Note:** since version 20.0, `await app.init()` is **required** after constructing the `Application`. The WebGPU backend, which `AUTO` tries first on browsers that support it, acquires its GPU device asynchronously, so initialization had to become an async step; it resolves without suspending on the WebGL and Canvas backends. On 19.x the call is optional and this example works without it.
  214. Documentation
  215. -------------------------------------------------------------------------------
  216. * [Online API](https://melonjs.github.io/melonJS/)
  217. Plugins
  218. -------------------------------------------------------------------------------
  219. melonJS provides a plugin system allowing to extend the engine capabilities.
  220. Here is the list of official plugins maintained by the melonJS team:
  221. - [debug-plugin](https://github.com/melonjs/melonJS/tree/master/packages/debug-plugin) - a debug panel for inspecting game objects
  222. - [tiled-inflate-plugin](https://github.com/melonjs/melonJS/tree/master/packages/tiled-inflate-plugin) - enable loading and parsing of zlib, gzip and zstd compressed [Tiled](https://www.mapeditor.org/) maps
  223. - [spine-plugin](https://github.com/melonjs/melonJS/tree/master/packages/spine-plugin) - [Spine](http://esotericsoftware.com) runtime integration to render Spine skeletal animations, with a dedicated batcher on each renderer (WebGPU, WebGL and Canvas)
  224. - [gamepad-plugin](https://github.com/melonjs/melonJS/tree/master/packages/gamepad-plugin) - on-screen touch controls (sticks and buttons) reported as a gamepad, so the same bindings cover a real pad and a touch screen
  225. - [capacitor-plugin](https://github.com/melonjs/melonJS/tree/master/packages/capacitor-plugin) - bridges [Capacitor](https://capacitorjs.com/)'s native lifecycle (pause/resume, hardware back-button, orientation lock, splash) for melonJS games wrapped as iOS / Android apps
  226. If you wish to develop your own plugin, we also provide a [plugin template](https://github.com/melonjs/plugin-template) to help you get started.
  227. Physics Adapters
  228. -------------------------------------------------------------------------------
  229. Since 19.5, melonJS exposes a `PhysicsAdapter` interface so the same game code can run on either the built-in SAT physics (default) or a third-party rigid-body engine, selected via the `physic` option on `Application` (and switched later with `world.setAdapter()`). Every adapter is made the same way, with `await XAdapter.create(options)`. Three official adapter packages, maintained by the melonJS team:
  230. - **[@melonjs/matter-adapter](https://github.com/melonjs/melonJS/tree/master/packages/matter-adapter)** — [matter-js](https://brm.io/matter-js/) integration. Rotational dynamics, matter's own constraints (springs / hinges / pins, through `adapter.matter`; `world.addJoint()` needs planck or Rapier), sleeping bodies, raycasts. Showcased by the [Matter Platformer](https://melonjs.github.io/melonJS/examples/#/platformer-matter) and [Pool (Matter)](https://melonjs.github.io/melonJS/examples/#/pool-matter) examples.
  231. - **[@melonjs/planck-adapter](https://github.com/melonjs/melonJS/tree/master/packages/planck-adapter)** — [planck.js](https://piqnt.com/planck.js/) integration (faithful Box2D 2.3.0 port). Hinge, rope, weld and slider joints with `world.addJoint()` (and the rest of Box2D's through `adapter.planck`), CCD bullet flag, sleeping bodies, native raycasts, per-body gravity scale. Showcased by the [Neon Plinko (Planck)](https://melonjs.github.io/melonJS/examples/#/plinko-planck) example.
  232. - **[@melonjs/rapier2d-adapter](https://github.com/melonjs/melonJS/tree/master/packages/rapier2d-adapter)** — [Rapier](https://rapier.rs) 2D integration, compiled to WebAssembly. Many bodies at once, per-body continuous collision detection, hinge, rope, weld and slider joints with `world.addJoint()`, a character controller, native raycasts. Selectable in the [Physics Shapes](https://melonjs.github.io/melonJS/examples/#/physics-shapes) and [Line Collision](https://melonjs.github.io/melonJS/examples/#/line-collision) examples.
  233. Not sure which one fits your game? Stay on the built-in physics for platformers, top-down games, shoot-'em-ups and 2.5D with height; reach for an adapter when the game needs rotation that collides, stacking, joints or real friction. The [physics skill](https://github.com/melonjs/melonJS/blob/master/packages/melonjs/skills/melonjs-physics/SKILL.md#picking-one) has the table, game type by game type.
  234. See the [Migrating to the Physics Adapter API](https://github.com/melonjs/melonJS/wiki/Migrating-to-the-Physics-Adapter-API), [Switching Physics Adapters](https://github.com/melonjs/melonJS/wiki/Switching-Physics-Adapters), and [BuiltinAdapter Quirks](https://github.com/melonjs/melonJS/wiki/BuiltinAdapter-Quirks) wiki pages for migration guides and the per-adapter behaviour table.
  235. Installation
  236. -------------------------------------------------------------------------------
  237. melonJS is distributed as a tree-shakeable ES module with TypeScript declarations included.
  238. The published bundle targets **ES2022** — transpile it if you need to support older browsers.
  239. Install via [npm](https://www.npmjs.com/package/melonjs) :
  240. npm install melonjs
  241. Then import what you need in your project :
  242. ```JavaScript
  243. import { Application, Sprite, loader } from 'melonjs';
  244. ```
  245. Or use it directly via [jsDelivr](https://www.jsdelivr.com/package/npm/melonjs) CDN :
  246. ```html
  247. <!-- load the ES module bundle of melonJS v20.x -->
  248. <script type="module" src="https://cdn.jsdelivr.net/npm/melonjs@20/+esm"></script>
  249. <!-- omit the version completely to get the latest one -->
  250. <!-- you should NOT use this in production -->
  251. <script type="module" src="https://cdn.jsdelivr.net/npm/melonjs/+esm"></script>
  252. ```
  253. > Note: the debug plugin is available separately as [`@melonjs/debug-plugin`](https://www.npmjs.com/package/@melonjs/debug-plugin)
  254. ### Supporting older browsers
  255. The published bundle targets ES2022, so it uses private class members and other
  256. modern syntax. A browser that predates those cannot parse the file at all — this
  257. fails at load, not at the point a feature is used.
  258. To support older browsers, transpile melonJS **together with your own code**.
  259. The usual trap is that build setups skip `node_modules` by default, which leaves
  260. melonJS untouched no matter how low you set your target.
  261. With [Vite](https://vite.dev) :
  262. ```javascript
  263. // vite.config.js
  264. export default {
  265. build: {
  266. // esbuild downlevels dependencies too, melonjs included
  267. target: "es2020",
  268. },
  269. };
  270. ```
  271. With Babel, make sure melonJS is not excluded :
  272. ```javascript
  273. // webpack.config.js
  274. {
  275. test: /\.js$/,
  276. // the default `exclude: /node_modules/` would skip melonjs
  277. exclude: /node_modules\/(?!melonjs)/,
  278. use: "babel-loader",
  279. }
  280. ```
  281. Transpiling costs some size and speed: private class members become `WeakMap`
  282. lookups, which are on hot paths in the renderer. Only reach for it if you have
  283. users on browsers that need it.
  284. ### Running without a DOM (experimental)
  285. melonJS also runs where there is no `document` to put a canvas in: on
  286. [nx.js](https://github.com/TooTallNate/nx.js) (the Nintendo Switch homebrew
  287. framework), or rendering in a Web Worker. Hand the Application the canvas to
  288. draw to:
  289. ```javascript
  290. const app = new Application(1280, 720, {
  291. canvas: screen, // nx.js's display; an OffscreenCanvas in a worker
  292. renderer: video.AUTO,
  293. scale: 1,
  294. });
  295. await app.init();
  296. ```
  297. This is tested against a simulation of nx.js built from its source, not yet on
  298. Switch hardware. Some things differ there: Tiled maps must be JSON, sizing is
  299. fixed rather than fitted to a page, and a worker gets no input or sound of its
  300. own. The [platforms skill](https://github.com/melonjs/melonJS/blob/master/packages/melonjs/skills/melonjs-platforms/SKILL.md#runtimes-with-no-dom-nxjs-web-workers)
  301. lists them.
  302. Building with AI agents
  303. -------------------------------------------------------------------------------
  304. melonJS ships **skills** — guidance files that teach AI coding assistants the
  305. engine's conventions and, more usefully, the mistakes that fail silently rather
  306. than raising an error.
  307. They are versioned with the engine and ship inside the package, at
  308. `node_modules/melonjs/skills/` — so a copy matching the exact release you are
  309. running is always on disk.
  310. Install them into whatever assistant you use, with one command :
  311. ```bash
  312. npx skills add https://github.com/melonjs/melonJS/tree/master/packages/melonjs/skills
  313. ```
  314. It detects the assistants in your project and installs one copy of each skill
  315. under `.agents/skills/<skill-name>`, then symlinks that copy into every
  316. assistant's own directory, so `.claude/skills/melonjs` points back at
  317. `.agents/skills/melonjs` and there is nothing to place by hand. It reports the
  318. assistants it covers as it runs (77 of them at the time of writing). Add
  319. `-a claude-code -a cursor` to target specific ones.
  320. The set includes an `AGENTS.md` for anything following that convention (Codex,
  321. Cursor, Gemini CLI); GitHub Copilot reads the same content from
  322. `.github/copilot-instructions.md`. It names the three rules that produce code
  323. which runs and is wrong, and links the API index below — if you already keep an
  324. `AGENTS.md`, paste its sections into yours.
  325. The command installs from `master`. To pin to the release you are running,
  326. point it at that tag instead of `master` in the URL above.
  327. The skills are plain markdown and can be read by any agent, or by a human.
  328. For anything the skills do not cover, the complete API is indexed for agents at
  329. [llms.txt](https://melonjs.github.io/melonJS/llms.txt) — every exported class,
  330. function and type with a one-line summary and a link to its reference page,
  331. regenerated on every docs build.
  332. Community
  333. -------------------------------------------------------------------------------
  334. Join us and get help or share your projects :
  335. - [Discord](https://discord.gg/aur7JMk)
  336. - [Wiki](https://github.com/melonjs/melonJS/wiki)
  337. - [FAQ](https://github.com/melonjs/melonJS/wiki/FAQ)
  338. Contributing
  339. -------------------------------------------------------------------------------
  340. We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting changes or new features.
  341. <a href = "https://github.com/melonjs/melonJS/graphs/contributors">
  342. <img src = "https://contrib.rocks/image?repo=melonJS/melonjs"/>
  343. </a>
  344. Sponsors
  345. -------------------------------------------------------------------------------
  346. Support the development of melonJS by [becoming a sponsor](https://github.com/sponsors/melonjs). Get your logo in our README with a link to your site or become a backer and get your name in the [BACKERS](BACKERS.md) list. Any level of support is really appreciated and goes a long way !
  347. [![Melon Gaming](https://user-images.githubusercontent.com/4033090/136695857-d098c27d-f4b2-4c71-8574-b5f4291779cb.png "Melon Gaming")](https://www.melongaming.com)
  348. [![Altbyte Pte Ltd](https://user-images.githubusercontent.com/4033090/136692693-35dca8aa-5012-4a37-9ea2-51640d2e6d73.png "AltByte")](https://www.altbyte.com)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.