stage-js 0.9.5 → 1.0.0-alpha.1

package/.gitattributes

@@ -0,0 +1 @@
+* text=auto

package/CHANGELOG.md

@@ -0,0 +1,146 @@
+#### v1.0 [work in progress]
+* use ES modules and classes
+* typescript definition added
+* lib directory renamed to src, and folder structure flattened
+* all classes are exported under Stage namespace
+* added Stage.mount()
+* Stage is not callable
+* removed Stage.internal
+* removed Stage() (use other functions to create components)
+* removed Stage({ }), and await Stage.atlas({ }) preloads images
+* removed Stage(function(root, canvas))
+* removed Stage.app(callback)
+* removed script loader `preload(url)`
+* removed relative path resolver for texture images
+* removed cordova/fastcontext loader and build removed
+* removed different platform builds (web, cordova)
+* removed Stage.config()
+* removed _create, _extend functions with js functions
+* Ease() replaced by Ease.get()
+* removed Stage.Math, added Stage.math with different function names
+* renamed sequence to align
+* removed Matrix.reverse (use inverse)
+* removed Mouse.subscribe, replaced by new Mouse().mount
+* renamed Image/image to Sprite/sprite, and .image() to .texture()
+
+#### v0.8.2
+* `render.js` renamed to `loop.js`
+* `node.js` renamed to `tree.js`
+* cordova starts by mousemove
+
+#### v0.8.1
+* `node.scaleTo()` shortcut pinning method added
+* `node.matrix(true)` returns relative matrix instead of absolute
+
+#### v0.8.0
+* **default `.tween()` behavior changed from append to replace**
+* `.tween(duration, delay)` changed to `.tween(duration, delay, append = false)`
+* `tween.clear()` deprecated and no-op
+* `tween.end()` replaced by `tween.done()`
+
+#### v0.7.1
+* `tween.then()` replaced by `tween.end()`
+* `tween.remove/hide()` are added
+
+#### v0.7.0
+* **images and script urls starting with `./` are resolved as relative**
+
+#### v0.6.7
+* Stage.Math extends native Math
+
+#### v0.6.6
+* lookup atlas by name before textures
+* `node.width/height()` pinning shortcuts return value
+* preloadScript('url') removed
+
+#### v0.6.5
+* **.preload('url.js') added**
+
+#### v0.6.4
+* pinning shortcuts are added to nodes
+* entire atlas can be referenced
+
+#### v0.6.2
+* `atlas.image.url` renamed to `src`
+* pining shorthand methods added to node
+* tick-based `timeout(fn, delay)` method added to node
+* entire atlas can be used as texture
+
+#### v0.6.0
+* **Cut/CutJS renamed to Stage/Stage.js**
+
+#### v0.5.0
+* atlas spec changed
+* **.preload(fn) added**
+* node.insert/append/prepend() methods accept array
+* node.id() renamed to node.label()
+* Cut.addTexture() removed
+* image.cropY/cropY() removed
+* anim.gotoLabel() removed
+* Cut.Anim.FPS is not public anymore
+* drawing() replaced with .canvas()
+* **Texture renamed to Atlas, new Texture class replaced Cut.Out**
+* node._cutouts and Cut.cutout() replaced with node._textures and Cut.texture()
+* Cut.texture() returns selection object
+* image-loader spec changed
+
+#### v0.4.12
+* root.background method added
+
+#### v0.4.10
+* **game loop continues if any tick returns true, but only renders if touched**
+
+#### v0.4.9
+* texture.ratio renamed to texture.ppu
+
+#### v0.4.8
+* new drawing (experimental) and cutout (internal) api
+
+#### v0.4.3
+* pin set/get is refactored
+* resize in/out replace with scale in-pad/out-crop
+* default viewbox mode is 'in-pad'
+
+#### v0.4.0
+* **CommonJS/Node.js files and project structure**
+* Source files moved to `lib` and platform files to `platform`
+* extension files moved to ext
+* `lib/main` set as npm `main`
+* texture name made optional in cutout selector: `"[texture:]cutout"`
+* FastContext support added to Cordova, FastCanvas loader removed
+
+* `Cut.Out.select` replaced with `Cut.cutout`
+* `Cut.config` and `Cut.start(configs)` are added
+* `Cut.init` and `Loader.loadImage` replaced with `"app-loader"` and `"image-loader"` configs
+* `Loader` merged with `Root`
+* `Loader.start/pause/resume` replaced with `Cut.start/pause/resume`
+* `root._ratio` replaced with `root.viewport().ratio`
+* `_isCut` replaced with `Cut._ensure`
+* `Texture` reorganized
+* `root.resize()` renamed to `viewport()`
+
+#### v0.3.1
+* Remove `Mouse(..., captureAnyMove)` and use flag instead
+* Refactoring easing class and moving tween/ease to another file
+
+#### v0.3.0
+* **Browserified**
+* Synthetic `Mouse` clicks instead of browser clicks
+* New `off` method to remove listeners
+* New `data` parameter for `visit` methods
+* `_listens` renamed to `_flag`
+* `_isFunc`, `_function`, `_options` and `_status` are removed 
+* `_extend` signature changed
+
+#### v0.2.1
+* `setImage/Value/Frames/Font` deprecated and replaced by `image/value/frames`
+
+#### v0.2.0
+* mouse event listener signature changed from `(rawEvent, {x, y})` to `({x, y, raw})`
+* `viewport` listener signature changed from `(width, height)` to `({width, height})`
+* `Cut.addTexture(...)` is replaced with `Cut(...)`
+* `spy(true)` is replaced with `attr('spy', true)`
+* tweening support for pinning XY-shorthands added 
+* `drawing` signature changed from `([name], width, height, [ratio], callback, [def])` to `([name], width, height, [ratio], [callback])` and `(def, [callback])`
+* node.trigger() method added, calls .publish() and returns `this`
+* using deep listeners count instead of `spy` to optimized mouse event distribution

package/LICENSE.md

@@ -1,4 +1,4 @@
-@copyright Copyright (c) 2020 Ali Shakiba http://shakiba.me/stage.js  
+@copyright Copyright (c) 2023 Ali Shakiba http://shakiba.me/stage.js  
 @license The MIT License (MIT)  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

package/README.md

@@ -1,101 +1,81 @@
 [![Stage](https://s3.amazonaws.com/piqnt.com/stage.js/stage.png)](http://piqnt.com/stage.js/)
 
-Stage.js is a 2D HTML5 JavaScript library for cross-platform game development, it is lightweight, fast and open-source.
+Stage.js is a 2D rendering and layout library for HTML5 Canvas. It is lightweight, fast and optimized for web and mobile game development.
 
-[**Check out examples and demos!**](http://piqnt.com/stage.js/)
+### Features
+- Tree object model, similar to DOM, for composing an application
+- Managed and optimized rendering and game loop
+- Mouse events processing and delivering them to target nodes
+- Positioning and layout
+- Texture atlas and image preloading
 
-[Install](#installation) · [Usage](#usage) · [Resources](#resources) · [API Doc](#api-doc) · [Development](#development) · [License](#license)
+[**Live Examples and Demos**](http://piqnt.com/stage.js/)
 
 [中文手册](https://github.com/shakiba/stage.js/wiki/%E4%B8%AD%E6%96%87%E6%89%8B%E5%86%8C)
 
+## v1.0-alpha [Work in Progress] Upgrade and Breaking Changes
 
-## Introduction
+Since the initial development of Stage.js in 2013, web technology has changed a lot. The new version of Stage.js is updated to take advantage of new technologies to simplify the API. There are backward incompatible changes in the new version. Please see the [upgrade](./UPGRADE.md) doc for more information.
 
-Canvas is the graphic component of HTML5 game development, but it only has a drawing API and there is no data model like the DOM to compose your application.
-You need to manually draw your application and manage rendering cycles to play it.
-Moreover, mouse events are only available at the entire Canvas level and they also need to be processed manually.
+## Install
 
-Stage.js provides a DOM-like tree data model to compose your application and internally manages rendering cycles and the drawing of your application.
-It also processes and distributes mouse and touch events to targeted tree nodes.
-A Stage.js application consists of a tree of nodes. Each node is pinned (transformed) against its parent and has zero, one or more image textures.
 
-Each rendering cycle consists of ticking and drawing tree nodes. On ticking, nodes adjust themselves to recent updates while on drawing each node transforms according to its pinning and draws its textures.
-
-Rendering is retained and is paused when there is no change.
-
-### Example
-
-```js
-// Create new app
-Stage(function(stage) {
-
-  // Set view box
-  stage.viewbox(300, 200);
-
-  // Create an image and append it to stage
-  var box = Stage.image('box').appendTo(stage);
-
-  // Align box to center
-  box.pin('align', 0.5);
-
-  // On mouse click...
-  box.on('click', function(point) {
-    // ...tween scale values of this node
-    this.tween().ease('bounce').pin({
-      scaleX : Math.random() + 0.5,
-      scaleY : Math.random() + 0.5
-    });
-  });
-});
+#### Browser
 
-// Adding a texture
-Stage({
-  image : 'sample.png',
-  textures : {
-    box : { x : 0, y : 0, width : 30, height : 30 }
-  }
-});
+```html
+<script src="https://cdn.jsdelivr.net/npm/stage-js@1.0"></script>
+<script>
+  const app = Stage.mount();
+</script>
 ```
 
-
-## Installation
-
-#### Download
-Latest builds are available in the project [releases page](https://github.com/shakiba/stage.js/releases/latest).
-
 #### NPM
 
 ```
-npm install stage-js --save
+npm install --save stage-js
 ```
 
-#### Bower
-
+```js
+const Stage = require('stage-js');
 ```
-bower install stage-js --save
+
+```js
+import Stage from 'stage-js';
 ```
 
+### Example
 
-## Usage
+```js
+// Define and preload a texture
+await Stage.atlas({
+  image : 'sample.png',
+  textures : {
+    box : { x : 0, y : 0, width : 30, height : 30 }
+  }
+});
 
-#### Browser
+// Create and mount a new app
+const app = Stage.mount();
 
-Include an appropriate build file from `dist` directory in your HTML page before your application. For example:
+// Set view box
+app.viewbox(300, 200);
 
-```html
-<script src="path/to/stage.web.min.js"></script>
-<script src="path/to/your-app.js"></script>
-```
+// Create an sprite and append it to app
+const box = Stage.sprite('box').appendTo(app);
 
-#### Browserify, CommonJS, Node.js
-Generally it is preferred to directly include a browser build file in HTML pages, however it is also possible to use CommonJS require instead, for example:
+// Align box to center
+box.pin('align', 0.5);
 
-```js
-var Stage = require('stage-js/platform/web');
+// On mouse click...
+box.on('click', function(point) {
+  // ...tween scale values of this node
+  this.tween().ease('bounce').pin({
+    scaleX : Math.random() + 0.5,
+    scaleY : Math.random() + 0.5
+  });
+});
 ```
 
-See `platform` directory for other available modules.
-
 
 ## Resources
 
@@ -106,37 +86,42 @@ See `platform` directory for other available modules.
 
 ## API Doc
 
-### Application
-An application is created by passing a callback function to `Stage()`.
-The library will load, create and initialize all required components and will then call the provided function with the application root node and display the container which is normally a Canvas element.
+### Setup
+An application is created by calling `Stage.mount()`.
+This will set up the root node with a canvas element, starts the application, and returns the root node.
 
 ```javascript
-// Create and start an application
-Stage(function(stage, display) {
+// Create and start an application (with a default full page canvas)
+const app = Stage.mount();
 
-  // Set viewbox for stage, see pinning for valid modes
-  stage.viewbox(width, height, mode = 'in-pad');
-
-  // Listen to view port resize events
-  stage.on('viewport', function(viewport) {
-    // `viewport` attributes are `width`, `height` and `ratio`
-  });
+// Create and start an application with a custom canvas element
+const app = Stage.mount({
+  canvas : document.getElementById('game-canvas')
+});
 
-  // Pause playing
-  stage.pause();
+// Set viewbox for stage, see pinning for valid modes
+app.viewbox(width, height, mode = 'in-pad');
 
-  // Resume playing
-  stage.resume();
+// Listen to view port resize events
+app.on('viewport', function(viewport) {
+  // `viewport` attributes are `width`, `height` and `ratio`
 });
+
+// Pause playing
+app.pause();
+
+// Resume playing
+app.resume();
+
 ```
 
 
 ### Tree Model
-Every app consists of a tree. The tree's root is provided as `stage`.
+Every application consists of a tree. The tree's root is created and returned by `Stage.mount()`.
 
 ```javascript
 // Create a new node instance (with no textures)
-var node = Stage.create();
+const node = Stage.create();
 
 // Append/prepend child to parent's children (accepts array)
 parent.append(child);
@@ -182,12 +167,12 @@ node.hide();
 node.show();
 
 // Iterate over parent's children, child can not be removed
-for (var child = parent.first(); child; child = child.next()) {
+for (let child = parent.first(); child; child = child.next()) {
   // use child
 }
 
 // Iterate over parent's children, child can be removed
-var child, next = parent.first();
+let child, next = parent.first();
 while (child = next) {
   next = child.next();
   // use child
@@ -209,7 +194,7 @@ node.visit({
 
 ### Game Loop
 Each rendering cycle consists of ticking and redrawing the application tree.
-Application and its nodes can be updated during ticking.
+An application and its nodes can be updated during ticking.
 Depending on application activities there can be three different follow-ups after ticking:
 
 * If at least one node is touched then the entire application tree will be redrawn and the game loop will continue.
@@ -403,13 +388,13 @@ Stage.Mouse.CANCEL = 'touchcancel mousecancel';
 Textures are drawable objects which are used by tree nodes to draw graphics on the Canvas surface.
 
 ### Texture Atlas
-A texture atlas (sprite sheet) consists of a set of named textures which are referenced by name in an application.
+A texture atlas (sprite sheet) consists of a set of named textures that are referenced by name in an application.
 
 Atlases are usually created using static image files. Images referenced in atlases are automatically preloaded.
 
 ```javascript
 // Adding texture atlas
-Stage({
+Stage.atlas({
   name : 'mario', // optional
   image : {
     src : 'mario.png',
@@ -437,30 +422,27 @@ Stage({
   }
 });
 
-Stage.image('mario:stand');
+Stage.sprite('mario:stand');
 
 Stage.anim('mario:walk').play();
 
 Stage.string('mario:number').value(100);
 ```
 
-If image src starts with `./` it will be resolved relative to the current script URL.
-
-
-### Image
-An image is a node with one texture.
+### Sprite
+A sprite is a node with one texture.
 
 ```javascript
-// Create a new image instance
-var image = Stage.image(texture);
+// Create a new sprite instance
+let sprite = Stage.sprite(texture);
 
-// Change image texture
-image.image(texture);
+// Change sprite texture
+sprite.image(texture);
 
-// Tile/Stretch image when pinning width and/or height
+// Tile/Stretch sprite when pinning width and/or height
 // To define borders add top, bottom, left and right to texture
-image.tile();
-image.stretch();
+sprite.tile();
+sprite.stretch();
 ```
 
 
@@ -469,7 +451,7 @@ An animation or anim is a node with an array of textures as frames.
 
 ```javascript
 // Create a new anim instance
-var anim = Stage.anim(textures, fps = 15);
+const anim = Stage.anim(textures, fps = 15);
 
 // Get or set animation frame-per-second
 anim.fps();
@@ -499,11 +481,11 @@ anim.repeat(repeat, callback = null);
 
 
 ### String
-String is a row of images which are dynamically selected from `frames` using characters of a string `value` (or items of an array `value`).
+String is a row of textures that are dynamically selected from `frames` using characters of a string value, or items of an array value.
 
 ```javascript
 // Create a new string instance with frames
-var string = Stage.string(frames);
+const string = Stage.string(frames);
 
 // Set frames, a string referencing a map in an atlas 
 string.frames("digits");
@@ -531,12 +513,12 @@ string.value();
 
 
 ### Row and Column
-A row/column is a node which organizes its children as a horizontal/vertical sequence.
+A row/column is a node that aligns its children in a horizontal/vertical direction.
 
 ```javascript
 // Create a new row/column
-var row = Stage.row(childrenAlignY = 0);
-var column = Stage.column(childrenAlignX = 0);
+const row = Stage.row(childrenAlignY = 0);
+const column = Stage.column(childrenAlignX = 0);
 
 // Make node a row/column
 node.row(childrenAlignY = 0);
@@ -548,25 +530,37 @@ node.spacing(space);
 
 
 ### Box (experimental)
-A box resizes to wrap its children. It can be applied to tiled/stretched
-images to create variable size components such as windows and buttons.
+A box resizes to cover its children. It can be applied to tiled/stretched
+images, for example, to create variable-size nodes such as windows and buttons.
 
 ```javascript
 // Create a new box
-var box = Stage.box();
+const box = Stage.box();
 
 // Make node a box
 node = node.box();
 ```
 
 
+### Layer (experimental)
+A layer resizes to cover its parent.
+
+```javascript
+// Create a new layer
+const box = Stage.box();
+
+// Make node a layer
+node = node.layer();
+```
+
+
 ### Tweening
 Tweening is used to apply smooth transitions to pinning values.
 
 ```javascript
 // Create a tweening entry
 // When `append` is true new entry is appended to current entries otherwise replaces them
-var tween = node.tween(duration = 400, delay = 0, append = false);
+const tween = node.tween(duration = 400, delay = 0, append = false);
 
 // Set pinning values and start tweening
 // Pinning shortcut methods, such as `.scale()`, can also be used
@@ -597,29 +591,18 @@ tween.remove();
 tween.hide();
 
 // Create and chain a new tweening to this entry
-var nextTween = tween.tween(duration = 400, delay = 0);
+const nextTween = tween.tween(duration = 400, delay = 0);
 ```
 
 
 ### Global Methods
 ```javascript
 
-// Create a new app
-Stage(function(stage, display) { });
+// Mount and start a new app
+let app = Stage.mount();
 
 // Create and preload a texture atlas
-Stage({ });
-
-// A function to be called before starting any app
-// Can be used for preloading application assets
-Stage.preload(function(done) {
-  // Call `done` when loaded or failed
-  done(error);
-});
-
-// Preload and execute a JS file
-// URLs starting with `./` are resolved relative to current script URL
-Stage.preload(src);
+Stage.atlas({ ... });
 
 // Pause playing all applications
 Stage.pause();
@@ -630,12 +613,12 @@ Stage.resume();
 
 
 ## Development
-To try examples with a live build run following command and check output for the URL to open in your browser:
+To try examples with a live build run the following command and check the output for the URL to open in your browser:
 ```
 npm run dev
 ```
 
 
 ## License
-Copyright 2020 Ali Shakiba http://shakiba.me/stage.js  
+Copyright 2023 Ali Shakiba http://shakiba.me/stage.js  
 Available under the MIT License

package/UPGRADE.md

@@ -0,0 +1,26 @@
+
+## V1 [Work in Progress] Upgrade and Breaking Changes
+
+Since the initial development of Stage.js in 2013, web technology has changed a lot. The new version of Stage.js is updated to take advantage of new web technologies to simplify the API, and there are backward incompatible changes in the new version.
+
+#### Importing and Starting
+The first important change is using ES classes and exports. Now all classes are exported under `Stage` namespace, and `Stage` is not a function or a type anymore. In addition, preloading images and creating textures are separated from creating and mounting an app, and you need to use `await` to wait for the preloading to finish.
+
+- Use `stage = Stage.mount()` to create and mount a new app, instead of `Stage(function(stage){ }))`.
+- Use `await Stage.atlas({ })` to preload images and create textures before using them, instead of `Stage({ })`.
+- Use `Stage.Node` as the base class for your custom nodes, instead of `Stage`.
+
+#### Build
+The second change is build-files. There are multiple build outputs for ES, CommonJS, and UMD.
+
+FastContext support is dropped in this version, and there is one build file for all platforms. FastContext was used to take advantage of native GPU rendering in Android devices when browser Canvas rendering was not GPU optimized, however this is not needed anymore.
+
+#### Relative Paths
+The second important change is that relative image paths for textures are not resolved relative to the script anymore. You need to use absolute paths or resolve them yourself using a build tool.
+
+#### Other API Changes
+There are also smaller API changes:
+- 'Stage.Image` and `Stage.image()` are renamed to `Stage.Sprite` and `Stage.sprite()` (to avoid overlapping with native Image class).
+- `Stage.Math` is renamed to `Stage.math` and extends native `Math` (to avoid overlapping with native Math class).
+
+For a complete list of changes, see [CHANGELOG.md](CHANGELOG.md).