move

Documentation

Overview

Move is a real-time simulation of real-world physics. Move deals with automatically applying simulated forces to virtual 3D objects known as bodies. Move updates all bodies locations and directions based on forces and collisions with other bodies.

Bodies are created using NewBody(shape). For example:

box    := NewBody(NewBox(hx, hy, hz))
sphere := NewBody(NewSphere(radius))

Creating and tracking bodies is the responsibility of the calling application. Bodies are moved by regularly calling Mover.Step(). Regulating the calls to Step() is the responsibility of the calling application. See:

http://gafferongames.com/game-physics/fix-your-timestep

Once Step has completed, all bodies new locations and directions are stored in body.World.

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

Index

• Constants
• type Abox
  • func (a *Abox) Overlaps(b *Abox) bool
• type Body
  • func NewBody(shape Shape) Body
• type Mover
  • func NewMover() Mover
• type Shape
  • func NewBox(hx, hy, hz float64) Shape
  • func NewSphere(radius float64) Shape
• type World

Constants

const (
	SphereShape = iota // Considered convex (curving outwards).
	BoxShape           // Polyhedral (flat faces, straight edges). Considered convex.
	NumShapes          // Keep as last constant.
)

Enumerate the shapes handled by physics and returned by Shape.Type()

Types

type Abox

type Abox struct {
	Sx, Sy, Sz float64 // Smallest point.
	Lx, Ly, Lz float64 // Largest point.
}

Abox is an axis aligned bounding box used with the Shape interface. Its primary purpose is to surround arbitrary shapes during broad phase collision detection. Abox is not a primitive shape for collision - use Box instead. The vertices for the full axis aligned box are:

Sx, Sy, Sz -- smallest vertex (left, bottom, back = minimum point)
Sx, Sy, Lz |
Sx, Ly, Sz |
Sx, Ly, Lz |- generate if necessary.
Lx, Sy, Sz |
Lx, Sy, Lz |
Lx, Ly, Sz |
Lx, Ly, Lz -- largest vertex (right, top, front = maximum point)

func (*Abox) Overlaps

func (a *Abox) Overlaps(b *Abox) bool

Overlaps returns true if Abox a and b are intersecting. Returns false if Abox a and b are not intersecting or are just touching along one or more points, edges, or faces.

type Body

type Body interface {
	Id() uint32               // The unique body id.
	SetShape(shape Shape)     // Shape is mandatory.
	World() *lin.T            // Get/Set world transform which is the...
	SetWorld(world *lin.T)    // ...bodies location and direction.
	IsMovable() bool          // True if the body has mass.
	Speed() (x, y, z float64) // Current linear velocity.
	Whirl() (x, y, z float64) // Current angular velocity.
	Push(x, y, z float64)     // Add to the body's linear velocity.
	Turn(x, y, z float64)     // Add to the body's angular velocity.
	Stop()                    // Stops linear velocity.
	Rest()                    // Stops angular velocity.

	// SetMaterial associates physical properties with a body. The physical
	// properties are combined with the body's shape to determine its behaviour
	// during collisions. The updated Body is returned.
	//     mass:       unmoving (static/fixed) bodies have 0 mass.
	//     bounciness: total bounciness is determined by multiplying the bounciness
	//                 of the two colliding bodies. If one of the bodies has 0
	//                 bounciness then there is no bounce effect.
	SetMaterial(mass, bounciness float64) Body
	Data() interface{}        // Get/Set application specific data...
	SetData(data interface{}) // ...often pointer to the scene graph node.
}

Body is a single object contained within a physics simulation. Bodies generally relate to a scene node that is displayed to the user. Only add bodies that need to participate in physics. Bodies that are added to physics are expected to have their movement controlled by the physics simulation and not the application.

func NewBody

func NewBody(shape Shape) Body

NewBody returns a new Body structure. The body will be positioned, with no rotation, at the origin.

type Mover

type Mover interface {
	SetGravity(gravity float64) // Default is 10m/s.
	SetMargin(margin float64)   // Default is 0.04.

	// Step the physics simulation one tiny bit forward. This is expected
	// to be called regularly from 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.  Unmoving/unmoved
	// bodies, or bodies with zero mass are not updated.
	Step(bodies []Body, timestep float64)
}

Mover simulates forces acting on moving bodies. Expected usage is to simulate real-life conditions like air resistance and gravity, or the lack thereof.

func NewMover

func NewMover() Mover

NewMover returns the default motion world instance.

type Shape

type Shape interface {
	Type() int       // Type returns the shape type.
	Volume() float64 // Volume is useful for mass = density*volume.

	// Aabb updates ab to be the axis aligned bounding box for this shape.
	// The updated Abox ab will be in the space defined by the transform.
	//    ab     : Output structure. Providing a nil Abox will cause a panic.
	//    margin : Optional small positive value that increases the size
	//             of the surrounding box. Use 0 for no margin.
	// The updated Abox ab is returned.
	Aabb(transfrom *lin.T, ab *Abox, margin float64) *Abox

	// Inertia is needed by collision resolution.
	//    mass   : can be set directly or as density*Volume()
	// The input vector, inertia, is updated and returned.
	Inertia(mass float64, inertia *lin.V3) *lin.V3
}

Shapes are physics collision primitives used to enclose a 3D model. A Shape is always in local space centered at the origin. Combine a shape with a transform to position the shape anywhere in world space. Shapes do not allocate memory so calculations, like filling in bounding boxes, are expected to be given the necessary structures.

func NewBox

func NewBox(hx, hy, hz float64) Shape

NewBox creates a Box shape. Negative input values are turned positive. Input values of zero are ignored, but not recommended.

func NewSphere

func NewSphere(radius float64) Shape

NewSphere creates a Sphere shape. Negative radius values are turned positive. Input values of zero are ignored, but not recommended.

type World

type World interface {
	Add(body Body) // Add to the current population (immigrate?).
	Rem(body Body) // Remove from the current population (emigrate?).
}

World is anything that wants to track a population (a bunch of bodies). It is expected to be used for organizing bodies into structures that can be efficiently traversed and manipulated.

There is currently no default implementation in the move package.