how things move

In the traditional "Scene Graph" model, a 3D scene is created from a tree of translation nodes. These nodes serve as an inexpensive joint system with their actual positions calculated through a series of nested matrix transformations by the GPU.

The Scene Graph model is crude and obsolete given the speed of modern CPUs. In PySoy, every object in 3d space is one or more physics bodies with their own velocity, rotation, and potential connections with other bodies.

We originally used ODE and are now migrating to our own internal physics processing written partially in  Orc. ODE will continue to be part of PySoy physics for the next few beta releases.

PySoy's Scene Thread

When PySoy is first imported by Python several background threads are launched to handle rendering, physics, audio, input, etc. These threads are 100% C, Python code is not permitted for speed though Python callbacks are permitted and Python may be used to build up a sequence of commands to be executed as part of these threads.

These threads belong to the GObject-based backend libsoy and operate outside the context of Python's Global Interpreter Lock (GIL) to for good multicore performance.


Virtually everything visible in a soy.scenes.Scene is an instance of soy.bodies.Body. The Body class implements the standard physics body properties such as velocity, rotation, and mass. Even lights and cameras are considered physics bodies and behave accordingly.

Bodies can connected using joints to constrain their movement in respect to each other.

By default a Body has no shape, that is, it cannot collide with anything else. A .shape property can be added to provide collision.

For field effects we have soy.fields which apply forces to all bodies within range according to the rules of that field. Currently we only have "gravity"-like fields (ie, for space flight games). Fields acting according to surface area or volume displacement are in development.

To aid in development each of these can be made visible in the 3D scene. In this way PySoy can also be a great learning tool.

Mesh Animation

One of the greatest challenges in this model is merging mesh animation, such as a bipedal character walking or a tree bending to wind.

Traditional character animation libraries, including Cal3D, work only with pre-scripted animation cycles. While different cycles can be blended, such as walking and swinging a sword at the same time, the position of bones cannot be constrained by the environment. One negative effect of this is the "walking uphill" scenario where one foot is inside the hill and the other stands on air.

We are implementing our own internal animation system using this same physics model; every "bone" is a separate physics body which is typically connected to other "bones" with joints.

Left alone any such model would be only somewhat more realistic than a ragdoll; it's limbs would move according to their mass, it's joints constrained, but under gravity this model would crumple to the ground.

From here a programmer will implement "behavior", which applies torque and forces to joints to achieve certain dynamic effects. Part of this is "training" through scripted walk cycles and other animations.


The PySoy physics model was developed by Arc Riley, Zach Miller, Mike Beckson, and Eric Stein.