Your First Fisix Application

From Fisix Engine Wiki

Contents 1 Getting Started With Fisix 2 The physics of Fisix 3 My First Fisix Project 4 The Engine Itself 5 Objects Within The World 6 Start Your Engines 7 Putting It All Together

Getting Started With Fisix

The Fisix Engine is a great system for building physics simulations into your project. The Fisix system is an implementation of a Verlet based physics system within ActionScript 3. First you create a FisixEngine, with gravity, forces, and reactions. Next you add objects, and groups of objects, in your application. After creating your objects, you then apply forces to your objects to give them interesting actions and reactions. Before we get started, its important to understand the basic ideas behind any physics system.

The physics of Fisix

Every frame of animation is a new slice of time within the Fisix world. On each slice, each Fisix subsystem iterates over each item within the world. The most important subsystems are:

• Integration
• Collision Detection
• Collision Reaction

Integration

Integration is basically the accumulation of forces upon your objects. Variables for bounce, friction, drag, gravity, and other physical forces that are applied by the user and application are applied to each object. Fisix uses the Verlet integration method (insert information about why verlet is better than other methods).

Collision Detection

Collision Detection is the method with which we determine whether or not something has, is, or is about to collide with an object. This also fixes objects that have collided so that they are not overlapping on each other. Fisix has multiple methods with which to determine whether something has collided, with varying levels of quality/speed tradeoffs.

Collision Reaction

This is the point in which the physics math actually occurs. Collision reaction is what happens when two objects collide. Fisix has two methods for determining the reaction between objects, 'physical' and 'none'. We'll talk more about these methods later.

My First Fisix Project

Of course there is much more to play with, such as applying forces to objects, but this is enough to get started. We'll assume that you've got the FisixEngine.swc file, and a copy of Flex Builder 2.

1. Open up Flex.
2. Choose 'New ActionScript Project'
3. Call your project 'MyFisixDemo' and choose a location for your project (or leave it at the default).

The project will be created, and you'll be given a file like so:

package {
	import flash.display.Sprite;

	public class MyFisixDemo extends Sprite
	{
		public function MyFisixDemo()
		{
		}
	}
}

1. Go to Project-> Properties.
2. Select 'ActionScript Build Path'
3. In the window on the right select the tab 'Library path'
4. Click 'Add SWC...'
5. Navigate to the file FisixEngine.swc (located in the bin folder of this package).

By adding this file, we're adding all the classes required to use the FisixEngine in an already compiled form. Note: Flex Builder will not autocomplete any classes that are included into your swf. You will also have to add your 'import' statements the old-fashioned way, too.

The first thing we need to code is change the swf metadata:

[SWF(width='600',height='400',backgroundColor='0xFFFFFF',frameRate='30')]
public class MyFisixDemo extends Sprite

This will tell the compiler what attributes our swf should have. This removes the dark blue default, and gives us a bigger area to work in.

The Engine Itself

Next we want to create our FisixEngine instance:

//Create an instance of our engine.
var myEngine:FisixEngine = new FisixEngine();

The Fisix Engine (and all its objects) have two different reaction modes: physical and none(the default). No reaction means that physical accuracy of the reaction is not maintained. Physical reaction uses more processing power to simulate friction and bounce. Most importantly, this determines the default reaction mode for each object within the world. Since we are just starting out, we'll just turn on the physical reaction for all objects.

//turn on physical collision reactions
myEngine.setReactionMode(ReactionModes.PHYSICAL);

By default the engine has very little gravity. We're going to tell it to pull down harder. Remember that we mentioned that the first step of the Fisix system is 'integration'. This is the accumulation of forces. When you set the gravity you're setting a constant force on all your objects in a specific direction. In this code:

//set the gravity to pull down at a rate of 1 pixel per second
myEngine.setGravity(0, 1 * stage.frameRate);

We're setting the gravity to a default force equal to numberOfPixels * framesPerSecond.

Objects Within The World

Now that we have an engine to work with, and a basic force applied to all objects (gravity), we can start adding those objects.

//next, add a surface to the engine
var surface1:Surface = myEngine.newSurface(new Vector(0,200),new Vector(500,350),10)
//set the surface's physical properties
surface1.bounce = 0.9;
surface1.friction = 0.5;

This code adds a new surface to the application. A surface is a basic building block. It is simply a line with two points and a thickness. The line's two points are two Vector objects, and the thickness is how thick the object should be. The thickness of surfaces is very important for collision detection, so making your surfaces thicker will make them more resistent to problems with collision detection (not sure this needs to be here, but putting it in so i don't forget).

Surface is a subclass of CollisionObject, the main object class for objects within the world. CollisionObject has many properties that are used on all objects we create within the world.

//add a circle particle to the surface at position 200,100 with a radius of 50 pixels
var particle1:WheelParticle = myEngine.newWheelParticle(200,100,50);
particle1.bounce = 0.7;
particle1.friction = 0.5;		

The WheelParticle is also a subclass of CollisionObject, so we can set the bounce and friction of this object in the same way as the Surface.

Start Your Engines

And now we are ready to set a couple final rendering parameters, and start the FisixEngine.

//turn on primitive rendering
myEngine.setRender(true);
//tell the engine where to render to
myEngine.setRenderGraphics(graphics);

The engine, by default, doesn't actually show anything. By calling setRender(true) on our engine, we can see the basic reactions between objects being drawn as primitive shapes. When you build your application, you'll want to attach DisplayObjects to your various physics objects to give it polish and presence. The setRenderGraphics() call tells the engine which Graphics object to render to when setRender() is true.

//start the engine
myEngine.startEngine(stage.frameRate);

And a call to startEngine() gets things running. You may optionally call the mainLoop() within your onEnterFrame() call. (note: Does this really matter? Is there a preferred method?)

Putting It All Together

package {
	import flash.display.Sprite;
	import com.fileitup.fisixengine.core.FisixEngine;
	import com.fileitup.fisixengine.collisions.ReactionModes;
	import com.fileitup.fisixengine.core.Vector;
	import com.fileitup.fisixengine.particles.WheelParticle;
	import com.fileitup.fisixengine.primitives.Surface;
	
	import flash.display.MovieClip;
	
	[SWF(width='600',height='400',backgroundColor='0xFFFFFF',frameRate='30')]
	public class MyFisixDemo extends Sprite
	{
		public function MyFisixDemo()
		{
			//Create an instance of our engine.
			var myEngine:FisixEngine = new FisixEngine();
			//turn on physical collision reactions
			myEngine.setReactionMode(ReactionModes.PHYSICAL);
			//set the gravity to pull down at a rate of 1 pixel per second
			myEngine.setGravity(0, 1 * stage.frameRate)
			
			//next, add a surface to the engine
			var surface1:Surface = myEngine.newSurface(new Vector(0,200),new Vector(500,350),10)
			//set the surface's physical properties
			surface1.bounce = 0.9;
			surface1.friction = 0.5;
			
			//add a circle particle to the surface at position 200,100 with a radius of 50 pixels
			var particle1:WheelParticle = myEngine.newWheelParticle(200,100,50);
			particle1.bounce = 0.7;
			particle1.friction = 0.5;
			
			//turn on primitive rendering
			myEngine.setRender(true);
			//tell the engine where to render to
			myEngine.setRenderGraphics(graphics);
			
			//start the engine
			myEngine.startEngine(30);
		}
	}
}

This should be enough to get you started upon building your own simulation. Try adding different types of variables to the application. Add a wheel or two, and watch the particles bounce off each other. Change the bounce and friction properties to see how the simulation changes. Try adding negative values to the x gravity force, and watch things roll uphill!