StageJS

用于游戏开发的2D HTML5渲染和布局引擎

Game engine
shakiba/stage.jspiqnt.com/stage.js/stage-js

README

Stage

Stage.js是一个2D的HTML5 Javascript库，用于跨平台游戏开发，它量轻，快速，且开源。

中文手册

介绍


Canvas是HTML游戏开发中的图形元素，但它只支持绘图接口，但它没有任何可以像DOM那样支持你应用程序操作的数据模型，你必须手动绘制你的应用程序，并且管理渲染循环才可以“玩”它。再有，鼠标事件也仅仅在整个的画布层级上可用，它们也需要被手动处理。

Stage.js提供了类似于DOM的树型数据模型，来操作你的应用程序，且在内部管理渲染循环及应用程序的绘制，它也处理且向目标树节点，发布鼠标及触摸事件。一个Stage.js应用包含了许多的树节点，每个节点都相对于它的父级节点定位（变型），且拥有0/1/或更多个图像纹理。

每次渲染循环都包含了激活及绘制树节点，在激活节点时，会将它们调节为最近一次更新（的样子），然后在绘制每个节点时，会按照它们的“钉”对它们进行转换，再绘制它们的纹理。

渲染在它没有变化时仍然被保留了下来，且为暂停状态。

举例


  1. ```js
  2. // Create new app
  3. Stage(function(stage) {

  5.   // Set view box
  6.   stage.viewbox(300, 200);

  8.   // Create an image and append it to stage
  9.   var box = Stage.image('box').appendTo(stage);

  11.   // Align box to center
  12.   box.pin('align', 0.5);

  14.   // On mouse click...
  15.   box.on('click', function(point) {
  16.     // ...tween scale values of this node
  17.     this.tween().ease('bounce').pin({
  18.       scaleX : Math.random() + 0.5,
  19.       scaleY : Math.random() + 0.5
  20.     });
  21.   });
  22. });

  24. // Adding a texture
  25. Stage({
  26.   image : 'sample.png',
  27.   textures : {
  28.     box : { x : 0, y : 0, width : 30, height : 30 }
  29.   }
  30. });
  31. ```


安装


下载

项目发布页面中提供了最新版本。

使用NPM安装


  1. ```
  2. npm install stage-js --save
  3. ```

使用Bower安装


  1. ```
  2. bower install stage-js --save
  3. ```


用法


在浏览器端使用


在你的应用程序之前，将适合的构建文件，从dist目录中包含到你的HTML页面上，例如：


  1. ```html
  2. <script src="path/to/stage.web.min.js"></script>
  3. <script src="path/to/your-app.js"></script>
  4. ```

Browserify, CommonJS, Node.js


通常，最好在HTML页面中直接包含浏览器构建文件，但也可以使用CommonJS require，例如：
  1. ```js
  2. var Stage = require('stage-js/platform/web');
  3. ```

有关其他可用模块，请参阅平台目录。


资源


Stage.js 介绍  by Baljeet Rathi, SitePoint

中文手册  by Villor 紫刃


接口文档


应用程序

应用程序就是通过Stage()的回调函数来创建的，库会先调用，创建并初始化所有包含的组件，并会在应用程序根节点上调用所提供的（回调）函数，然后将容器显示出来（通常为一个Canvas元素）。

  1. ```javascript
  2. // Create and start an application
  3. Stage(function(stage, display) {

  5.   // Set viewbox for stage, see pinning for valid modes
  6.   stage.viewbox(width, height, mode = 'in-pad');

  8.   // Listen to view port resize events
  9.   stage.on('viewport', function(viewport) {
  10.     // `viewport` attributes are `width`, `height` and `ratio`
  11.   });

  13.   // Pause playing
  14.   stage.pause();

  16.   // Resume playing
  17.   stage.resume();
  18. });
  19. ```


Tree Model 树模型


每个应用都包含了一个树，树的根节点（由程序）作为阶段提供。


  1. ```javascript
  2. // Create a new node instance (with no textures)
  3. var node = Stage.create();

  5. // Append/prepend child to parent's children (accepts array)
  6. parent.append(child);
  7. parent.prepend(child);

  9. // Append/prepend child to parent's children
  10. child.appendTo(parent);
  11. child.prependTo(parent);

  13. // Insert sibling after/before child (accepts array)
  14. child.insertNext(sibling);
  15. child.insertPrev(sibling);

  17. // Insert sibling after/before child
  18. sibling.insertAfter(child);
  19. sibling.insertBefore(child);

  21. // Remove child from its parent
  22. child.remove();

  24. // Remove child from parent (accepts array)
  25. parent.remove(child);

  27. // Remove all of parent's children
  28. parent.empty();

  30. // Get parent's first/last (visible) child
  31. parent.first(onlyVisible = false);
  32. parent.last(onlyVisible = false);

  34. // Get immediate parent
  35. child.parent();

  37. // Get child's next/prev (visible) sibling
  38. child.next(onlyVisible = false);
  39. child.prev(onlyVisible = false);

  41. // Get node's visiblity
  42. node.visible();
  43. // Set node's visiblity
  44. node.visible(visible);
  45. node.hide();
  46. node.show();

  48. // Iterate over parent's children, child can not be removed
  49. for (var child = parent.first(); child; child = child.next()) {
  50.   // use child
  51. }

  53. // Iterate over parent's children, child can be removed
  54. var child, next = parent.first();
  55. while (child = next) {
  56.   next = child.next();
  57.   // use child
  58. }

  60. // Visit node's sub-tree including node itself
  61. node.visit({
  62.   start : function(node) {
  63.     return skipChildren;
  64.   },
  65.   end : function(node) {
  66.     return stopVisit;
  67.   },
  68.   reverse : reverseChildrenOrder = false,
  69.   visible : onlyVisibleNodes = false
  70. });
  71. ```


Game Loop 游戏循环

每次渲染循环都包含了激活及重绘应用程序树。应用程序及它的节点都可以在激活时被更新，根据应用程序的活动性，下边有三种在激活后不同方式的后续行为：


如果至少有一个节点被触及，那个整个应用程序树都被重绘，且游戏循环会继续。
如果没有节点被触及，但至少有一个激活函数返回了true那么游戏循环会继续，但会保持之前的绘制状态。
如果没有节点被触及，也没有任何一个激活函数返回true那么应用程序会暂停，直到它被直接或间接地触及。

节点可以被直接触及，使用node.touch()方法，但通常它们都是被其它动作间接触及的，比如说定位或树的操作。


Nodes can be touched directly by calling node.touch() but usually they are touched indirectly by other actions such as pinning or tree manipulation.

  1. ```javascript
  2. // Register a function to be called on ticking
  3. node.tick(function(millisecElapsed) {
  4.   return continueGameLoop;
  5. }, beforeChildren = false);

  7. // Touch node
  8. node.touch();
  9. ```


Pinning 定位

定位指定了一个节点如何附加在它的父节点上，定位包含了尺寸、转换、定位及透明度。


  1. ```javascript
  2. // Get a pinning value
  3. node.pin(name);

  5. // Set a pinning value
  6. node.pin(name, value);

  8. // Set one or more pinning values
  9. node.pin({
  10.   name : value,
  11.   ...
  12. });
  13. ```

当nameX等于nameY时，就可以简短地使用name来代替它们。

尺寸

对于一些节点来说，比如说图像、字符串、行和列，尺寸的设置是自动进行的

  1. ```javascript
  2. node.pin({
  3.   height : height,
  4.   width : width
  5. });

  7. // Shortcut for setting size:
  8. node.size(width, height);
  9. node.width(width);
  10. node.height(height);

  12. // Shortcut for getting size:
  13. node.width();
  14. node.height();
  15. ```

转换

转换包含了缩放、错切及旋转。转换要应用在缩放和错切之后。

  1. ```javascript
  2. node.pin({
  3.   scaleX : 1,
  4.   scaleY : 1,
  5.   skewX : 0,
  6.   skewY : 0,
  7.   rotation : 0
  8. });

  10. // Shortcut for setting transformation:
  11. node.scale(x, y = x);
  12. node.scale({ x : x, y : y });
  13. node.skew(x, y = x);
  14. node.skew({ x : x, y : y });
  15. node.rotate(angle);
  16. ```

定位

当定位时，自身上的控制点，以父节点上对齐点的位置（作为参照）进行偏移。控制点及对齐点定义为width宽或height高的比例，0代表左上，1代表右下（同CSS中的background-position的关键字left/top/bottom/right的意义）。如果没指定的话，控制点默认就是对齐点的值。

  1. ```javascript
  2. node.pin({
  3.   alignX : 0,
  4.   alignY : 0,
  5.   handleX : 0,
  6.   handleY : 0,
  7.   offsetX : 0,
  8.   offsetY : 0
  9. });

  11. // Shortcut methods for setting positioning:
  12. node.offset(x, y);
  13. node.offset({ x : x, y : y });
  14. ```

默认轴对齐包围盒（AABB盒）是要在转换后才使用定位的，但也可能会使用未转换的盒来设置枢纽定位。枢纽定位用未转换的宽高来定义，它被用作自身的缩放、错切及旋转的中心点。


  1. ```javascript
  2. node.pin({
  3.   pivotX : 0,
  4.   pivotY : 0
  5. });
  6. ```

透明度

透明度既可以应用在节点纹理及子树节点上，又可以只应用在节点纹理自己上。

  1. ```javascript
  2. node.pin({
  3.   alpha : 1,
  4.   textureAlpha : 1
  5. });

  7. // Shortcut methods for setting transparency:
  8. node.alpha(alpha);
  9. node.alpha(alpha, textureAlpha);
  10. ```

缩放至

缩放到新的宽高，如果设置了按比例缩放，可以使用的模式有：
- in: 最大化缩放，保持各边缘在scaleWidth和scaleHeight（下边都使用“指定的尺寸”）的里边
- in-pad: 比较像in模式，但均匀地将整个节点填充到指定的尺寸里边
- out: 最小化缩放，各边缘保持在指定的尺寸之外
- out-crop: 像out一样，但是会均匀地剪裁画面到指定的尺寸

  1. ```javascript
  2. node.pin({
  3.   scaleMode : mode,
  4.   scaleWidth : width,
  5.   scaleHeight : height
  6. });

  8. // Shortcut method:
  9. node.scaleTo(width, height, mode);
  10. ```


事件

事件监听器可以用来在节点上注册及解注册（事件），监听器是在有事件发布在节点上时被调用的。有些事件可以被发布在多个节点上，但事件却不会传播（冒泡）。

  1. ```javascript
  2. // Register a listener to node
  3. // Event `name` can be one or an array of strings or spaced separated strings
  4. node.on(name, listener);

  6. // Unregister a listener from node.
  7. node.off(name, listener);

  9. // Get listeners registered to node
  10. // Returns an array or undefined
  11. node.listeners(name);

  13. // Call listeners with args
  14. // Returns number of listeners called
  15. node.publish(name, args);
  16. ```


鼠标和触摸

本地的鼠标及触摸事件可以被捕获、处理及发布到应用程序的节点上，节点接收局部坐标的鼠标事件，也就是鼠标相对于节点的左上角的指定的位置

  1. ```javascript
  2. // Add click listener to node
  3. node.on('click', function(point) {
  4.   // point.x and point.y are relative to this node left and top
  5.   // point.raw is original event
  6. });
  7. ```

创建语法单击事件并将其发布到节点，而不是本机单击事件。

除了标准事件类型之外，还支持语法mousecancel事件类型，该类型类似于touchcancel，但在mousedown后面没有mouseup时发布。

  1. ```javascript
  2. // Mouse events:
  3. Stage.Mouse.CLICK = 'click';
  4. Stage.Mouse.START = 'touchstart mousedown';
  5. Stage.Mouse.MOVE = 'touchmove mousemove';
  6. Stage.Mouse.END = 'touchend mouseup';
  7. Stage.Mouse.CANCEL = 'touchcancel mousecancel';
  8. ```


纹理

纹理是可绘制的对象，树节点会使用它，来在画布表面绘制图像。


纹理图集


纹理图集（精灵图）包含了命名为纹理的一个集合，在应用程序中，它通过名称来被引用。

图集通常使用静态图像文件来建立，图集中的图像引用是自动预调用的。


  1. ```javascript
  2. // Adding texture atlas
  3. Stage({
  4.   name : 'mario', // optional
  5.   image : {
  6.     src : 'mario.png',
  7.     ratio : 1, // optional, for high-res images
  8.   }
  9.   textures : {
  10.     stand : { x : 0,   y : 0, width : 40, height : 60 },
  11.     walk : [
  12.       { x : 40,  y : 0, width : 40, height : 60 },
  13.       { x : 80,  y : 0, width : 40, height : 60 },
  14.       { x : 120, y : 0, width : 40, height : 60 }
  15.     ],
  16.     number : {
  17.       '0' : { x : 0,  y : 60, width : 10, height : 14 },
  18.       '1' : { x : 10, y : 60, width : 10, height : 14 },
  19.       '2' : { x : 20, y : 60, width : 10, height : 14 },
  20.       '3' : { x : 30, y : 60, width : 10, height : 14 },
  21.       '4' : { x : 40, y : 60, width : 10, height : 14 },
  22.       '5' : { x : 50, y : 60, width : 10, height : 14 },
  23.       '6' : { x : 60, y : 60, width : 10, height : 14 },
  24.       '7' : { x : 70, y : 60, width : 10, height : 14 },
  25.       '8' : { x : 80, y : 60, width : 10, height : 14 },
  26.       '9' : { x : 90, y : 60, width : 10, height : 14 }
  27.     }
  28.   }
  29. });

  31. Stage.image('mario:stand');

  33. Stage.anim('mario:walk').play();

  35. Stage.string('mario:number').value(100);
  36. ```

如果图像的src以./开头的话，它会被解释成相对于当前脚本URL的位置


图片

图片就是带有一种纹理的节点

  1. ```javascript
  2. // Create a new image instance
  3. var image = Stage.image(texture);

  5. // Change image texture
  6. image.image(texture);

  8. // Tile/Stretch image when pinning width and/or height
  9. // To define borders add top, bottom, left and right to texture
  10. image.tile();
  11. image.stretch();
  12. ```


动画

动画或anim对象是带有纹理数组的节点，纹理被用作帧。

  1. ```javascript
  2. // Create a new anim instance
  3. var anim = Stage.anim(textures, fps = 15);

  5. // Get or set animation frame-per-second
  6. anim.fps();
  7. anim.fps(fps);

  9. // Set animation frames, `textures` can be an array or a texture selector
  10. anim.frames(textures);

  12. // Go to n-th frame
  13. anim.gotoFrame(n);

  15. // Move n frames forward (or backward if n is negative)
  16. anim.moveFrame(n);

  18. // Get number of frames
  19. anim.length();

  21. // Start playing (from `frameName` if specified)
  22. anim.play(frameName = undefined);

  24. // Stop playing (and jump to `frameName` if specified)
  25. anim.stop(frameName = undefined);

  27. // Play `repeat * length` frames and then stop and call `callback`
  28. anim.repeat(repeat, callback = null);
  29. ```


字符串动画

字符串是一行图片，它使用字符串值中的每个字符（或数组值中的元素）来动态地选择帧。

  1. ```javascript
  2. // Create a new string instance with frames
  3. var string = Stage.string(frames);

  5. // Set frames, a string referencing a map in an atlas
  6. string.frames("digits");

  8. // Set frames, a map with textures as values and frame names as keys
  9. string.frames({
  10.   '0' : zeroTexture,
  11.   '1' : oneTexture,
  12.   ...
  13. });

  15. // Set frames, a function which takes a char (or item) and returns a texture
  16. string.frames(function(char) {
  17.   // create a texture for char
  18.   return texture;
  19. });

  21. // Set value, it can be a string (or an array)
  22. // Characters (or items) are used to select frames and create a row of images
  23. string.value(value);

  25. // Get assigned value
  26. string.value();
  27. ```


行和列

行/列也是一种节点，用来组织它的子元素，呈现横向/纵向的序列。

  1. ```javascript
  2. // Create a new row/column
  3. var row = Stage.row(childrenAlignY = 0);
  4. var column = Stage.column(childrenAlignX = 0);

  6. // Make node a row/column
  7. node.row(childrenAlignY = 0);
  8. node.column(childrenAlignX = 0);

  10. // Add spacing between row/column cells
  11. node.spacing(space);
  12. ```


盒（试验中）

盒会重新调整尺寸以包裹它的子元素。它可以被用来平铺/拉伸图像，来创建一个变化尺寸的元素，比如说窗口或按钮。


  1. ```javascript
  2. // Create a new box
  3. var box = Stage.box();

  5. // Make node a box
  6. node = node.box();
  7. ```


补间动画

补间动画是应用在平滑转换的定位值上的。

  1. ```javascript
  2. // Create a tweening entry
  3. // When `append` is true new entry is appended to current entries otherwise replaces them
  4. var tween = node.tween(duration = 400, delay = 0, append = false);

  6. // Set pinning values and start tweening
  7. // Pinning shortcut methods, such as `.scale()`, can also be used
  8. tween.pin(pinning);

  10. // Set easing for tweening, it can be either a function or an identifier
  11. // defined as 'name[-mode][(params)]', for example 'quad' or 'poly-in-out(3)'
  12. // Names: linear, quad, cubic, quart, quint, poly(p), sin/sine,
  13. //        exp, circle/circ, bounce, elastic(a, p), back(s)
  14. // Modes: in, out, in-out, out-in
  15. tween.ease(easing);

  17. // Set duration in milliseconds
  18. tween.duration(ms);

  20. // Set delay in milliseconds
  21. tween.delay(ms);

  23. // Callback when tweening is done
  24. tween.done(function() {
  25.   // this === node
  26. });

  28. // Remove this node when tweening ends
  29. tween.remove();

  31. // Hide this node when tweening ends
  32. tween.hide();

  34. // Create and chain a new tweening to this entry
  35. var nextTween = tween.tween(duration = 400, delay = 0);
  36. ```


全局方法

  1. ```javascript

  3. // Create a new app
  4. Stage(function(stage, display) { });

  6. // Create and preload a texture atlas
  7. Stage({ });

  9. // A function to be called before starting any app
  10. // Can be used for preloading application assets
  11. Stage.preload(function(done) {
  12.   // Call `done` when loaded or failed
  13.   done(error);
  14. });

  16. // Preload and execute a JS file
  17. // URLs starting with `./` are resolved relative to current script URL
  18. Stage.preload(src);

  20. // Pause playing all applications
  21. Stage.pause();

  23. // Resume playing all applications
  24. Stage.resume();
  25. ```


发展

要尝试使用实时生成的示例，请运行以下命令并检查要在浏览器中打开的URL的输出：
  1. ```
  2. npm run dev
  3. ```


许可证

Copyright 2020 Ali Shakiba http://shakiba.me/stage.js  
根据MIT许可证提供