APEngine物力引擎简介.doc

APE(物力引擎)
APE，设么是APE呢。APE(Actionscript Physics Engine)是一个ActionScript3写成的物理引擎，用于模拟现实中物体发生的运动和碰撞。它是免费、开源的，遵循MIT协议。
看来特别适用用来做游戏开发，已经有许多很有趣的应用使用这个开发的 。
现提供了Java Port,和C++ SDL Port
官方网址为：http://www.cove.org/ape/
下载地址为：http://www.cove.org/ape/ape_a045.zip（包含两个demo，api，swc文件，和源码）
官网的两个例子:
Demo1: http://www.cove.org/ape/demo1.htm

Demo2: http://www.cove.org/ape/demo2.htm

API地址: http://www.cove.org/ape/docs/api/
下面中文版,网上搜集的
APE中总共才12个类，用起来相当的方便。这12个类的继承关系如下：
目录：
AbstractCollection
Group
Composite
AbstractItem
AbstractConstraint
SpringConstraint
AbstractParticle
RectangleParticle
CircleParticle
WheelParticle
Vector
APEngine

AbstractCollection（子类有：Group和Composite）
此类为群组性的基类。你不应实例化这个类，而应该使用该类的子类。
属性：
constraints 属性
constraints:Array [只读]
一个数组，包含所有被加入到AbstractCollection中的AbstractConstraint类的实例。
particles 属性 
particles:Array [只读]
一个数组，包含所有被加入到AbstractCollection中的AbstractParticle类的实例。
sprite 属性  
sprite:Sprite [只读]
为渲染和增加children而提供的作为容器使用的Sprite。当这个sprite第一次被请求时，这个sprite会自动的加入到APEngine类的全局容器中。
构造函数：
public function AbstractCollection()

方法：
addConstraint () 方法
public function addConstraint(c:AbstractConstraint):void
在收集器中增加一个约束。
参数 c:AbstractConstraint — 被加入的约束.
addParticle () 方法 
public function addParticle(p:AbstractParticle):void
在AbstractCollection中加入一个AbstractParticle 
参数p:AbstractParticle — 被加入的粒子
cleanup () 方法 
public function cleanup():void
调用AbstractCollection每个成员的cleanup（）方法. 当AbstractCollection 从他的父容器中被移除的话，cleanup()方法会自动的被调用。
getAll () 方法   
public function getAll():Array
返回一个数组，这个数组包含被加入到AbstractCollection.中的每一个粒子和约束。
init () 方法 
public function init():void
通过调用每一个成员的init（）方法实例化这个AbstractCollection的每一个成员。
paint () 方法   
public function paint():void
通过调用每一个成员的paint（）方法来渲染 AbstractCollection的每个成员。
removeConstraint () 方法   
public function removeConstraint(c:AbstractConstraint):void
从收集器中删除参数指定的约束。
参数 c:AbstractConstraint — 将被移除的约束。
removeParticle ()方法 
public function removeParticle(p:AbstractParticle):void
从AbstractCollection中移除一个AbstractParticle
参数 p:AbstractParticle — 将被移除的粒子
——————————————————————————————————————————————————————————————————————————————
Group（继承自AbstractCollection）
组可以包含粒子，约束和复合体。组可以被设置为和其他的组进行碰撞检测。
属性：
collideInternal:Boolean [读写] 
决定这个组内的成员彼此是否进行碰撞检测；
collisionList:Array [只读] 
返回一个数组，这个数组包含所有和这个组进行碰撞检测的所有组的实例。
composites:Array [只读] 
返回一个数组，这个数组包含所有加入到这个组的复合体。
构造函数
public function Group(collideInternal:Boolean = false) 
Group是APE中的主要的用于组织的类。一旦创建了组，并把粒子，约束，复合体加入组，那么这些东西也就加入了APEngine。组可以包含粒子，约束和复合体。复合体只能包含粒子和约束。
参数：
collideInternal:Boolean (default = false)
方法：
addCollidable（）方法
addCollidable(g:Group):void
加入一个组的实例与这个组进行碰撞检测。
addCollidableList（）方法
public function addCollidableList(list:Array):void 
加入AbstractCollection实例的数组，让数组中的元素与这个组进行碰撞检测。
addComposite（）方法
public function addComposite(c:Composite):void
在这个组中加入复合体
cleanup()方法
public override function cleanup():void 
调用组的cleanup（）方法将会调用组中所有成员的cleanup（）方法。当组从APEngine引擎中移除时，组的cleanup（）方法会自动的调用。
getAll()方法
public override function getAll():Array 
返回一个包含组中所有粒子，约束，复合体的数组。
init()
public override function init():void 
通过依次调用组中每个成员的init（）方法来初始化组中的每个成员。
paint()方法
public override function paint():void 
Paints 组中的所有成员. 这个方法由APEngine 类自动的调用。
removeCollidable（）方法
public function removeCollidable(g：Group):void 
从这个组的collidable list中移除一个组。
removeComposite（）方法
public function removeComposite(c：Composite):void 
从组中移除复合体。
————————————————————————————————————————————————————————————————————
Composite（继承自AbstractCollection）
复合体可以包含粒子和约束。复合体可以加入到一个组中，就像粒子和约束一样。注意：复合体中的成员彼此不能进行碰撞检测。
属性：
fixed:Boolean [读写]
决定复合体的状态是否固定。设置这个值为true或false将会设置复合体中所有组成的粒子的固定状态为true或false。当复合体中的任何一个粒子的状态为不固定时，这个值返回的都为false。
构造函数：
public function Composite()
方法：
rotateByAngle（）方法
public function rotateByAngle(angleDegrees:Number, center:Vector):void
围绕给定的中心，使复合体旋转参数指定的角度。
rotateByRadian（）方法
public function rotateByRadian(angleRadians:Number, center：Vector):void
围绕给定的中心，使复合体旋转参数指定的弧度。

————————————————————————————————————————————————————————————————————
AbstractItem（子类有：AbstractConstraint和AbstractParticle）
所有约束和粒子的基类
属性
alwaysRepaint 属性 
alwaysRepaint:Boolean [read-write]
为了更好的运行，为了避免不必要的重绘，固定的粒子和弹性约束不需要调用他们的paint（）方法，当一个弹性约束的两端所连接的粒子是固定的话，那么这个弹性约束被认为是固定的。这个属性设置为true的时候，如果粒子和弹性约束的fixed属性也为true的时候，粒子和弹性约束的paint（）方法会被强制调用。如果你想要旋转固定的粒子和弹性约束的话，你应该设置他们的repaintFixed属性为true。如果粒子和弹性约束不是固定的话，alwaysRepaint属性是没有效果的。
sprite 属性
sprite:Sprite [只读]
为渲染和增加children而提供的作为容器使用的Sprite。当这个sprite第一次被请求时，这个sprite会自动的加入到APEngine类的全局容器中。

visible 属性 
visible:Boolean [只写]
决定这个项是否可见。
构造函数
AbstractItem ()
public function AbstractItem()

方法
cleanup () 方法
public function cleanup():void
当包含一个项目（粒子或约束）的组（组或复合体）从APEngine移除的时候，这个方法被自动的调用。
init ()方法
public function init():void
当包含一个项目（粒子或约束）的组（组或复合体）被加到引擎，一个项目（粒子或约束）的复合体被加到组，一个项目（粒子或约束）被加到组或复合体的时候，这个方法会被自动的调用。
paint () 方法 
public function paint():void
这个项目的默认的渲染方法。当APEngine.paint()方法被调用的时候会自动的调用这个方法。
setFill () 方法
public function setFill(color:uint = 0xffffff, alpha:Number = 1):void
设置这个项的填充样式。
setLine () 方法 
public function setLine(thickness:Number = 0, color:uint = 0x000000, alpha:Number = 1):void
设置这个项的样条线的样式。
setStyle () 方法
public function setStyle(lineThickness:Number = 0, lineColor:uint = 0x000000, lineAlpha:Number = 1, fillColor:uint = 0xffffff, fillAlpha:Number = 1):void
设置这个项的样条线和填充。

————————————————————————————————————————————————————————————————————
AbstractParticle类（子类有：CircleParticle，RectangleParticle）（父类是：AbstractItem）
所有粒子的基类
你不应该实例化这个类，而是应该使用这个类的子类。
属性：
center 属性
center:Vector [只读]
返回代表粒子当前位置的向量。
collidable属性
collidable:Boolean [读写]
决定这个粒子是否能和其它的粒子或约束碰撞。默认值为true。
elasticity 属性 
elasticity:Number [读写]
这个粒子的弹性，标准的值在0到1之间。值越大，弹性越大。
在碰撞的过程中，弹性的值是累加的。如果一个粒子的弹性值设为0.4，另一个粒子的弹性制也设为0.4，那么在碰撞的时候弹性值就是0.8了，这和一个粒子的弹性值是0另一个弹性值是0.8产生的效果是一样的。
设置大于1的弹性值（单个粒子大于1或累加后大于1）将会使粒子获得比它原来更多的能量。（尽管现实中不可能，但是这是非常有意思的）
fixed 属性
fixed:Boolean [读写]
决定粒子是否固定。如果粒子是固定的话，早受到力的作用和在碰撞过程中将保持不动。固定的粒子非常适合用来模拟表面。
friction 属性 
friction:Number [读写]
粒子表面的摩擦系数。值必须在0到1之间
0代表没有摩擦（理想光滑），1代表完全的摩擦（像胶水一样）
在碰撞中，摩擦系数也是累加的，但是被限制在1到0之间。例如，如果两个粒子表面的摩擦系数都是0.7的话，这两个粒子之间最终的摩擦力将会是1（完全的粘在一起）
在当前的版本中，仅仅只考虑动态的摩擦。静态的摩擦在下一个版本中可能会得到支持。
当前的版本有一个bug，那就是当和摩擦系数大于0且不固定的粒子碰撞时会得到错误的行为。一个解决的办法就是，只给固定的粒子设置摩擦系数。
抛出错误
—当摩擦系数的值小于0或大于1时抛出 ArgumentError
mass 属性  
mass:Number [只写]
粒子的质量。大于0的值均为有效值。默认情况下所有的粒子的质量均为1.质量属性和粒子形状的大小没有关系。
抛出错误
— 当质量小于0抛出ArgumentError
multisample属性 
multisample:int [读写]
每一次循环中，进行碰撞检测的中间位置值，在一个快速移动的粒子中把这个值适当的设置大一些可以阻止穿透现象的发生。
position属性
position:Vector [读写]
粒子的位置属性。为了一些目的得到粒子的位置是非常有用的。
当你获得粒子的位置的时候，你实际得到的是当前位置信息的一份拷贝。正因为这样，你不能通过修改你从粒子取得的有关位置的向量（Vector）的x参数和y参数来改变粒子的位置。你必须这样做：position=new Vector(100,100),或者你可以用px和py属性来代替。
修改粒子位置的三种方法：改变他的位置（直接），给它设置速度，在它上面应用一个力。设置非固定粒子的位置并不同于把他的fixed属性设置为true那样简单。一个处在它位置属性所指定位置的粒子的行为就好像它连接在一个0长度的弹簧上一样。
px属性 
px:Number [读写]
粒子的x坐标
py 属性   
py:Number [读写]
粒子的y坐标
velocity属性   
velocity:Vector [读写]
粒子的速度。如果你想改变粒子的运动，你应该要么用这个属性，要么用addForce（）方法。一般来说，addForce()方法慢慢的改变物体的运动状态，velocity属性适合瞬间的给物体设置一个速度来改变物体的运动状态（例如抛出物体）。
方法：
addForce () 方法 
public function addForce(f:Vector):void
给粒子加一个力。当应用这个方法的时候，粒子的质量也考虑在内了，所以对于模拟风之类的效果来说，这个方法是非常适合的。
参数 f:Vector —代表被添加力的向量。
addMasslessForce () 方法   
public function addMasslessForce(f:Vector):void
为粒子添加一个忽略质量的力。当用这个方法的时候，粒子的质量被忽略。在模拟类似于重力的力的情况，这个方法很适合。
参数 f:Vector —代表被添加力的向量。
setDisplay () 方法 
public function setDisplay(d:DisplayObject, offsetX:Number = 0, offsetY:Number = 0, rotation:Number = 0):void
在渲染粒子的时候，分配一个显示对象（DisplayObject）来使用。
update ()方法 
public function update(dt2:Number):void
在APEngine.step()方法中会自动的调用update（）方法。用这个方法整合粒子。
————————————————————————————————————————————————————————————————————
RectangleParticle——》AbstractParticle——》AbstractItem
矩形的粒子

属性
angle 属性 
angle:Number [读写]
矩形粒子旋转的度数。
height 属性   
height:Number [读写] 
矩形粒子的高度。
radian 属性   
radian:Number [读写]
矩形粒子旋转地弧度。
注：尽管矩形粒子可以被旋转，但是它没有角速度。换句话说，在碰撞中，旋转状态不会改变，因旋转而产生的能量也不会应用到碰撞中。
width 属性 
width:Number [属性]
矩形粒子的宽度。

构造函数
RectangleParticle () 
public function RectangleParticle(x:Number, y:Number, width:Number, height:Number, rotation:Number = 0, fixed:Boolean = false, mass:Number = 1, elasticity:Number = 0.3, friction:Number = 0)
参数
x:Number — 初始x位置 

y:Number —初始y位置 

width:Number — 这个粒子的宽度 

height:Number — 这个粒子的高度 

rotation:Number (default = 0) — 这个粒子旋转的弧度. 

fixed:Boolean (default = false) —决定这个粒子是否固定。固定的粒子不受力和碰撞的影响，非常适合作为平面。不固定的粒子受力和碰撞的作用自由的移动 。 
mass:Number (default = 1) — 粒子的质量
elasticity:Number (default = 0.3) — 粒子的弹性. 值越高弹性越大
friction:Number (default = 0) — 粒子表面的摩擦系数
注意：固定的粒子仍然可以改变它的旋转属性。
方法
init () 方法
public override function init):void
建立矩形粒子的视觉表象，当这个矩形粒子的父组（包含该粒子的组）的实例被加到APEngine中、矩形粒子的复合体被加入到组中、矩形粒子被加入到组或复合体中的时候，这个方法会自动的被调用。
paint () 方法 
public override function paint():void
这个矩形粒子默认的渲染方法，这个方法会被APEngine.paint()方法自动的调用。
如果你想要自己定义渲染方法，你可以创建这个类的一个子类，并在子类中覆盖paint（）方法。
————————————————————————————————————————————————————————————————————
CircleParticle——》 AbstractParticle——》AbstractItem
子类：WheelParticle
圆形粒子
属性
radius 属性 
radius:Number [读写]
粒子的半径
构造函数
CircleParticle () 构造器 
public function CircleParticle(x:Number, y:Number, radius:Number, fixed:Boolean = false, mass:Number = 1, elasticity:Number = 0.3, friction:Number = 0)
参数：
x:Number — 这个粒子的初始x位置. 

y:Number — 这个例子的初始y位置. 

radius:Number — 粒子的半径. 

fixed:Boolean (default = false) —决定这个粒子是否固定。 
mass:Number (default = 1) — 粒子的质量. 

elasticity:Number (default = 0.3) — 粒子的弹力，值越大弹力越大。 
friction:Number (default = 0) — 粒子表面的摩擦力。
方法
init () 方法
public override function init():void
建立圆形粒子的视觉表象，当这个圆形粒子的父组（包含该粒子的组）的实例被加到APEngine中、圆形粒子的复合体被加入到组中、圆形粒子被加入到组或复合体中的时候，这个方法会自动的被调用。
paint () 方法 
public override function paint():void
这个粒子默认的渲染方法，这个方法会被APEngine.paint()方法自动的调用。
如果你想要自己定义渲染方法，你可以创建这个类的一个子类，并在子类中覆盖
————————————————————————————————————————————————————————————————————
WheelParticle ——》 CircleParticle ——》 AbstractParticle ——》 AbstractItem
用于模拟轮子行为的粒子
属性
angle 属性 
angle:Number [只读]
轮子旋转的角度
angularVelocity 属性 
angularVelocity:Number [读写]
轮子粒子的角速度。你可以通过修改这个值使轮子粒子旋转起来。
radian 属性 
radian:Number [只读]
轮子旋转的弧度
speed 属性
speed:Number [读写]
轮子粒子的速度，你可以通过修改这个值使轮子旋转。
traction 属性   
traction:Number [读写]
在碰撞中牵引力的大小。这个属性决定了当轮子粒子和其它的粒子接触是到底有多少牵引力作用在轮子粒子上。如果这个值设为0，将不会有牵引力，就好像与轮子接触的平面是完全光滑的那样。这个值应该在0到1之间。
注意：frection（摩擦系数）和traction（牵引力）的行为是不同的。当轮子粒子在一个摩擦系数非常打的平面运动时，轮子粒子的运动速度将非常慢，好像平面上涂满了胶水。
构造函数
WheelParticle () 构造器
public function WheelParticle(x:Number, y:Number, radius:Number, fixed:Boolean = false, mass:Number = 1, elasticity:Number = 0.3, friction:Number = 0, traction:Number = 1)
参数：
x:Number —初始x位置 

y:Number —初始y位置. 

radius:Number — 粒子的半径. 

fixed:Boolean (default = false) — 决定这个粒子是否是固定的。 
mass:Number (default = 1) — 粒子的质量 

elasticity:Number (default = 0.3) — 粒子的弹力。值越大塔里越大。 
friction:Number (default = 0) —粒子表面的摩擦力。 

traction:Number (default = 1) — 粒子表面的牵引力。
注：固定的轮子粒子也可以自由度旋转
方法
init ()方法
public override function init():void
建立粒子的视觉呈现。当粒子被加入到引擎时这个方法自动被调用。
paint () 方法 
public override function paint():void
这个粒子默认的渲染方法。在快速的测试中你应该仅仅用这个默认的paint（）方法。如果你有自己的特殊的要求，你应该自己写一个类，要么让这个类继承APE中的粒子或约束，要么把他们组合在一起。然后在你自己的类中定义你自己的渲染方法。
update () 方法 
public override function update(dt:Number):void
————————————————————————————————————————————————————————————————————
AbstractConstraint（父类是：AbstractItem）（子类有：SpringConstraint）
你不应实例化这个类，而应该使用它的子类。
属性
stiffness 属性 
stiffness:Number [read-write]
是约束变得僵硬，值越大越僵硬。这个值应该在0到1之间。根据运行的情况，这个直设的过高会导致应用不稳定。
————————————————————————————————————————————————————————————————————
SpringConstraint——》 AbstractConstraint ——》 AbstractItem
一个像弹簧的约束用来连接两个物体。
属性
angle属性 
angle:Number [只读]
连接在这个SpringConstraint（弹簧约束）上的两个粒子的位置所构成的角度。你可以在渲染方法中应用这个属性和center属性。
center 属性
center:Vector [只读]
连接在这个SpringConstraint（弹簧约束）上的两个粒子的位置的中心。你可以在渲染方法中应用这个属性和旋转属性。
collidable 属性 
collidable:Boolean [只读]
决定两个粒子之间的区域是否接受碰撞检测。如果这个属性打开的话（即为true），你可以修改rectHeight属性和rectWidth属性来修改接受碰撞检测区域的尺寸大小。
currLength 属性 
currLength:Number [只读]
返回弹簧约束（SpringConstraint）的长度，即两个被链接的粒子的距离。
fixed 属性 
fixed:Boolean [只读]
如果被链接的两个粒子的fixed属性都为true时返回true。
fixedEndLimit 属性 
fixedEndLimit:Number [读写]
当弹簧约束（SpringConstraint）为可接受碰撞的并且两端的粒子只有一个是固定的，这个值将处理固定端粒子附近的碰撞，纠正难以解决的碰撞问题。这个值在0.0到1.0之间。
radian 属性 
radian:Number [只读]
连接在这个SpringConstraint（弹簧约束）上的两个粒子的位置所构成的旋转的值。你可以在你自定义的渲染方法中应用这个属性和center属性。
rectHeight 属性 
rectHeight:Number [读写]
如果collidable属性为true，你可以设置这两个粒子之间能接受碰撞的矩形区域的高度。这个值是大于零的。如果你设置这个值为10，那么碰撞区域矩形的高度为10像素，这个高度与两个连接的粒子的连线垂直的。
rectScale属性
rectScale:Number [读写]
如果collidable属性为true，你可以设置这两个粒子之间能接受碰撞的矩形区域的缩放。有效值在0到1之间。如果你将值设为1，这个碰撞区域将扩展到来被链接的两个粒子处。设置一个较低的值，会使碰撞区域按距离的百分比缩放。这个值设的过大会使碰撞矩形扩张甚至超过两端的粒子。
restLength 属性
restLength:Number [读写]
restLength 属性设置弹簧约束（SpringConstraint）的长度。如果两端的粒子位置没有因受到外力而改变的话，那么这个属性的值等于两端粒子的距离。弹簧约束将总是试着使两个粒子的距离等于这个属性的值。这个值必须大于0.
构造函数
SpringConstraint () 
public function SpringConstraint(p1:AbstractParticle, p2:AbstractParticle, stiffness:Number = 0.5, collidable:Boolean = false, rectHeight:Number = 1, rectScale:Number = 1, scaleToLength:Boolean = false)
参数：
p1:AbstractParticle — 约束所连接的第一个粒子。

p2:AbstractParticle — 约束所连接的第二个粒子。

stiffness:Number (default = 0.5) —弹簧的强度。有效值在0到1之间。低值的效果就像软弹簧，高值的效果如同硬弹簧。 
collidable:Boolean (default = false) — 决定此约束是否接受碰撞检测。

rectHeight:Number (default = 1) —如果这个约束是可接受碰撞检测的，可碰撞的区域的高度可设置为像素值。高度和被链接的两个粒子的连线垂直。 
rectScale:Number (default = 1) —如果这个约束是可接受碰撞检测的，可被碰撞的区域的缩放可被设置为一个0到1之间的值。这个缩放是两个被链接的粒子之间的距离的一个百分数。 
scaleToLength:Boolean (default = false) —如果这个约束是可接受碰撞检测的并且这个值设为true时，可接受碰撞的区域将随着两个粒子的距离而缩放。
方法
init ()方法
public override function init():void
建立弹簧约束的视觉呈现。当此弹簧约束的父组的实例被加到APEngine中、此弹簧约束的复合体被加到组中、次弹簧约束被加到复合体或组中的时候，这个方法会自动的被调用。
isConnectedTo () 方法 
public function isConnectedTo(p:AbstractParticle):Boolean
如果传递给此函数的参数是被链接的两个粒子之一则返回true。
参数 p:AbstractParticle 
返回 Boolean
paint () 方法 
public override function paint():void
这个约束的默认渲染方法。这个方法由APEngine.paint()自动的调用。如果你想要自定义渲染方法，你可以创建一个这个类的子类，并在子类中覆盖paint（）方法。
setCollidable ()方法 
public function setCollidable(b:Boolean, rectHeight:Number, rectScale:Number, scaleToLength:Boolean = false):void
参数：
b:Boolean 

rectHeight:Number 

rectScale:Number 

scaleToLength:Boolean (default = false)
setDisplay ()方法
public function setDisplay(d:DisplayObject, offsetX:Number = 0, offsetY:Number = 0, rotation:Number = 0):void
当渲染这个约束时分配一个显示对象以备使用。
参数
d:DisplayObject 

offsetX:Number (default = 0) 

offsetY:Number (default = 0) 

rotation:Number (default = 0)
————————————————————————————————————————————————————————————————————
Vector类
属性
x 属性 
public var x:Number
y 属性 
public var y:Number

构造函数
Vector () constructor 
public function Vector(px:Number = 0, py:Number = 0)
参数：
px:Number (default = 0) 

py:Number (default = 0)
方法
copy () 方法
public function copy(v:Vector):void
参数：
v:Vector
cross () 方法 
public function cross(v:Vector):Number
参数
v:Vector 
返回：
Number