$.gameQuery.Animation

gameQuery允许你定义动画(animations) . Animations是由一张包含了多帧(frame)的图片, 就像 css sprite那样. 动画本身并不会存在直到它与一个精灵相联系. 下面是动画可以拥有的属性:

• imageURL: 图片的URL地址
• numberOfFrame: 在animation中帧(frame)的总数 (例如, 当你需要15帧尺寸均为10×10的精灵, 那么你的图片总的尺寸是10×150或者 150×10[取决于你的帧是纵向排列还是横向排列])
• delta: 一帧的宽度[横向排列帧] /一帧的高度[纵向排列] (总之取决于type的类型)
• rate: 帧之间的间隔时间(毫秒)
• type:动画类型, 可以由下面的值组合, 可以用”|”隔开:
  • $.gameQuery.ANIMATION_VERTICAL, 帧之间是在垂直方向堆叠起来的
  • $.gameQuery.ANIMATION_HORIZONTAL, 帧之间是水平排列的
  • $.gameQuery.ANIMATION_ONCE, 如果你不希望动画重复播放的话
  • $.gameQuery.ANIMATION_CALLBACK, 动画每播完一次就执行指定的函数
  • $.gameQuery.ANIMATION_MULTI, 如果你的图片文件中包含了多个动画(if your image file contain more than one animation side by side)
  • $.gameQuery.ANIMATION_PINGPONG, 动画播放完最后一帧后, 并不从头开始下一轮播放, 而是反向播放
• distance: 如果type类型设置为ANIMATION_MULTI, distance表示图片文件中帧序列之间的距离(the distance between two image when using multi-animations)
• offsetx: 在x轴方向, 图片中第一帧与x轴起点的距离(采用的是精灵序列sprite-sheets)
• offsety: 在y轴方向, 图片中第一帧与y轴起点的距离(采用的是精灵序列sprite-sheets)

例子:

playground(options)

这个函数定义了用来显示游戏的div框. 所有通过gameQuery添加的对象, 实际上是在这个div元素上添加子元素. 如果css选择表达式的结果有多个, 那么只有第一个结果会被采用.

Options可以包含的键值:

• height: 游戏展示区域的高度(默认值是320)
• width: 游戏展示区域的宽度(默认值是480)
• refreshRate: 刷新速率, 以毫秒为单位(默认值是30)

例子:

playground()

无参数调用playground(), 将会返回当前playground.

startGame(function)

这个函数将会通过预加载资源和开启游戏主循环(start the main loop)来使得游戏进入就绪状态. 如果有一个函数类型的参数, 那么这个函数会在所有资源都加载完毕时被调用.

example:

registerCallback(function, rate)

这个函数可以使注册函数以定时间隔被调用. 参数rate表示函数被前后两次调用的时间间隔.

如果作为参数的那个函数返回了一个整数值的话, 那么这个整数值将被作为新rate值. 如果函数返回的是布尔值’false’, 这个注册函数将不会被再次调用.

addSprite(name, options)

这个函数会在被选择元素上增加一个精灵(sprite). 这个元素可以使playground, 一个精灵或者其他sprite. 任何通过这种方法创建增加的sprite会自动开始播放动画. 精灵会保持hidden直到start()函数被调用.

Options可以包含的值:

• animation: 一个动画
• height: 精灵(sprite)的高度(默认值是32)
• width: 精灵(sprite)的宽度(默认值是32)
• posx: 在x轴上的位置(默认值是0)
• posy: 在y轴上的位置(默认值是0)
• callback: 在动画播放结束时回调函数将被调用. (只有当动画类型是 $.gameQuery.CALLBACK才能设置)

例子:

addGroup(name, options)

这个函数的行为方式与addSprite几乎相同, 唯一的区别是它创建的是透明的精灵(group主要用来包含其他组).

Options可以包含的值:

• overflow: 当元素超出组(group)时是否可见(默认值是visible, 可见)
• height: 组(group)的高度(默认值是32)
• width: 组(group)的宽度(默认值是32)
• posx: 在x轴上, 组的位置(默认值是0)
• posy: 在y轴上, 组的位置(默认值是0)

例子:

addTilemap(name, tileDescription, animationList, options)

注:tilemap应该是那种由各种方块构造而成的地图, RPG小游戏中很常见 这个函数通过动画列表(animationList)与排序动画的地砖描述(tileDescription). animationList可以是动画数组, 或者multi-animation. tileDescription可以使一个整数数组, 数组中的值表示animationList中的动画索引(或者multi-animaiton索引) 或者是一个将x和y索引作为参数, 并返回动画索引的方法.(or a function taking as parameter a x and y index and returning the index of the animation for this point) 通过这个方法创建的砖块(Tiles)赋予了类名class “tileType_x”, 其中x是动画索引值(这样做方便碰撞检测). 备注:如果tilemap变形了话(旋转、缩放), 这就不能起作用了.(Remark: this doesn’t work if the tilemap is transformed (rotation or scalling))

Options可以包含的值:

• sizex: 砖块(tiles)的列数
• sizey: 砖块(tiles)的行数
• height: 单个砖块(tiles)的高度
• width: 单个砖块(tiles)的宽度
• posx: x轴位置(默认值是0)
• posy: y轴位置(默认值是0)

例子:

setAnimation(animation, callback)

这个函数能改变调用者对象的动画(animation). 这个调用者应该是个精灵(sprite). 参数Callback是函数类型, 它会在动画播放完成时被调用. 这是个可选参数, 只有当动画类型是$.gameQuery.CALLBACK才能被使用. 当无参数调用这个函数, 将会移除调用者所关联的动画.

如果当前关联动画是一个mutli-animations类型, 那么参数 animation可以是multi-animations动画中的任何一个动画的索引值.

pauseAnimation()

使得被选择对象的动画停在当前帧(frame). 如果动画只有一帧或者动画已经暂停, 那么函数不起作用.

resumeAnimation()

如果被选择对象的动画已经暂停, 那么恢复它. 如果动画并没有暂停, 那么函数不起作用.

xyz(x, y, z, relative)

设置sprite/group/tilemap的坐标. 如果参数relative被设置为true, 那么参数value被在当前位置上叠加. 如果无参数调用这个函数, 将会返回对象object {x: x-coordinate, y: y-coordinate, z: z-coordinate}.

xy(x, y, relative)

设置sprite/group/tilemap的坐标. 如果参数relative被设置为true, 那么参数value被在当前位置上叠加. 如果无参数调用这个函数, 将会返回对象object {x: x-coordinate, y: y-coordinate, z: z-coordinate} 由于取得值z并不需要花费多少成本, 所以值z也在返回值当中.

x(value, relative)

设置sprite/group/tilemap的x轴坐标. 如果参数relative被设置为true, 那么参数value被在当前位置上叠加. 如果无参数调用这个函数, 将会返回x轴坐标值(x轴坐标值x-coordinate对应于css中的”left”属性).

y(value, relative)

设置sprite/group/tilemap的y轴坐标. 如果参数relative被设置为true, 那么参数value被在当前位置上叠加. 如果无参数调用这个函数, 将会返回y轴坐标值(y轴坐标值y-coordinate对应于css中的”top”属性).

z(value, relative)

设置sprite/group/tilemap的z轴坐标. 如果参数relative被设置为true, 那么参数value被在当前位置上叠加. 如果无参数调用这个函数, 将会返回z轴坐标值(z轴坐标值z-coordinate对应于css中的”z-index”属性).

wh(w, h, relative)

设置sprite/group/tilemap的宽度和高度. 如果参数relative被设置为true, 那么参数value被在当前尺寸上叠加. 如果无参数调用这个函数, 将会返回对象object {w: width, h: height}.

w(value, relative)

设置sprite/group/tilemap的宽度. 如果参数relative被设置为true, 那么参数value被在当前尺寸上叠加. 如果无参数调用这个函数, 将会返回宽度值.

h(value, relative)

设置sprite/group/tilemap的高度. 如果参数relative被设置为true, 那么参数value被在当前尺寸上叠加. 如果无参数调用这个函数, 将会返回高度值.

collision(filter)

这个函数检测返回那些与调用对象相碰撞的对象, 需要检测碰撞的对象通过过滤器(css选择器)选定.

例子:

setLoadBar(id, width, callback) 在0.5版本中弃用

这个函数指定div来显示载入进度条. 当载入列表中的每个条目被载入完成, 这个以当前载入进度百分比作为参数函数被调用, div本身也会从0开始到它宽度慢慢显示.

loadCallback(callback)

这个函数是一个回调函数, 它需要使用当前载入进度(loading progress)百分比作为参数.

addSound(sound, add) 你需要包含sound wrapper 才能使这个函数生效

这个函数可以为当前对象添加相关联的声音. 如果这个对象之前已经有关联的对象的话, 要是参数add是true, 新的声音将会替代之前的声音; 否则两个声音都会与当前对象相关联.

playSound() 你需要包含sound wrapper 才能使这个函数生效

这个函数会使那些与所选元素(可以有多个)关联的声音开始播放.

stopSound() 你需要包含 sound wrapper 才能使这个函数生效

这个函数会使那些与所选元素(可以有多个)关联的声音停止.

pauseSound() 你需要包含sound wrapper 才能使这个函数生效

这个函数会使那些与所选元素(可以有多个)关联的声音暂停.

muteSound(mute) 你需要包含sound wrapper 才能使这个函数生效

这个函数会使那些与所选元素(可以有多个)关联的声音静音, 或者使全部声音静音, 如果没有指定元素. 如果你传递参数false, 会解除静音.

roate(angle) 支持的浏览器: firefox > 3.5, safari > 3.1, chrome, internet explorer > 5.5

这个函数会在顺时针方向旋转所选元素(可以有多个). 传递的参数是角度值. 目前使用这个函数会导致碰撞检测失效(The usage of this funciton breaks the collison detection for now !)

scale(ratio) 支持的浏览器: firefox > 3.5, safari > 3.1, chrome, internet explorer > 5.5

这个函数会改变所选元素(可以有多个)的比例. 传递的参数是一个比值: 1.0 = 原始尺寸, 0.5 = 一半尺寸, 2.0 = 两倍尺寸. 目前使用这个函数会导致碰撞检测失效(The usage of this funciton breaks the collison detection for now !)

flipv(value)

如果参数是true, 这个函数会垂直翻转精灵(sprite), 如果没有指定参数, 并不执行翻转. 如果参数是false, 会使精灵在垂直方向返回正常状态.

fliph(value)

如果参数是true, 这个函数会水平翻转精灵(sprite), 如果没有指定参数, 并不执行翻转. 如果参数是false, 会使精灵在水平方向返回正常状态.