melonjs 9.1.0 → 10.0.1

package/README.md

@@ -1,46 +1,55 @@
-melonJS
-=======
+melonJS 2
+=========
 [![Build Status](https://travis-ci.org/melonjs/melonJS.svg)](https://travis-ci.org/melonjs/melonJS)
 [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/melonjs/melonJS.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/melonjs/melonJS/context:javascript)
 [![Build Size](https://badgen.net/bundlephobia/min/melonjs)](https://bundlephobia.com/result?p=melonjs)
 [![Dependencies](https://img.shields.io/david/melonjs/melonJS.svg)](https://david-dm.org/melonjs/melonJS)
-[![jsDeliver](https://data.jsdelivr.com/v1/package/npm/melonjs/badge)](https://www.jsdelivr.com/package/npm/melonjs)
+[![NPM Package](https://img.shields.io/npm/v/melonjs)](https://www.npmjs.com/package/melonjs)
 [![Boss Bounty Badge](https://img.shields.io/endpoint.svg?url=https://api.boss.dev/badge/enabled/melonjs/melonJS)](https://www.boss.dev/issues/repo/melonjs/melonJS)
 
 
-A fresh & lightweight HTML5 game engine
+A fresh, _modern_ & lightweight HTML5 game engine
 -------------------------------------------------------------------------------
 ![melonJS](http://melonjs.org/media/alex4-github.png)
 
-Copyright (C) 2011 - 2021 Olivier Biot
+melonJS 2 is a modern version of the melonJS game engine. It has been rebuilt almost entirely using ES6 class, inheritance and semantic, and is bundled using Rollup to provide modern features such as transpiling and tree-shaking.
 
-[melonJS](http://melonjs.org/) is licensed under the [MIT License](http://www.opensource.org/licenses/mit-license.php)
+>Note: migrating an existing project to melonJS 2 (version 10.0 and higher) will definitely break your game (ES6 semantic, no more Jay inheritance, nodeJS event emitter, and no backward compatibility with deprecated legacy APIs), and you might want to read first this small step by step guide on [upgrading to melonJS 2](https://github.com/melonjs/melonJS/wiki/Upgrading-to-melonJS-2). If you are looking at the legacy version (9.x and lower) of melonJS, you can find it [here](https://github.com/melonjs/melonJS/tree/legacy) under the _legacy_ branch.
+
+[melonJS](http://melonjs.org/) is open-source, licensed under the [MIT License](LICENSE.md), and actively developed and maintained with the help of a small team of enthusiasts at AltByte in Singapore.
 
 About melonJS
 -------------------------------------------------------------------------------
 
-[melonJS](http://melonjs.org/) is the result of our enthusiasm & experiments with Javascript,
-and currently features :
+[melonJS](http://melonjs.org/) is a fully featured game engine :
 
-- A fresh & lightweight 2D sprite-based engine
+Compatibility
 - Standalone library (does not rely on anything else, except a HTML5 capable browser)
 - Compatible with all major browsers (Chrome, Safari, Firefox, Opera, Edge) and mobile devices
-- Fast WebGL renderer for desktop and mobile devices with fallback to Canvas rendering
+
+Graphics
+- 2D sprite-based graphic engine
+- Fast WebGL 1 & 2 renderer for desktop and mobile devices with fallback to Canvas rendering
 - High DPI resolution & Canvas advanced auto scaling
-- Web Audio support with fallback to Multi-channel HTML5 audio
-- Lightweight physics implementation to ensure low cpu requirements
-- Polygon (SAT) based collision algorithm for accurate detection and response
-- Fast Broad-phase collision detection using spatial partitioning
-- 3rd party tools support for physic body definition such as [PhysicsEditor](https://www.codeandweb.com/physicseditor)
-- Advanced math API for Vector and Matrix
-- Tween Effects, Transition effects
-- Basic set of Object Entities and GUI elements included
-- Pooling support for object recycling
-- Basic Particle System
 - Sprite with Animation management
+- built-in effects such as tinting and masking
 - Standard spritesheet, single and multiple Packed Textures support
-- 3rd party tools support for Texture Packing such as [TexturePacker](https://www.codeandweb.com/texturepacker), [Free Texture Packer](http://free-tex-packer.com), [ShoeBox](https://renderhjs.net/shoebox/)
-- A state manager (to easily manage loading, menu, options, in-game state)
+- System & Bitmap Text
+
+Sound
+- Web Audio support with spatial audio or stereo panning based on [Howler](https://howlerjs.com)
+- fallback to Multi-channel HTML5 audio for legacy browsers
+
+Physic
+- Polygon (SAT) based collision algorithm for accurate detection and response
+- Fast Broad-phase collision detection using spatial partitioning
+- Collision filtering for optimized automatic collision detection
+
+Input
+- Mouse and Touch device support (with mouse emulation)
+- Device motion & accelerometer support
+
+Level Editor
 - Tiled map format version +1.0 integration for easy level design
     - Uncompressed Plain, Base64, CSV and JSON encoded XML tilemap loading
     - Orthogonal, Isometric and Hexagonal maps (both normal and staggered)
@@ -54,13 +63,29 @@ and currently features :
     - Dynamic Layer and Object/Group ordering
     - Dynamic Entity loading
     - Shape based Tile collision support
-- System & Bitmap fonts
-- Mouse and Touch device support (with mouse emulation)
-- Device motion & accelerometer support
-- Built-in support for 3rd party Application Wrappers such as [Cordova](https://cordova.apache.org)
-- Asynchronous publish/subscribe pattern messaging support (minPubSub)
+
+Assets
+- Asynchronous asset loading
 - A fully customizable preloader
-- As light as [~70kb](https://bundlephobia.com/result?p=melonjs@latest) minified & gzipped
+
+And Also
+- A state manager (to easily manage loading, menu, options, in-game state)
+- Tween Effects, Transition effects
+- Pooling support for object recycling
+- Basic Particle System
+- nodeJS EventEmitter based event system
+
+Tools integration
+-------------------------------------------------------------------------------
+ [![Free Texture Packer](https://user-images.githubusercontent.com/4033090/136762061-1d3a0dfe-dbe0-4d3d-808d-47a49ecf5309.png "Free Texture Packer")](http://free-tex-packer.com)
+ [![TexturePacker](https://user-images.githubusercontent.com/4033090/136762472-bc55a638-c69b-4ff5-9d03-c684c8bea0ea.png "TexturePacker")](https://www.codeandweb.com/texturepacker)
+ [![PhysicsEditor](https://user-images.githubusercontent.com/4033090/136762890-b1010c7f-cb19-4d35-a3f1-f5048db07835.png "PhysicsEditor")](https://www.codeandweb.com/physicseditor)
+ [![ShoeBox](https://user-images.githubusercontent.com/4033090/136762705-92027d94-d87c-4a95-b051-26647410248d.png "ShoeBox")](https://renderhjs.net/shoebox/)
+ [![Tiled](https://user-images.githubusercontent.com/4033090/136762999-5a7f377b-4136-4205-9fe0-83728c90cb9b.png "Tiled")](https://www.mapeditor.org)
+ [![Cordova](https://user-images.githubusercontent.com/4033090/136763147-6d157ce6-6921-437e-bb8f-0287b86109da.png "Cordova")](https://cordova.apache.org)
+
+Tools integration and usage with melonJS is documented in our [Wiki](https://github.com/melonjs/melonJS/wiki#third-party-tools-usage).
+
 
 Using melonJS
 -------------------------------------------------------------------------------
@@ -68,7 +93,7 @@ Using melonJS
 Basic Example
 
 ```JavaScript
-import * as me from "melonjs.module.js"
+import * as me from "melonjs.module.js";
 
 me.device.onReady(function () {
     // initialize the display canvas once the device/browser is ready
@@ -96,65 +121,68 @@ me.device.onReady(function () {
 Documentation :
 
 * [Online API](http://melonjs.github.io/melonJS/docs/) ([offline](https://github.com/melonjs/melonJS/archive/gh-pages.zip) version under the `docs` directory)
-* [Examples](https://melonjs.github.io/examples/)
 
 For your first time using melonJS, follow these tutorials :
 
 - [Platformer](http://melonjs.github.io/tutorial-platformer/) Step by Step Tutorial.
 - [Space Invaders](http://melonjs.github.io/tutorial-space-invaders/) Step by Step Tutorial.
 
+> Note: current version of both the tutorials are not compatible with the ES6 version.
+
 You may find it useful to skim the overview found at the wiki [Details & Usage](https://github.com/melonjs/melonJS/wiki#details--usage)
 
-When starting your own projects, checkout the [boilerplate](https://github.com/melonjs/boilerplate)
+When starting your own projects, checkout our [es6 boilerplate](https://github.com/melonjs/es6-boilerplate)
+
+Demos
+-------------------------------------------------------------------------------
+
+A few demos of melonJS capabilities :
+
+* [Platformer Demo](https://melonjs.github.io/examples/examples/platformer/)
+* [Isometric Demo](https://melonjs.github.io/examples/examples/isometric_rpg/)
+* [Sprite Demo](https://melonjs.github.io/examples/examples/sprite/)
+* [Masking Demo](https://melonjs.github.io/examples/examples/masking/)
+* [Primitive Drawing Demo](https://melonjs.github.io/examples/examples/graphics/)
+* [UI Demo](https://melonjs.github.io/examples/examples/UI/)
+
+More examples are available [here](https://melonjs.github.io/examples/)
 
 Download melonJS
 -------------------------------------------------------------------------------
 
 The latest builds with corresponding release note are available for direct download [here](https://github.com/melonjs/melonJS/releases).
 
-Since version 9.0.0 melonJS provides different build options :
+Since version 10.0.0 melonJS provides different build options :
 
 | build               | description |
 | ------------------- | ----------- |
-| `melonjs.js`        | a legacy ES5 UMD Bundle (directly transpiled from the ES6 version) including full API backward compatibility with previous versions |
-| `melonjs.min.js`    | a minified version of the ES5 UMD bundle version |
-| `melonjs.module.js` | a ES6 Module Bundle, for those living on the edge, and with no backward compatibility (note: this will break your game when upgrading!) |
-
-> Note: current version of both the tutorials and the debugPanel are not compatible with the ES6 version.
+| `melonjs.module.js` | the ES6 Module (ESM) Bundle |
+| `melonjs.module.d.ts` | typescript declaration file for the ES6 Module (ESM) Bundle |
+| `melonjs.js`        | a ES5 UMD Bundle (directly transpiled from the ES6 version) |
+| `melonjs.min.js`    | a minified version of the ES5 UMD bundle |
 
 Alternatively, the latest version of melonJS can be installed through [NPM](https://www.npmjs.com/package/melonjs) :
 
     $ npm install melonjs
 
-If you need to import the ES6 module of melonjs :
-
-    $ import * as me from "melonjs.module.js";
+If you need to import the ES6 module of melonjs (e.g. for Webpack):
 
-> Note: when using the es6 module, deprecated methods need to be manually applied, see [here](http://melonjs.github.io/melonJS/docs/me.deprecated.html#.apply)
+    $ import * as me from 'melonjs/dist/melonjs.module.js';
 
 Or can simply be added to your html, through a content delivery network (CDN) URL, using for example :
 
 ```html
-<!-- load the ES5 UMD bundle of melonJS v9.0.0 -->
-<script src="https://cdn.jsdelivr.net/npm/melonjs@9.0.0/dist/melonjs.js"></script>
-<!-- load the ES6 module bundle of melonJS v9.0.0 -->
-<script src="https://cdn.jsdelivr.net/npm/melonjs@9.0.0/dist/melonjs.module.js"></script>
+<!-- load the ES5 UMD bundle of melonJS v10.0.0 -->
+<script src="https://cdn.jsdelivr.net/npm/melonjs@10.0.0/dist/melonjs.js"></script>
+<!-- load the ES6 module bundle of melonJS v10.0.0 -->
+<script src="https://cdn.jsdelivr.net/npm/melonjs@10.0.0/dist/melonjs.module.js"></script>
 <!-- omit the version completely to get the latest one -->
 <!-- you should NOT use this in production -->
 <script src="https://cdn.jsdelivr.net/npm/melonjs/dist/melonjs.js"></script>
 <!-- add ".min" to any JS/CSS file to get a minified version -->
-<script src="https://cdn.jsdelivr.net/npm/melonjs@8.0.1/dist/melonjs.min.js"></script>
-```
-and of course the debug panel :
-```html
-<!-- load the latest debug panel -->
-<script src="https://cdn.jsdelivr.net/npm/melonjs/plugins/debug/debugPanel.js"></script>
-<!-- or a specific corresponding release -->
-<script src="https://cdn.jsdelivr.net/npm/melonjs@8.0.1/plugins/debug/debugPanel.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/melonjs@10.0.0/dist/melonjs.min.js"></script>
 ```
-
-> Note: "official" CDN and NPM install are only available from version 7.0.0 and onwards.
-> Note: ES6 version of melonJS is available from version 9.0.0 and onwards.
+> Note: starting from the 10.0.0 version, the debug plugin is no longer provided as part of the melonJS library release, and has been moved to the official [boilerplate](https://github.com/melonjs/es6-boilerplate)
 
 Building melonJS
 -------------------------------------------------------------------------------
@@ -209,4 +237,12 @@ If you need technical support, you can contact us through the following channels
 * [melonJS wikipage](https://github.com/melonjs/melonJS/wiki)
 * [Discord](https://discord.gg/aur7JMk)
 
-For any other non technical related questions, feel free to also send us an [email](mailto:contact@melonjs.org).
+For any other non technical related questions, feel free to also send us an [email](mailto:contact@melonjs.org)
+
+Sponsors
+-------------------------------------------------------------------------------
+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 !
+
+[![Melon Gaming](https://user-images.githubusercontent.com/4033090/136695857-d098c27d-f4b2-4c71-8574-b5f4291779cb.png "Melon Gaming")](https://www.melongaming.com)
+
+[![Altbyte Pte Ltd](https://user-images.githubusercontent.com/4033090/136692693-35dca8aa-5012-4a37-9ea2-51640d2e6d73.png "AltByte")]()