// 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
    });
  });
});

// Adding a texture 添加纹理
Stage({
  image : 'sample.png',
  textures : {
    box : { x : 0, y : 0, width : 30, height : 30 }
  }
});

<script src="path/to/stage.web.min.js"></script>
<script src="path/to/your-app.js"></script>

var Stage = require('stage-js/platform/web');
See platform directory for other available modules.

// Create and start an application  创建并启动一个应用程序
Stage(function(stage, display) {

  // 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`
  });

  // Pause playing
  // 暂停游戏（渲染）
  stage.pause();

  // Resume playing
  // 恢复暂停
  stage.resume();
});

// Create a new node instance (with no textures)
// 创建一个新节点实例（没有纹理）
var node = Stage.create();

// Append/prepend child to parent's children (accepts array)
// 追加/预加child节点，作为父元素的子节点（接受数组）
parent.append(child);
parent.prepend(child);

// Append/prepend child to parent's children
// 追加/预加child节点作为父元素的子节点
child.appendTo(parent);
child.prependTo(parent);

// Insert sibling after/before child (accepts array)
// 在child节点的后边/前边插入一个邻节点（接受数组）
child.insertNext(sibling);
child.insertPrev(sibling);

// Insert sibling after/before child
// 在child节点的后边/前边插入一个邻节点
sibling.insertAfter(child);
sibling.insertBefore(child);

// Remove child from its parent
// 将child节点从其父节点下移除
child.remove();

// Remove child from parent (accepts array)
// 将child节点从父节点下移除（接受数组）
parent.remove(child);

// Remove all of parent's children
// 删除父节点的所有子节点
parent.empty();

// Get parent's first/last (visible) child
// 获取父节点的第1个/最后1个（可见的）子节点
parent.first(onlyVisible = false);
parent.last(onlyVisible = false);

// Get immediate parent
// 获取即时的父节点
child.parent();

// Get child's next/prev (visible) sibling
// 获取子节点的下一个/上一个（可见的）邻节点
child.next(onlyVisible = false);
child.prev(onlyVisible = false);

// Get node's visiblity
// 获取节点的可见性
node.visible();
// Set node's visiblity
// 设置节点的可见性
node.visible(visible);
node.hide();
node.show();

// Iterate over parent's children, child can not be removed
// 遍历父节点的所有子节点，此种方法下子节点---不能被删除
for (var child = parent.first(); child; child = child.next()) {
  // use child 使用子节点
}

// Iterate over parent's children, child can be removed
// 遍历父节点的所有子节点，此种方法下子节点---可以被删除
var child, next = parent.first();
while (child = next) {
  next = child.next();
  // use child 使用子节点
}

// Visit node's sub-tree including node itself
// 访问节点的子树（包含本节点自己在内）
node.visit({
  start : function(node) {
    return skipChildren;
    //返回值为：是否跳过子节点
  },
  end : function(node) {
    return stopVisit;
    //返回值为：是否停止访问
  },
  reverse : reverseChildrenOrder = false,
  //参数为：是否倒序访问子节点
  visible : onlyVisibleNodes = false
  //参数为：是否只访问可见的子节点
});

// Register a function to be called on ticking
// 注册一个用来激活的函数
node.tick(function(millisecElapsed) {
  return continueGameLoop;
}, beforeChildren = false);

// Touch node 触及节点
node.touch();

// Get a pinning value 获取一个定位值
node.pin(name);

// Set a pinning value 设置一个定位值
node.pin(name, value);

// Set one or more pinning values
// 设置一个或多个定位值
node.pin({
  name : value,
  ...
});

node.pin({
  height : height,
  width : width
});

// Shortcut for setting size:
// 简写的设置尺寸方法
node.size(width, height);
node.width(width);
node.height(height);

// Shortcut for getting size:
// 简写的获取尺寸方法
node.width();
node.height();

node.pin({
  scaleX : 1,
  scaleY : 1,
  skewX : 0,
  skewY : 0,
  rotation : 0
});

// Shortcut for setting transformation:
// 简写的设置转换的方法
node.scale(x, y = x);
node.scale({ x : x, y : y });
node.skew(x, y = x);
node.skew({ x : x, y : y });
node.rotate(angle);

node.pin({
  alignX : 0,
  alignY : 0,
  handleX : 0,
  handleY : 0,
  offsetX : 0,
  offsetY : 0
});

// Shortcut methods for setting positioning:
// 简写的用来设置定位的方法
node.offset(x, y);
node.offset({ x : x, y : y });

node.pin({
  pivotX : 0,
  pivotY : 0
});

node.pin({
  alpha : 1,
  textureAlpha : 1
});

// Shortcut methods for setting transparency:
// 简写的设置透明度的方法
node.alpha(alpha);
node.alpha(alpha, textureAlpha);

node.pin({
  scaleMode : mode,
  scaleWidth : width,
  scaleHeight : height
});

// Shortcut method:
// 简写的方法
node.scaleTo(width, height, mode);

// Register a listener to node
// 给节点注册一个监听器
// Event `name` can be one or an array of strings or spaced separated strings
// 事件`name`可以为一个字符串，或字符串数组，或空格隔开的字符串
node.on(name, listener);

// Unregister a listener from node.
// 解注册节点上的监听器
node.off(name, listener);

// Get listeners registered to node
// 获取节点上注册的监听器
// Returns an array or undefined
// 返回一个数组或 undefined
node.listeners(name);

// Call listeners with args
// 带参数调用监听器
// Returns number of listeners called
// 返回被调用的监听器数量
node.publish(name, args);

// Add click listener to node
// 向节点添加点击事件 
node.on('click', function(point) {
  // point.x and point.y are relative to this node left and top
  // point.x 和 point.y 都相对于节点左上角的
  // point.raw is original event
  // point.raw 是原始的 event 对象
});

// Mouse events: 鼠标事件
Stage.Mouse.CLICK = 'click';
Stage.Mouse.START = 'touchstart mousedown';
Stage.Mouse.MOVE = 'touchmove mousemove';
Stage.Mouse.END = 'touchend mouseup';
Stage.Mouse.CANCEL = 'touchcancel mousecancel';

// Adding texture atlas 添加一个纹理图集
Stage({
  name : 'mario', // optional 可选项
  image : {
    src : 'mario.png',
    ratio : 1, // optional, for high-res images 可选项，用以获取高分辨率的图像
  }
  textures : {
    stand : { x : 0,   y : 0, width : 40, height : 60 },
    walk : [
      { x : 40,  y : 0, width : 40, height : 60 },
      { x : 80,  y : 0, width : 40, height : 60 },
      { x : 120, y : 0, width : 40, height : 60 }
    ],
    number : {
      '0' : { x : 0,  y : 60, width : 10, height : 14 },
      '1' : { x : 10, y : 60, width : 10, height : 14 },
      '2' : { x : 20, y : 60, width : 10, height : 14 },
      '3' : { x : 30, y : 60, width : 10, height : 14 },
      '4' : { x : 40, y : 60, width : 10, height : 14 },
      '5' : { x : 50, y : 60, width : 10, height : 14 },
      '6' : { x : 60, y : 60, width : 10, height : 14 },
      '7' : { x : 70, y : 60, width : 10, height : 14 },
      '8' : { x : 80, y : 60, width : 10, height : 14 },
      '9' : { x : 90, y : 60, width : 10, height : 14 }
    }
  }
});

Stage.image('mario:stand');

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

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

// Create a new image instance 创建一个新的图片实例
var image = Stage.image(texture);

// Change image texture 更改图片实例
image.image(texture);

// Tile/Stretch image when pinning width and/or height
// 在定义宽或高时，平铺/拉伸图片
// To define borders add top, bottom, left and right to texture
// 要定义边框的话，就要给纹理加上top/bottom/left/right属性
image.tile();
image.stretch();

// Create a new anim instance 创建一个anim实例
var anim = Stage.anim(textures, fps = 15);

// Get or set animation frame-per-second
// 获取或设置动画的帧率
anim.fps();
anim.fps(fps);

// Set animation frames, `textures` can be an array or a texture selector
// 设置动画的帧，`textures`可以是数组或纹理选择器（类似CSS选择器）
anim.frames(textures);

// Go to n-th frame 跳转到第n帧
anim.gotoFrame(n);

// Move n frames forward (or backward if n is negative)
// 向前移动n帧（如果是负数就向后n帧）
anim.moveFrame(n);

// Get number of frames 获取帧总数
anim.length();

// Start playing (from `frameName` if specified)
// 开始播放（从`frameName`开始，如果指定了的话）
anim.play(frameName = undefined);

// Stop playing (and jump to `frameName` if specified)
// 停止播放（并且跳到`frameName`帧，如果指定了的话）
anim.stop(frameName = undefined);

// Play `repeat * length` frames and then stop and call `callback`
// 播放 `repeat * length` 帧，并且停止，然后调用`callback`回调方法
anim.repeat(repeat, callback = null);

// Create a new string instance with frames
// 使用 frames 创建一个字符串实例
var string = Stage.string(frames);

// Set frames, a string referencing a map in an atlas 
// 设置帧，字符串所引用的图集的映射
string.frames("digits");

// Set frames, a map with textures as values and frame names as keys 
// 设置帧，一个映射，值为纹理，键为帧名称
string.frames({
  '0' : zeroTexture,
  '1' : oneTexture,
  ...
});

// Set frames, a function which takes a char (or item) and returns a texture
// 设置帧，一个接收单字符（或元素）的函数，它返回一个纹理
string.frames(function(char) {
  // create a texture for char 为这个字符创建一个纹理
  return texture;
});

// Set value, it can be a string (or an array)
// 设置值，它可以是一个字符串（或一个数组）
// Characters (or items) are used to select frames and create a row of images
// 这些字符（或元素）可以用来选择帧，创建一行图片
string.value(value);

// Get assigned value 获取分配到的值
string.value();

// Create a new row/column 创建一个新的行/列
var row = Stage.row(childrenAlignY = 0);
var column = Stage.column(childrenAlignX = 0);

// Make node a row/column 将一个节点变成行/列
node.row(childrenAlignY = 0);
node.column(childrenAlignX = 0);

// Add spacing between row/column cells
// 给行/列的每一个单元添加间隙
node.spacing(space);

// Create a new box 创建一个新的盒元素
var box = Stage.box();

// Make node a box 将一个节点变成盒元素
node = node.box();

// Create a tweening entry 创建一个补间元素
// When `append` is true new entry is appended to current entries otherwise replaces them
// 当`append`是true时，会将一个新元素追加到当前元素集的后边，否则就会替换它们
var 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
// 定位的简写方法，比如`.scale()`也可以使用
tween.pin(pinning);

// Set easing for tweening, it can be either a function or an identifier
// 给补间动画设置缓冲，它可以是一个函数，或一个标识
// defined as 'name[-mode][(params)]', for example 'quad' or 'poly-in-out(3)'
// 定义为 '名称[-模式][(参数)]'，例如'quad' 或 'poly-in-out(3)'
// Names: linear, quad, cubic, quart, quint, poly(p), sin/sine, 
//        exp, circle/circ, bounce, elastic(a, p), back(s)
// 以上这些是可用的名称
// Modes: in, out, in-out, out-in
// 以上这些是可用的模式
tween.ease(easing);

// Set duration in milliseconds
// 设置毫秒值的持续时间
tween.duration(ms);

// Set delay in milliseconds
// 设置毫秒值的延迟时间
tween.delay(ms);

// Callback when tweening is done
// 当补间动画完成后，执行回调
tween.done(function() {
  // this === node
});

// Remove this node when tweening ends
// 当补间动画完成后删除这个节点
tween.remove();

// Hide this node when tweening ends
// 当补间动画完成后隐藏这个节点
tween.hide();

// Create and chain a new tweening to this entry
// 创建一个新的补间动画，并将其链接到本元素上
var nextTween = tween.tween(duration = 400, delay = 0);

// Create a new app 创建一个新应用
Stage(function(stage, display) { });

// 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`
  done(error);
});

// Preload and execute a JS file
// 预调用并执行一个JS文件
// URLs starting with `./` are resolved relative to current script URL
// 以`./`开头的URL地址，会被计算为相对于当前脚本URL的地址
Stage.preload(src);

// Pause playing all applications
// 暂停所有正在播放中的应用程序
Stage.pause();

// Resume playing all applications
// 恢复所有播放中的应用程序
Stage.resume();