ump

README

Ump

Go collision-detection library for axis-aligned rectangles. Its main features are:

• ump only does axis-aligned bounding-box (AABB) collisions. If you need anything more complicated than that (circles, polygons, etc.) give box2dlite a look.
• Handles tunnelling - all items are treated as "bullets". The fact that we only use AABBs allows doing this fast.
• Strives to be fast while being economic in memory
• It's centered on detection, but it also offers some (minimal & basic) collision response
• Can also return the items that touch a point, a segment or a rectangular zone.
• ump is gameistic instead of realistic.

The demos are Amore based, but this library can be used in any Go program.

ump is ideal for:

• Tile-based games, and games where most entities can be represented as axis-aligned rectangles.
• Games which require some physics, but not a full realistic simulation - like a platformer.
• Examples of genres: top-down games (Zelda), Shoot-em-ups, fighting games (Street Fighter), platformers (Super Mario).

ump is not a good match for:

• Games that require polygons for the collision detection
• Games that require highly realistic simulations of physics - things "stacking up", "rolling over slides", etc.
• Games that require very fast objects colliding reallistically against each other (in ump, being gameistic, objects are moved and collided one at a time)
• Simulations where the order in which the collisions are resolved isn't known.

Example

For full example usage please see the amore example platformer

Documentation

Index

• type Body
  • func (body *Body) Extents() (x, y, w, h, r, b float32)
  • func (body *Body) GetResponse(tag string) string
  • func (body *Body) GetResponses() map[string]string
  • func (body *Body) HasTag(tags ...string) bool
  • func (body *Body) IsStatic() bool
  • func (body *Body) Move(x, y float32) (gx, gy float32, cols []*Collision)
  • func (body *Body) Position() (x, y float32)
  • func (body *Body) Remove()
  • func (body *Body) SetResponse(tag, resp string)
  • func (body *Body) SetResponses(respMap map[string]string)
  • func (body *Body) SetStatic(isStatic bool)
  • func (body *Body) Tag() string
  • func (body *Body) Update(x, y float32)
• type Collision
• type Point
• type Resp
• type World
  • func NewWorld(cellSize int) *World
  • func (world *World) Add(tag string, left, top, w, h float32) *Body
  • func (world *World) AddResponse(name string, response Resp)
  • func (world *World) Project(body *Body, goalX, goalY float32) []*Collision
  • func (world *World) QueryPoint(x, y float32, tags ...string) []*Body
  • func (world *World) QueryRect(x, y, w, h float32, tags ...string) []*Body
  • func (world *World) QuerySegment(x1, y1, x2, y2 float32, tags ...string) []*Body

Types

type Body

type Body struct {
	ID uint32
	// contains filtered or unexported fields
}

Body represents a rectangle that will collide with other rectangles/bodies

func (*Body) Extents

func (body *Body) Extents() (x, y, w, h, r, b float32)

Extents will return the position and size of the body

func (*Body) GetResponse

func (body *Body) GetResponse(tag string) string

GetResponse will return the filter name for the tag passed. If the tag is not defined in the response map then the default reponse will be returned

func (*Body) GetResponses

func (body *Body) GetResponses() map[string]string

GetResponses will return the response map set on this body

func (*Body) HasTag

func (body *Body) HasTag(tags ...string) bool

HasTag will check a list of tags to see if this body matches any of them. This is good for checking groups of object that collide.

func (*Body) IsStatic

func (body *Body) IsStatic() bool

IsStatic will return if the body is a static body or not. See SetStatic for why it would be a static body

func (*Body) Move

func (body *Body) Move(x, y float32) (gx, gy float32, cols []*Collision)

Move moves a body to a new location and will return the point where the body managed to get to (gx, gy). It will also return any collisions that happened inbetween the movements.

func (*Body) Position

func (body *Body) Position() (x, y float32)

Position will return the current position of the body.

func (*Body) Remove

func (body *Body) Remove()

Remove will remove this body from the world and will no longer collide with any other bodies.

func (*Body) SetResponse

func (body *Body) SetResponse(tag, resp string)

SetResponse will set an entry in the response map for the provided tag.

func (*Body) SetResponses

func (body *Body) SetResponses(respMap map[string]string)

SetResponses will set a map of responses for a body. This map defines how this body will react to certain collisions. The map is formatted map[object_tag]filter_name By default all items will collide and not resolve. To change the default behaviour use the "default" entry in the response map. For instance on an item that would bounce like a ball you would call `body.SetResponses(map[string]string{"default": "bounce"})

func (*Body) SetStatic

func (body *Body) SetStatic(isStatic bool)

SetStatic will make this body static which means that other bodies will collide with it but this body will skip collision check. This is good for optimizing your collisions with items like walls and floors.

func (*Body) Tag

func (body *Body) Tag() string

Tag will return the string tag for this body

func (*Body) Update

func (body *Body) Update(x, y float32)

Update changes the position of the body with out checking for collisions

type Collision

type Collision struct {
	Intersection float32
	Distance     float32
	Body         *Body
	Move         Point
	Normal       Point
	Touch        Point
	Data         Point
	RespType     string
}

Collision represents a touch of two objects. The intersection is the fraction of the movement where the two items touched. Distanse is how far the two object are from each other. Body is the other body that was collided.

- Move is the amount the body needs to move to resolve the collision - Normal is the normal of the collision - Touch is the point where the two bodies first touched - Data is used for misc data that can be pass in a filter - RespType describes which filter was used to resolve the collision

type Point

type Point struct {
	X, Y float32
}

Point is used as data points in a collision. This could represent a touch or a normal or something else.

type Resp

type Resp func(world *World, col *Collision, body *Body, goalX, goalY float32) (gx, gy float32, cols []*Collision)

Resp is a function that will handle and resolve a collision. For instance the bound filter will return the bounce goal gx gy, and then project for the new direction to make sure there are not collisions in that direction.

type World

type World struct {
	// contains filtered or unexported fields
}

World is the virtual world in which all these collisions happen. The world contains a grid, which contains several cells, which contains collidable bodies.

A world also has registered responses to filter collisions please see Resp for this.

func NewWorld

func NewWorld(cellSize int) *World

NewWorld builds a physics world with the provided cell size. A good default is 64. It represents the size of the sides of the (squared) cells that will be used internally to provide the data. In tile based games, it's usually a multiple of the tile side size. So in a game where tiles are 32x32, cellSize will be 32, 64 or 128. In more sparse games, it can be higher.

func (*World) Add

func (world *World) Add(tag string, left, top, w, h float32) *Body

Add will create a new Body to be tracked in this world. The tag is important. It is used to decided which filter to use but also for you to decide what to do when a body collides with your new body.

left, top, w, and h describe a rectangle for the body to inhabit.

func (*World) AddResponse

func (world *World) AddResponse(name string, response Resp)

AddResponse will add a new filter response for this world. This is helpful if you are creating custom reactions in your world.

func (*World) Project

func (world *World) Project(body *Body, goalX, goalY float32) []*Collision

Project will project the goal location of the provided body but not move it. This is good for checking a future location of a body and see if there are any collisions in that space.

func (*World) QueryPoint

func (world *World) QueryPoint(x, y float32, tags ...string) []*Body

QueryPoint will return any bodies that are underneathe the point.

If tags are passed into the query then it will only return the bodies with those tags.

func (*World) QueryRect

func (world *World) QueryRect(x, y, w, h float32, tags ...string) []*Body

QueryRect will take the rectangle arguments and return any bodies that are in that rectangle

If tags are passed into the query then it will only return the bodies with those tags.

func (*World) QuerySegment

func (world *World) QuerySegment(x1, y1, x2, y2 float32, tags ...string) []*Body

QuerySegment will return any bodies that are underneathe the segment/line.

If tags are passed into the query then it will only return the bodies with those tags.