physics

Documentation

Overview

Package physics deals with automatically applying simulated forces, real world based or otherwise, to virtual 3D objects known as bodies. Physics will update bodies location, direction, and motion based on forces and collisions with other bodies.

Currently the physics engine is incomplete and untested. The initial attempt cobbled together collision algorithms from any and all sources.

http://www.realtimerendering.com/intersections.html.
http://www.cs.cmu.edu/~baraff/pbm/rigid2.pdf
http://www.ode.org (very nice code structure and layout)
http://bulletphysics.org
... and others that are referenced thoughout the package.

However precious little working physics code made the transition from the source material. This was entirely the fault of the package author and in no way the fault of the excellent source material. Hence... (TODO) this entire package needs to be replaced by something that is fully implemented, tested, and benchmarked (ideally by someone that knows, and likes, physics :P). Creating bindings, or porting an open source engine are also possibilities.

Package physics is provided as part of the vu (virtual universe) 3D engine.

Index

• type Body
  • func NewBody(uid int, size, mass float32) Body
• type Contact
• type Physics
  • func New() Physics
• type Shape
  • func Abox(bx, by, bz, tx, ty, tz float32) Shape
  • func Plane(nx, ny, nz, dx, dy, dz float32) Shape
  • func Ray(ox, oy, oz, dx, dy, dz float32) Shape
  • func Sphere(cx, cy, cz, r float32) Shape

Types

type Body

type Body interface {
	Id() int                                 // Same id as scene graph node.
	SetShape(shp Shape)                      // Need shape to participate in collision.
	SetLocation(loc *lin.V3)                 // Pointer to shared external location.
	SetRotation(rot *lin.Q)                  // Pointer to shared external rotation.
	LinearMomentum() (x, y, z float32)       // Current linear motion.
	SetLinearMomentum(x, y, z float32)       // Apply initial motion.
	AngularMomentum() (x, y, z float32)      // Current angular motion (think of spin).
	SetAngularMomentum(x, y, z float32)      // Apply initial angular motion.
	ResetMomentum()                          // Remove all linear and angular momentum.
	SetResolver(r func(contacts []*Contact)) // Marks a body as free of physics.
}

Body is a single object that is contained within a physics simulation. Bodies generally relate to a scene node that is displayed to the user. Only bodies that participate in physics should be added to the physics simulation.

func NewBody

func NewBody(uid int, size, mass float32) Body

NewBody returns a stationary physics body. Note that zero mass objects can't (won't) be moved.

type Contact

type Contact struct {
	Normal lin.V3  // Normal vector at contact location.
	Depth  float32 // Penetration depth
	Bid    int     // Body identifier.
}

Contact describes the contact point between two objects. It contains a contact normal vector, and a contect depth which allows the contacting objects to be separated if necessary.

TODO ideally the normal is a separating normal, pretty sure this is not always the case. Also it would be nice to return a single separating contact point in the case of multiple contacts in a collision.

Contacts are generated by collisions and consumed by collision resolution.

type Physics

type Physics interface {
	AddBody(b Body)             // Add a body to the physics simulation.
	RemBody(b Body)             // Remove a body from the physics simulation.
	Reset()                     // Clear all bodies from the simulation.
	SetGravity(gravity float32) // SetGravity for the physics simulation.
	SetDamping(damping float32) // SetDamping for all physics motion.
	Collide(b Body)             // Run collision for just the given body.

	// Step the physics simulation one tiny bit forward.  This is expected
	// to be called for each update in the main engine loop.  At the end of
	// a simulation step, all the bodies positions will be updated based on
	// forces acting upon them and/or collision results.  Bodies that are
	// free or have zero mass are not updated.
	//
	// Note that the collision information is both generated and consumed
	// by the physics simulation.  Free bodies that have registered for
	// collision updates are the exception.
	Step(step float32)
}

Physics is the set of rules that simulates forces acting on bodies in motion. The normal usage is to simulate real-life conditions like air resistance and gravity, or the lack there-of.

func New

func New() Physics

New returns the default physics world instance.

type Shape

type Shape interface {
	// Shape vs shape collision returns all the points of contact.
	Collide(s Shape) (contacts []*Contact)

	// Resolve collisions under physics control.
	Bounce(s Shape, c []*Contact, mo1, mo2 *motion)

	// Volume, given a density, can be used to calculate mass as:
	//     mass = density * volume.
	// Shapes with no volume (rays, planes) return 0.
	Volume() float32
}

Shape allows collision and collision resolution between different shapes. Shapes are only expected to be created by the engine/application but only consumed by the physics system.

func Abox

func Abox(bx, by, bz, tx, ty, tz float32) Shape

Abox (axis aligned bounding box) are specified by a bottom (left) corner and a top (right) corner where the bottom corner coordinates are less than the top corner coordinates.

func Plane

func Plane(nx, ny, nz, dx, dy, dz float32) Shape

Plane is defined by a unit normal vector for the plane and the distance of the plane from the origin.

func Ray

func Ray(ox, oy, oz, dx, dy, dz float32) Shape

Ray is defined by a point of origin and a direction vector.

func Sphere

func Sphere(cx, cy, cz, r float32) Shape

Sphere is defined by a center location and a radius.