Comparing version 0.9.5 to 1.0.0-alpha.1
@@ -1,2 +0,2 @@ | ||
@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) | ||
@@ -3,0 +3,0 @@ |
{ | ||
"name": "stage-js", | ||
"version": "0.9.5", | ||
"version": "1.0.0-alpha.1", | ||
"description": "2D HTML5 Rendering and Layout", | ||
@@ -24,29 +24,34 @@ "homepage": "http://piqnt.com/stage.js/", | ||
], | ||
"main": "lib/index.js", | ||
"files": [ | ||
"dist/", | ||
"doc/", | ||
"ext/", | ||
"lib/", | ||
"platform/", | ||
"test/" | ||
"type": "module", | ||
"main": "./dist/stage.cjs", | ||
"module": "./dist/stage.js", | ||
"browser": "./dist/stage.cjs", | ||
"jsdelivr": "dist/stage.umd.cjs", | ||
"unpkg": "dist/stage.umd.cjs", | ||
"exports": { | ||
".": { | ||
"types": "./index.d.ts", | ||
"import": "./dist/stage.js", | ||
"require": "./dist/stage.umd.cjs" | ||
} | ||
}, | ||
"types": "./index.d.ts", | ||
"ignore": [ | ||
"example/" | ||
], | ||
"devDependencies": { | ||
"expect.js": "*", | ||
"express": "^4.17.1", | ||
"@vue/compiler-sfc": "^3.3.4", | ||
"expect.js": "^0.3.1", | ||
"glob": "^10.2.6", | ||
"mocha": "^6.2.3", | ||
"nodemon": "^1.19.1", | ||
"sandboxed-module": "^2.0.0", | ||
"serve-index": "^1.9.1", | ||
"sinon": "^9.0.2", | ||
"webpack": "^4.33.0", | ||
"webpack-cli": "^3.3.3", | ||
"webpack-dev-middleware": "^3.7.0" | ||
"vite": "^4.3.8", | ||
"vite-plugin-pages": "^0.30.1" | ||
}, | ||
"scripts": { | ||
"test": "mocha test/*.js", | ||
"build": "webpack -p", | ||
"watch": "webpack --watch", | ||
"dev": "nodemon server.js" | ||
"dev": "vite", | ||
"build": "vite build", | ||
"test": "mocha test/*.js" | ||
} | ||
} |
245
README.md
[![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. | ||
#### Browser | ||
Rendering is retained and is paused when there is no change. | ||
```html | ||
<script src="https://cdn.jsdelivr.net/npm/stage-js@1.0"></script> | ||
<script> | ||
const app = Stage.mount(); | ||
</script> | ||
``` | ||
### Example | ||
#### NPM | ||
``` | ||
npm install --save stage-js | ||
``` | ||
```js | ||
// Create new app | ||
Stage(function(stage) { | ||
const Stage = require('stage-js'); | ||
``` | ||
// Set view box | ||
stage.viewbox(300, 200); | ||
```js | ||
import Stage from 'stage-js'; | ||
``` | ||
// Create an image and append it to stage | ||
var box = Stage.image('box').appendTo(stage); | ||
### Example | ||
// 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 | ||
}); | ||
}); | ||
}); | ||
// Adding a texture | ||
Stage({ | ||
```js | ||
// Define and preload a texture | ||
await Stage.atlas({ | ||
image : 'sample.png', | ||
@@ -58,44 +56,26 @@ textures : { | ||
}); | ||
``` | ||
// Create and mount a new app | ||
const app = Stage.mount(); | ||
## Installation | ||
// Set view box | ||
app.viewbox(300, 200); | ||
#### Download | ||
Latest builds are available in the project [releases page](https://github.com/shakiba/stage.js/releases/latest). | ||
// Create an sprite and append it to app | ||
const box = Stage.sprite('box').appendTo(app); | ||
#### NPM | ||
// 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 | ||
}); | ||
}); | ||
``` | ||
npm install stage-js --save | ||
``` | ||
#### Bower | ||
``` | ||
bower install stage-js --save | ||
``` | ||
## Usage | ||
#### Browser | ||
Include an appropriate build file from `dist` directory in your HTML page before your application. For example: | ||
```html | ||
<script src="path/to/stage.web.min.js"></script> | ||
<script src="path/to/your-app.js"></script> | ||
``` | ||
#### 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: | ||
```js | ||
var Stage = require('stage-js/platform/web'); | ||
``` | ||
See `platform` directory for other available modules. | ||
## Resources | ||
@@ -110,24 +90,29 @@ | ||
### 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'); | ||
// Create and start an application with a custom canvas element | ||
const app = Stage.mount({ | ||
canvas : document.getElementById('game-canvas') | ||
}); | ||
// Listen to view port resize events | ||
stage.on('viewport', function(viewport) { | ||
// `viewport` attributes are `width`, `height` and `ratio` | ||
}); | ||
// Set viewbox for stage, see pinning for valid modes | ||
app.viewbox(width, height, mode = 'in-pad'); | ||
// Pause playing | ||
stage.pause(); | ||
// Listen to view port resize events | ||
app.on('viewport', function(viewport) { | ||
// `viewport` attributes are `width`, `height` and `ratio` | ||
}); | ||
// Resume playing | ||
stage.resume(); | ||
}); | ||
// Pause playing | ||
app.pause(); | ||
// Resume playing | ||
app.resume(); | ||
``` | ||
@@ -137,7 +122,7 @@ | ||
### 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(); | ||
@@ -188,3 +173,3 @@ // Append/prepend child to parent's children (accepts array) | ||
// 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 | ||
@@ -194,3 +179,3 @@ } | ||
// Iterate over parent's children, child can be removed | ||
var child, next = parent.first(); | ||
let child, next = parent.first(); | ||
while (child = next) { | ||
@@ -217,3 +202,3 @@ next = child.next(); | ||
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: | ||
@@ -412,3 +397,3 @@ | ||
### 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. | ||
@@ -419,3 +404,3 @@ Atlases are usually created using static image files. Images referenced in atlases are automatically preloaded. | ||
// Adding texture atlas | ||
Stage({ | ||
Stage.atlas({ | ||
name : 'mario', // optional | ||
@@ -448,3 +433,3 @@ image : { | ||
Stage.image('mario:stand'); | ||
Stage.sprite('mario:stand'); | ||
@@ -456,19 +441,16 @@ Stage.anim('mario:walk').play(); | ||
If image src starts with `./` it will be resolved relative to the current script URL. | ||
### Sprite | ||
A sprite is a node with one texture. | ||
### Image | ||
An image 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(); | ||
``` | ||
@@ -482,3 +464,3 @@ | ||
// Create a new anim instance | ||
var anim = Stage.anim(textures, fps = 15); | ||
const anim = Stage.anim(textures, fps = 15); | ||
@@ -513,7 +495,7 @@ // Get or set animation frame-per-second | ||
### 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); | ||
@@ -546,8 +528,8 @@ // Set frames, a string referencing a map in an atlas | ||
### 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); | ||
@@ -564,8 +546,8 @@ // Make node a row/column | ||
### 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(); | ||
@@ -577,2 +559,14 @@ // Make node a 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 | ||
@@ -584,3 +578,3 @@ Tweening is used to apply smooth transitions to pinning values. | ||
// 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); | ||
@@ -616,3 +610,3 @@ // Set pinning values and start tweening | ||
// 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); | ||
``` | ||
@@ -624,19 +618,8 @@ | ||
// 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({ }); | ||
Stage.atlas({ ... }); | ||
// 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); | ||
// Pause playing all applications | ||
@@ -651,3 +634,3 @@ Stage.pause(); | ||
## 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: | ||
``` | ||
@@ -659,3 +642,3 @@ 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 |
@@ -5,5 +5,5 @@ var expect = require('./util/expect'); | ||
var Stage = require('../lib/tree'); | ||
var Texture = require('../lib/texture'); | ||
var Atlas = require('../lib/atlas'); | ||
var Stage = require('../src/tree'); | ||
var Texture = require('../src/texture'); | ||
var Atlas = require('../src/atlas'); | ||
@@ -111,3 +111,3 @@ var mario = { | ||
it('atlas.textures', function() { | ||
var Stage = sandboxed.require('../lib/'); | ||
var Stage = sandboxed.require('../src/'); | ||
@@ -145,3 +145,3 @@ Stage.atlas({ | ||
it('atlas.cutouts', function() { | ||
var Stage = sandboxed.require('../lib/'); | ||
var Stage = sandboxed.require('../src/'); | ||
@@ -148,0 +148,0 @@ Stage.atlas({ |
var expect = require('./util/expect'); | ||
var sinon = require('sinon'); | ||
var Stage = require('../lib/tree'); | ||
require('../lib/event'); | ||
var Stage = require('../src/tree'); | ||
require('../src/event'); | ||
@@ -7,0 +7,0 @@ describe('Event', function() { |
var expect = require('./util/expect'); | ||
var sinon = require('sinon'); | ||
var Stage = require('../lib/'); | ||
var Stage = require('../src/'); | ||
it('static methods', function() { | ||
expect(Stage.config).be.a('function'); | ||
expect(Stage.preload).be.a('function'); | ||
expect(Stage.start).be.a('function'); | ||
@@ -18,3 +16,3 @@ expect(Stage.pause).be.a('function'); | ||
// expect(Stage.stage).be.a('function'); | ||
// expect(Stage.image).be.a('function'); | ||
// expect(Stage.sprite).be.a('function'); | ||
// expect(Stage.anim).be.a('function'); | ||
@@ -21,0 +19,0 @@ // expect(Stage.string).be.a('function'); |
@@ -6,3 +6,3 @@ var expect = require('./util/expect'); | ||
var Stage = require('../lib/'); | ||
var Stage = require('../src/'); | ||
@@ -12,3 +12,3 @@ it('Mouse', function() { | ||
var Mouse = sandboxed.require('../lib/addon/mouse', { | ||
var Mouse = sandboxed.require('../src/mouse', { | ||
locals : { | ||
@@ -48,3 +48,3 @@ document : doc = { | ||
Mouse.subscribe(stage, elem = { | ||
new Mouse().mount(stage, elem = { | ||
addEventListener : elemOn = sinon.stub(), | ||
@@ -51,0 +51,0 @@ getBoundingClientRect : function() { |
@@ -5,3 +5,3 @@ var expect = require('./util/expect'); | ||
var Stage = require('../lib/tree'); | ||
var Stage = require('../src/tree'); | ||
@@ -8,0 +8,0 @@ it('label', function() { |
var expect = require('./util/expect'); | ||
var sinon = require('sinon'); | ||
var Stage = require('../lib/tree'); | ||
var Pin = require('../lib/pin'); | ||
var Stage = require('../src/tree'); | ||
var Pin = require('../src/pin'); | ||
@@ -7,0 +7,0 @@ describe('Pin', function() { |
var expect = require('./util/expect'); | ||
var sinon = require('sinon'); | ||
var Stage = require('../lib'); | ||
var Tween = require('../lib/addon/tween'); | ||
var Stage = require('../src/'); | ||
var Tween = require('../src/tween'); | ||
@@ -7,0 +7,0 @@ describe('Tween', function() { |
@@ -34,3 +34,3 @@ var expect = require('expect.js'); | ||
module.exports = expect; | ||
export default expect; | ||
@@ -37,0 +37,0 @@ Array.prototype.pluck = function(key) { |
@@ -1,2 +0,2 @@ | ||
module.exports = function(create) { | ||
export default function(create) { | ||
var memo = {}; | ||
@@ -3,0 +3,0 @@ function fn(key) { |
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
Dynamic require
Supply chain riskDynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
1933943
8
136
25763
Yes
625
2
1