Blitz3D Intermediates: Blitz-Tokamak Basics
by Bot Builder

What is Blitz-Tokamak?

Blitz Tokamak is a Blitz friendly wrapper written by Sweenie for the excellent Tokamak physics DLL.

You need the blitz wrapper from here
http://www.freewebs.com/sweenie/
and the Tokamak DLL from here
http://www.tokamakphysics.com/

The Tokamak DLL needs to go into your system folder OR your application/source folder.

What can I do with Blitz-Tokamak?

You can create tons of things using blitz-tokamak for physics. It's features include:
  • Very fast physics and collision system
  • Various types of joints with limits
  • Friction model with various amounts of friction for triangles and objects
  • Box, Capsule(called a cylinder), and sphere collisions
  • Various methods of applying force to a rigid body including torques, movement, and force from a point.
  • Support for a static mesh

What are all the TOK*** beginings on all the commands?

These beginnings divide all the commands up into sections:
  • TOKSIM commands are for the tokamak simulator. These commands mostly have to do with setup or global modifications
  • TOKRB commands are for tokamak rigid bodies. These are the things that bounce around etc. You have to make them out of the 3 primitives box, cylinder, and sphere, however you can use these in conjunction to produce more complex things like chairs and tables
  • TOKAB commands are for tokamak animated bodies. These are not affected by physics, and are positioned and rotated by your program. They have to be made out of the tokamak primitives, and like rigid bodies, can have more complex shapes constructed from the geometries. Uses for these are things like moving platforms, doors, gates, traps, etc.
  • TOKGEOM commands are used to modify the properties of the primitives(geometries) used in rigid bodies and animated bodies.
  • TOKJOINT commands are used to construct joints that join together rigid bodies in various ways. They can be used for rag dolls, machinery, traps, etc.

How do I write a blitz-tokamak program?

This is obviously a more complex subject, and the focus of this tutorial.

The first thing to do is to set up the simulator like this:


This sets it up - and gives the vector to use as gravity. In this case, the gravity is down in the y direction by 10. When setting these values keep in mind that the greater your gravity, and the greater the time step(covered later), the more likely objects will have errors, and go through meshs or other objects. This is why you should use blitz picking commands instead of tokamak for fast moving bullets etc.

Now, Tokamak is slightly limited by the fact that it has to know how many various objects you will have before you actually start up the simulation. You can set the following things:

  • TOKSIM_SetRigidBodiesCount - The number of rigid bodies used in the simulation. Defaults to 50
  • TOKSIM_SetAnimatedBodiesCount - The number of animated bodies used in the simulation. Defaults to 50
  • TOKSIM_SetRigidParticleCount - The number of rigid particles. Defaults to 50.
  • TOKSIM_SetControllersCount - The number of controllers. Defaults to 50, however it is not supported so you can set it to 0
  • TOKSIM_SetOverlappedPairsCount - The number of possible overlapped pairs. Defaults to 1225. This would be the maximum if the number of bodies was 100. If you are using a number drastically different, use (TBodies*(TBodies-1))/2 where TBodies is the total number of bodies. This would be the maximum, however you can experiment with setting it lower to save memory(this is used for the collision tables). Unless you're an advanced user, just leave this alone
  • TOKSIM_SetGeometriesCount - The number of primitives used in rigid and animated bodies. Defaults to 50
  • TOKSIM_SetConstraintsCount - The number of constraints in the simulation. defaults to 100. Unless you're an advanced user, just leave this alone
  • TOKSIM_SetConstraintSetsCount - The number of constraint sets in the simulation. Defaults to 100. Unless you're an advanced user, just leave this alone
  • TOKSIM_SetConstraintBufferSize - The size of the constraint solver buffer. Defaults to 2000. Unless you're an advanced user, just leave this alone
  • TOKSIM_SetStaticMeshNodesStartCount - The number of nodes use to store terrain triangles. Defaults to 200. Unless you're an advanced user, just leave this alone
  • TOKSIM_SetStaticMeshNodesGrowByCount - Makes the number of mesh nodes grow by this size if you run out of nodes. Defaults to -1(The nodecount will increase by 100% when growing). Unless you're an advanced user, just leave this alone
So, here's what we have so far:


This sets up the simulator with the appropriate amounts of memory. As you can see, I didn't use TOKSIM_SetOverlappedPairsCount, as the total number of rigid bodies is only 105, not much different from 100, so the default value will be fine.

I'm assuming you have some knowledge of blitz3d. Here is the scene setup:


Now, we'll set up the animated body for the ground. In this case, it never actually moves.


Tokab_Create creates an animated body and returns its handle.
Tokab_AddBox adds a box to the animated body. The parameters are AnimatedBody, Width, Height, Depth.
Tokab_SetPosition sets the position of the animated body. The parameters are AnimatedBody, X, Y, Z.
Here is the rest of the animated bodies setup:


This creates all the walls

Next, we create a rigid box.


The Arrays are used to store the handle of the Rigid Body, and the handles of the 3d representation.
The Rigid Body is created with the TOKRB_Create command which returns a handle.
The command TOKRB_AddBox adds a box to the rigid body. The parameters are the diminsions of the box. Note that the dimensions are twice that off the values in scaleentity because Blitz primitives are 2 units in each dimension. This command does return a handle to a geometry, however, at this point no geometric modifications are being made so it is unnessesary.
The next command sets the position of the rigid body. TOKRB_SetLinearDamping and TOKRB_SetAngularDamping set the linear dampening and angular damping respectivly. These can be thought of as air friction, or just to correct problems. Basically, all it means is that over time, an object will be slowed down linearly or angularly based upon how fast it is going. TOKRB_SetMass sets the mass of the object. The greater the mass, the less SetForce or other objects affect it.
TOKRB_SetBoxInertiaTensor sets the inertia tensor of an object. If you only have one geometry in your mesh, use this command, except with the specified object. The other parameters are the dimensions. So if your geometry was a sphere, you would use TOKRB_SetSphereInertiaTensor

Now, instead of only creating one, we'll create a bunch of them randomly placed with random velocities.


The TOKRB_SetVelocity and TOKRB_SetTorque commands obviously sets the linear and angular velocity of the rigid body.

Now, we'll write the skeleton of the main loop:


This gives us a scene with the camera moving around and around. you should see what looks like one white box in the middle.

Here's where the real fun comes in. this is the point where we add in the tokamak updater into the for...Next Loop


The command, TOKSIM_Advance, advances the physics simulation. The first parameter is the time step. A larger time step makes things go faster, a smaller one makes it go slower. This is useful for slow mo fx, etc. The second parameter sets the number of sub steps, which allow for more accurate processing of physics. This code:


Positions and rotates the 3d representations of the objects onto the tokamak rigid bodies. The code:


Gives all the objects a random spinning and moving velocity. The command TOKRB_ApplyImpulse2 applies an impulse at a location other than the center of the object, producing both movement and rotation.

Finally, we destroy the simulator and end the program.


Here is all the code for the demo. If it does not work, check to see if v04 of sweenie's wrapper are in your userlibs directory and the tokamak dll is either in the program directory or the windows/system32 folder.


For a printable copy of this article, please click HERE.

This site is Copyright© 2000-2004, BlitzCoder. All rights reserved.