Traer.physics port to AS3

Long-time Processing users probably remember Traer.physics, one of the first physics libraries for Processing, written in Java by Jeffrey Traer Bernstein. It was widely used long before the incredibly useful and much-larger-in-scope ToxicLibs were around. So what is it? A very simple particle system.

As Jeffrey puts it on his project page:

“All this is supposed to do is let you make particles, apply forces and calculate the positions of particles over time in real-time. Anything else you need to handle yourself”.

And well, this is, in my opinion, the beauty of it. Traer physics is really a lot of fun to play with. Granted, there isn’t a lot provided. A ParticleSystem class. A Particle class. Spring and Attraction (which acts also as repulsion by negating a value). That’s pretty much it. But it’s way more than enough to provide a sandbox to come up in no time with new ideas for interaction. Or cool visuals. Or whatever.

What’s in it?

ParticleSystem

This is where everything starts. It provides a dead easy API. The methods listed below are pretty much all you need to know get started:

• ParticleSystem(gravity:Vector3D, drag:Number); // constructor
• ParticleSystem.makeParticle(mass:Number, position:Vector3D):Particle;
• ParticleSystem.makeSpring(a:Particle, b:Particle, springConstant:Number, damping:Number, restLength:Number):Spring;
• ParticleSystem.makeAttraction(a:Particle, b:Particle, strength:Number, minDistance:Number):Attraction;
• ParticleSystem.tick(t:Number):void; // advances the simulation by an amount of time
• ParticleSystem.addCustomForce(f:Force):void; // this is how you add your custom designed forces that implement Force

Of course, a complete API to add/remove/get/set particles, forces, and various settings is provided (i.e. getSpring, getParticle, removeSpringByReference, removeParticleByReference…).

Particle

Can be fixed or free using Particle.makeFixed() and Particle.makeFree(), and have mass and age properties.

Integrator

Your choice of RungeKuttaIntegrator (more stable, more precise, slower) or ModifiedEulerIntegrator (fast, less precise, at times barely stable).
Hmm… What does stability mean? We’re talking about numerical stability here. The wikipedia entry for the Euler method explains very well what it means. In short, there is a correlation in the magnitude of errors occurring and the time increment used when calling ParticleSystem.tick(t). On top of that, some situations will make the integrator simply fail. Oh no worries. You’ll see… particles supposedly fixed flying around and your entire simulation exploding. Fun times! Ways of controlling your system’s stability include choosing a smaller time increment (slowing down the simulation) and add more drag to the system (making it harder for the particles to freely move).

Force

Spring and Attraction are provided. You are more than encouraged to create your own forces by implementing the Force interface.

The port, some nitty gritty details

Some changes to the API were necessary since ActionScript3 doesn’t allow for method overload. Traer.physics being originally written in Java, well, these were all over. I had to limit the options available.

I also chose not to use the original package custom vector class, since AS3 provides a standard Vector3D. This should make it easier to plug into this package other libraries. That change means the position property of Particle is actually a flash.geom.Vector3D.

ParticleSystem uses vector quantities to store particles and forces. Vector.<Particle>, Vector.<Spring>, Vector.<Attraction>, Vector.<Force> have been used where the original code uses Java’s ArrayList.

Examples

I included a bunch of examples in the package. I will post some explanations regarding some of them shortly. These include an orb web like little toy, a tribute to Yugo’s Wonderwall, and yes, the mandatory cloth simulation.

Oh, you may want to see a little something right away don’t you? Here are 700 free floating particles. Incredibly boring, but so little code was written for that!

What’s missing/What’s next?

Proper ASDocs and unit testing. I’ll try to get that done at some point… Performance tuning/optimization. I’m sure there’s a *lot* of room for improvement. Oh, and more examples!

Remind me again, why porting it?

Quite some time ago I used to play a lot with this package in Processing. I loved it. Some of the little experiments I did at this time… I thought… Damn, I wished Flash could handle that. Now I guess it can. Now, too, Jeffrey released the source code. I had to port over this thing to AS3, mostly for the fond memories I had of it. As a tribute to the good old times where people like Jeffrey, among others, were shaping what Processing is now: the enabler of data visualization for a wide and diverse crowd with only one requirement: a curious mind.

Useful links

Get the source + examples: Github repo
Traer.physics: the original package
Processing
Toxiclibs
http://en.wikipedia.org/wiki/Numerical_stability
http://en.wikipedia.org/wiki/Euler_method
http://en.wikipedia.org/wiki/Runge-Kutta_method