// Create and start an application
// 创建并开始一个应用程序
Stage(function(stage, display) {
  // `stage` is the root node for this application
  // “stage”是此应用程序的根结点
  // `display` is the actual element displaying rendered graphics
  // “display”是渲染图形所呈现的实际元素

  // Pause playing
  // 暂停演示
  stage.pause();

  // Resume playing
  // 恢复演示
  stage.resume();

  // Set viewbox for stage, valid modes are 'in', 'in-pad', 'out' and 'out-crop'
  // 设置舞台的可视区，可用的模式有'in', 'in-pad', 'out' 和 'out-crop'
  stage.viewbox(width, height, mode = 'in-pad');

  // Listen to view port resize events
  // 监听可视区的resize事件
  stage.on('viewport', function(viewport) {
    // `viewport` attributes are `width`, `height` and `ratio`
    // `viewport`有属性`width` `height` 和 `ratio`
  });
});

// Create a new node instance (with no textures)
// 创建一个新的节点实例（不带有材质）
var foo = Stage.create();

// Append/prepend bar to foo's children (accepts array)
// 追加或前追加bar作为foo的子节点（允许数组）
foo.append(bar);
foo.prepend(bar);

// Append/prepend bar to foo's children
// 追加或前追加bar作为foo的子节点
bar.appendTo(foo);
bar.prependTo(foo);

// Insert baz after/before bar (accepts array)
// 在bar后边或前边插入baz（允许数组）
bar.insertNext(baz);
bar.insertPrev(baz);

// Insert baz after/before bar
// 在bar后边或前边插入baz
baz.insertAfter(bar);
baz.insertBefore(bar);

// Remove bar from parent
// 将bar从其父级移除
bar.remove();

// Remove bar from foo (accepts array)
// 将bar从foo中移除（允许数组）
foo.remove(bar);

// Remove all foo's children
// 移除foo的所有子节点
foo.empty();

// Get foo's first/last (visible) child
// 获取foo的第一/最后（可视）子节点
foo.first(onlyVisible = false);
foo.last(onlyVisible = false);

// Get immediate parent
// 获取即时父级
bar.parent();

// Get bar's next/prev (visible) sibling
// 获取bar的下个或前一个（可视）邻节点
bar.next(onlyVisible = false);
bar.prev(onlyVisible = false);

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

// Iterate over foo's children, `child` can not be removed
// 遍历foo的子节点，`child`不可以被移除
for (var child = foo.first(); child; child = child.next()) {
  // use child
  // 使用child
}

// Iterate over foo's children, `child` can be removed
// 遍历foo的子节点，`child`可以被移除
var child, next = foo.first();
while (child = next) {
  next = child.next();
  // use child
  // 使用child
}

// Visit foo's sub-tree including foo
// 访问foo的子树（包含foo本身）
foo.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
// 注册一个在选中时被调用的函数
foo.tick(function(millisecElapsed) {
  return continueGameLoop;
}, beforeChildren = false);

// Touch foo
// 触及foo
foo.touch();

// Get a pinning value
// 获取一个销值
bar.pin(name);
// Set a pinning value
// 设置一个销值
bar.pin(name, value);
// Set one or more pinning values
// 设置一个或更多个销值
bar.pin({
  name : value
});

// Transformation
// 变形
// `rotation` is applied after scale and skew
// `rotation` 要在scale和skew之后应用
bar.pin({
  scaleX : 1,
  scaleY : 1,
  skewX : 0,
  skewY : 0,
  rotation : 0
});

// Size
// 尺寸
// For some nodes, such as images, it is set automatically
// 对于某些节点（比如图片）来说，它是自动设置的
bar.pin({
  height : height,
  width : width
});

// Positioning
// 定位
// For values defined as ratio of width/height, 0 is top/left and 1 is bottom/right
// 值定义为宽比高的比例，0代表顶或左，1代表底或右
bar.pin({
  // Pin point on parent used for positioning
  // 在父级元素上用来定位的销点
  // Defined as ratio of parent's width/height
  // 用父级上的宽高比来定义
  alignX : 0,
  alignY : 0,
  // Pin point on self used for positioning
  // 在自身上用来定位的销点
  // Defined as ratio of AABB or base width/height if pivoted
  // 定义成AABB或基本宽高比的比例（如果转动的话————这句我也不知道啥意思）
  // Defaults to align values
  // 默认值与align值相同
  handleX : 0,
  handleY : 0,
  // Distance from align point on parent to handle point on self in pixel
  // 从父级的align点到自身的handle点的距离（像素值）
  offsetX : 0,
  offsetY : 0,
  // Relative location on self used as scale/skew/rotation center, see handle
  // 用作scale/skew/rotation中心点的自身上的一个相对位置，参照handle
  pivotX : 0,
  pivotY : 0
});
// To summarize it, child's distance from parent's top-left is:
// 概括它，子元素距父级左上角的距离是下边的公式
// align * parentSize - handle * selfSize + offset
// selfSize就是自身的宽或高，parentSize就是父级的宽或高

// Transparency
// 透明度
bar.pin({
  // Transparency applied to self and children
  // 应用到自身及子元素的透明度
  alpha : 1,
  // Transparency applied only to self textures
  // 只应用到自身材质的透明度
  textureAlpha : 1
});

// Scale to new width/height, if mode is set scale proportionally, valid modes are:
// 缩放到新的宽或高，如果模式被设置成按比例缩放，可用的模式有
// 'in': maximum scale while keeps node edges inside scaleWidth/height
// in：最大化缩放，同时保证节点的边缘在缩放尺寸的内部
// 'in-pad': like 'in', but evenly pads node to fill entire scaleWidth/height
// in-pad：像in一样，但是会均匀地将切点平铺，填满缩放尺寸
// 'out': minimum scale while keeps node edges outside scaleWidth/height
// out：最小化缩放，同时保证节点的边缘在缩放尺寸外部
// 'out-crop': like 'out', but evenly crops it to scaleWidth/height
// out-crop：像out一样，但均匀地将它剪裁到缩放尺寸
bar.pin({
  scaleMode : mode,
  scaleWidth : width,
  scaleHeight : height
});

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

// Unregister a listener from foo.
// 注销foo的监听器
foo.off(name, listener);

// Get listeners registered to foo
// 获取foo的已注册监听器
foo.listeners(name);

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

// Add click listener to bar
// 给bar添加一个点击监听器
bar.on(Stage.Mouse.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是原始事件（不知道是不是事件源）
});

// 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
// 创建一个动画实例
var anim = Stage.anim(textures, fps = 15);

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

// Set anim frames, `textures` can be array or a selector
// 设置动画（使用）的帧，`texture`可以是数组或一个选择器
anim.frames(textures);

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

// Move n frames forward or backward if n is negative
// 向前移动n帧，如果n为负则向后移动n帧
anim.moveFrame(n);

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

// Start playing (from `frame`)
// 开始播放（从第`frame`帧）
anim.play(frame = null);

// Stop playing (and jump to `frame`)
// 停止播放（且跳到第`frame`帧）
anim.stop(frame = null);

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

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

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

// Add spacing between row/column cells
// 给行/列增加单元间隙
foo.spacing(space);

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

// Set frames, a string referencing a map in an atlas 
// 设置帧，字符串引用的是一个图集映射（在Texture部分中那个以"0,1,2,3.."定义的材质）
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
  // 为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 box
// 创建一个新盒
var box = Stage.box();

// Make foo a box
// 把foo变成盒
foo = foo.box();

// Create a tweening entry
// 创建一个补间动画入口
// When `append` is true new entry is appended to current entries otherwise replaces them
// 当`append`是真的时候，新的入口就被加到当前的入口中，否则就替换掉当前入口
var tween = foo.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)'
// 定义为 '名称[-模式][(参数)]'，比如……
// 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
// 模式：这段大概跟JQ的easing是一致的，但是几个带参数的不知道是啥意思，而且那个poly没见过
tween.ease(easing);

// Set duration in milliseconds
// 设置动画消耗的毫秒数
tween.duraion(ms);

// Set delay in milliseconds
// 设置动画延迟的毫秒数
tween.delay(ms);

// Callback when tweening is done
// 当补间动画完成后的回调函数
tween.done(function() {
  // this === foo
});

// 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，被处理成从当前脚本文件计算的相对地址
Stage.preload('script.js');

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

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