Skip to content

Shapes

abstract class CP::Shape
inherits Reference #

Defines the shape of a rigid body.

Direct known subclasses

CP::Shape::Circle CP::Shape::Poly CP::Shape::Segment

Methods#

#area : Float64#

Get the calculated area of this shape.

View source

#bb : BB#

Get the bounding box that contains the shape given its current position and angle.

Only guaranteed to be valid after cache_bb or Space#step is called. Moving a body that a shape is connected to does not update its bounding box. For shapes used for queries that aren't attached to bodies, you can also use update.

View source

#body : Body | ::Nil#

The Body this shape is added to.

View source

#body=(body : Body?)#

Set the Body this shape is added to.

Can only be used if the shape is not currently added to a space.

View source

#cache_bb : BB#

Update, cache and return the bounding box of a shape based on the body it's attached to.

View source

#center_of_gravity : Vect#

Get the centroid of this shape.

View source

#collide(b : Shape) : ContactPointSet#

Return contact information about two shapes.

View source

#collision_type : CollisionType#

User defined collision type for the shape.

See Space#add_collision_handler for more information.

View source

#collision_type=(collision_type : Int)#

View source

#density : Float64#

Get the density of the shape if you are having Chipmunk calculate mass properties for you.

View source

#density=(density : Number)#

Set the density of this shape to have Chipmunk calculate mass properties for you.

View source

#elasticity : Float64#

The elasticity of this shape.

A value of 0.0 gives no bounce, while a value of 1.0 will give a 'perfect' bounce. However due to inaccuracies in the simulation using 1.0 or greater is not recommended.

View source

#elasticity=(elasticity : Number)#

View source

#filter : ShapeFilter#

The collision filtering parameters of this shape.

View source

#filter=(filter : ShapeFilter)#

View source

#friction : Float64#

The friction of this shape.

Chipmunk uses the Coulomb friction model, a value of 0.0 is frictionless. A value over 1.0 is also perfectly fine.

View source

#friction=(friction : Number)#

View source

#mass : Float64#

Get the mass of the shape if you are having Chipmunk calculate mass properties for you.

View source

#mass=(mass : Number)#

Set the mass of this shape to have Chipmunk calculate mass properties for you.

View source

#moment : Float64#

Get the calculated moment of inertia for this shape.

View source

#point_query(p : Vect) : PointQueryInfo#

Perform a nearest point query. It finds the closest point on the surface of shape to a specific point.

View source

#segment_query(a : Vect, b : Vect, radius : Number = 0) : SegmentQueryInfo?#

Perform a segment query against a shape: check if the line segment from start to end intersects the shape.

View source

#sensor=(sensor : Bool)#

View source

#sensor? : Bool#

Is the shape set to be a sensor or not?

Sensors only call collision callbacks, and never generate real collisions.

View source

#space : Space | ::Nil#

The Space this shape is added to.

View source

#surface_velocity : Vect#

The surface velocity of this shape.

Useful for creating conveyor belts or players that move around. This value is only used when calculating friction, not resolving the collision.

View source

#surface_velocity=(surface_velocity : Vect)#

View source

#update(transform : Transform) : BB#

Update, cache and return the bounding box of a shape with an explicit transformation.

Useful if you have a shape without a body and want to use it for querying.

View source

class CP::Shape::Box
inherits CP::Shape::Poly #

A special case of a polygon - a rectangle.

The boxes will always be centered at the center of gravity of the body you are attaching them to. If you want to create an off-center box, you will need to use Poly.

Constructors#

.new(body : Body?, width : Number, height : Number, radius : Number = 0)#

Initialize a box shaped polygon shape with rounded corners.

View source

.new(body : Body?, box : BB, radius : Number = 0)#

Initialize an offset box shaped polygon shape with rounded corners.

View source

Class methods#

.moment(m : Number, width : Number, height : Number) : Float64#

Calculate the moment of inertia for a solid box.

View source

.moment(m : Number, box : BB) : Float64#

Calculate the moment of inertia for a solid box.

View source

class CP::Shape::Circle
inherits CP::Shape #

A circle shape defined by a radius

This is the fastest and simplest collision shape

Constructors#

.new(body : Body?, radius : Number, offset : Vect = CP::Vect.new(0, 0))#

The parameters are: the body to attach the circle to; the offset from the body's center of gravity in body local coordinates.

View source

Class methods#

.area(r1 : Number, r2 : Number) : Float64#

Calculate area of a hollow circle.

r1 and r2 are the inner and outer diameters. A solid circle has an inner diameter of 0.

View source

.moment(m : Number, r1 : Number, r2 : Number, offset : Vect = CP::Vect.new(0, 0)) : Float64#

Calculate the moment of inertia for a circle.

r1 and r2 are the inner and outer diameters. A solid circle has an inner diameter of 0.

View source

Methods#

#offset : Vect#

Get the offset of a circle shape.

View source

#offset=(offset : Vect)#

Unsafe. Set the offset of a circle shape.

This change is only picked up as a change to the position of the shape's surface, but not its velocity. Changing it will not result in realistic physical behavior. Only use if you know what you are doing!

View source

#radius : Float64#

Get the radius of a circle shape.

View source

#radius=(radius : Number)#

Unsafe. Set the radius of a circle shape.

This change is only picked up as a change to the position of the shape's surface, but not its velocity. Changing it will not result in realistic physical behavior. Only use if you know what you are doing!

View source

class CP::Shape::Poly
inherits CP::Shape #

A convex polygon shape

Slowest, but most flexible collision shape.

Included modules

Enumerable Indexable

Direct known subclasses

CP::Shape::Box

Constructors#

.new(body : Body?, verts : Array(Vect) | Slice(Vect), transform : Transform = Transform::IDENTITY, radius : Number = 0)#

Initialize a polygon shape with rounded corners. A convex hull will be created from the vertices.

The parameters are: the body to attach the poly to; the verts (vertices) of the polygon; the transform to apply to every vertex; the radius of the corners.

Adding a small radius will bevel the corners and can significantly reduce problems where the poly gets stuck on seams in your geometry.

View source

.new(body : Body?, verts : Array(Vect) | Slice(Vect), radius : Number)#

Initialize a polygon shape with rounded corners. The vertices must be convex with a counter-clockwise winding.

View source

Class methods#

.area(verts : Array(Vect) | Slice(Vect), radius : Number = 0) : Float64#

Calculate the signed area of a polygon.

A clockwise winding gives positive area. This is probably backwards from what you expect, but matches Chipmunk's winding for poly shapes.

View source

.centroid(verts : Array(Vect) | Slice(Vect)) : Vect#

Calculate the natural centroid of a polygon.

View source

.convex_hull(verts : Array(Vect) | Slice(Vect), tol : Number = 0) : Tuple(Slice(Vect), Int32)#

Calculate the convex hull of a given set of points.

tol is the allowed amount to shrink the hull when simplifying it. A tolerance of 0.0 creates an exact hull.

Returns the convex hull and the index where the first vertex in the hull came from (i.e. verts[first] == result[0])

View source

.moment(m : Number, verts : Array(Vect) | Slice(Vect), offset : Vect = CP::Vect.new(0, 0), radius : Number = 0) : Float64#

Calculate the moment of inertia for a solid polygon shape.

Assumes its center of gravity is at its centroid. The offset is added to each vertex.

View source

Methods#

#radius : Float64#

Get the radius of a polygon shape.

View source

#radius=(radius : Number)#

Unsafe. Set the radius of a poly shape.

This change is only picked up as a change to the position of the shape's surface, but not its velocity. Changing it will not result in realistic physical behavior. Only use if you know what you are doing!

View source

#set_verts(verts : Array(Vect) | Slice(Vect), transform : Transform = Transform::IDENTITY)#

Unsafe. Set the vertices of a poly shape.

This change is only picked up as a change to the position of the shape's surface, but not its velocity. Changing it will not result in realistic physical behavior. Only use if you know what you are doing!

View source

#size : Int32#

Get the number of verts in a polygon shape.

View source

#unsafe_fetch(index : Int) : Vect#

Get the i-th vertex of a polygon shape.

View source

class CP::Shape::Segment
inherits CP::Shape #

A line segment shape between two points.

Meant mainly as a static shape. Can be beveled in order to give them a thickness.

Constructors#

.new(body : Body?, a : Vect, b : Vect, radius : Number = 0)#

The parameters are: the body to attach the segment to; the endpoints (a, b) to attach the segment to; the radius of the half-circles at the ends of the segment (thickness is twice the radius).

View source

Class methods#

.area(a : Vect, b : Vect, radius : Number) : Float64#

Calculate the area of a fattened (capsule shaped) line segment.

View source

.moment(m : Number, a : Vect, b : Vect, radius : Number = 0) : Float64#

Calculate the moment of inertia for a line segment.

Beveling radius is not supported.

View source

Methods#

#a : Vect#

Get the first endpoint of a segment shape.

View source

#b : Vect#

Get the second endpoint of a segment shape.

View source

#normal : Vect#

Get the normal of a segment shape.

View source

#radius : Float64#

Get the radius of a segment shape.

View source

#radius=(radius : Number)#

Unsafe. Set the radius of a segment shape.

This change is only picked up as a change to the position of the shape's surface, but not its velocity. Changing it will not result in realistic physical behavior. Only use if you know what you are doing!

View source

#set_endpoints(a : Vect, b : Vect)#

Unsafe. Set the endpoints of a segment shape.

This change is only picked up as a change to the position of the shape's surface, but not its velocity. Changing it will not result in realistic physical behavior. Only use if you know what you are doing!

View source

#set_neighbors(prev : Vect, next next_ : Vect)#

Let Chipmunk know about the geometry of adjacent segments to avoid colliding with endcaps.

When you have a number of segment shapes that are all joined together, things can still collide with the "cracks" between the segments. By setting the neighbor segment endpoints you can tell Chipmunk to avoid colliding with the inner parts of the crack.

View source

struct CP::ShapeFilter
inherits Struct #

Fast collision filtering type that is used to determine if two objects collide before calling collision or query callbacks.

Chipmunk has two primary means of ignoring collisions: groups and category masks.

Groups are used to ignore collisions between parts on a complex object. A ragdoll is a good example. When jointing an arm onto the torso, you'll want them to allow them to overlap. Groups allow you to do exactly that. Shapes that have the same group don't generate collisions. So by placing all of the shapes in a ragdoll in the same group, you'll prevent it from colliding against other parts of itself.

Category masks allow you to mark which categories an object belongs to and which categories it collidies with. By default, objects exist in every category and collide with every category.

The type of categories and mask in ShapeFilter is UInt32.

There is one last way of filtering collisions using collision handlers. See the section on callbacks for more information. Collision handlers can be more flexible, but can be slower. Fast collision filtering rejects collisions before running the expensive collision detection code, so using groups or category masks is preferred.

Constants#

ALL = new(NO_GROUP, ALL_CATEGORIES, ALL_CATEGORIES)#

Collision filter value for a shape that will collide with anything except NONE.

ALL_CATEGORIES = ~(Bitmask.new(0))#

Value for signifying that a shape is in every category.

NO_GROUP = Group.new(0)#

Value signifying that a shape is in no group.

NONE = new(NO_GROUP, ~ALL_CATEGORIES, ~ALL_CATEGORIES)#

Collision filter value for a shape that does not collide with anything.

Constructors#

.new(group : Int = NO_GROUP, categories : Int = ALL_CATEGORIES, mask : Int = ALL_CATEGORIES)#

View source

Methods#

#categories : Bitmask#

A bitmask of user definable categories that this object belongs to.

The category/mask combinations of both objects in a collision must agree for a collision to occur.

View source

#categories=(categories : Bitmask)#

View source

#group : Group#

Two objects with the same non-zero group value do not collide.

This is generally used to group objects in a composite object together to disable self collisions.

View source

#group=(group : Group)#

View source

#mask : Bitmask#

A bitmask of user definable category types that this object object collides with.

The category/mask combinations of both objects in a collision must agree for a collision to occur.

View source

#mask=(mask : Bitmask)#

View source

alias CP::ShapeFilter::Bitmask #

Alias definition

UInt32

alias CP::ShapeFilter::Group #

Alias definition

UInt64