# API Reference

## `pymunk` Package

Submodules

- `pymunk.autogeometry` Module
- `pymunk.constraints` Module
- `pymunk.vec2d` Module
- `pymunk.matplotlib_util` Module
- `pymunk.pygame_util` Module
- `pymunk.pyglet_util` Module
- `pymunk.tests` Module
- `pymunk.examples` Module

..comment

Pymunk

Pymunk is a easy-to-use pythonic 2d physics library that can be used whenever you need 2d rigid body physics from Python.

Homepage: http://www.pymunk.org

This is the main containing module of Pymunk. It contains among other things the very central Space, Body and Shape classes.

class pymunk.Arbiter(_arbiter: pymunk._chipmunk.ffi.CData, space: Space)

  Bases: `object`

  The Arbiter object encapsulates a pair of colliding shapes and all of

    the data about their collision.

    They are created when a collision starts, and persist until those shapes are no longer colliding.

  Warning

  Because arbiters are handled by the space you should never hold onto a reference to an arbiter as you don’t know when it will be destroyed! Use them within the callback where they are given to you and then forget about them or copy out the information you need from them.

  __init__(_arbiter: pymunk._chipmunk.ffi.CData, space: Space) → None

    Initialize an Arbiter object from the Chipmunk equivalent struct and the Space.

    Note

    You should never need to create an instance of this class directly.

  property contact_point_set: ContactPointSet

    Contact point sets make getting contact information from the Arbiter simpler.

    Return ContactPointSet

  property friction: float

    The calculated friction for this collision pair.

    Setting the value in a pre_solve() callback will override the value calculated by the space. The default calculation multiplies the friction of the two shapes together.

  property is_first_contact: bool

    Returns true if this is the first step the two shapes started touching.

    This can be useful for sound effects for instance. If its the first frame for a certain collision, check the energy of the collision in a post_step() callback and use that to determine the volume of a sound effect to play.

  property is_removal: bool

    Returns True during a separate() callback if the callback was invoked due to an object removal.

  property normal: Vec2d

    Returns the normal of the collision.

  property restitution: float

    The calculated restitution (elasticity) for this collision pair.

    Setting the value in a pre_solve() callback will override the value calculated by the space. The default calculation multiplies the elasticity of the two shapes together.

  property shapes: Tuple[Shape, Shape]

    Get the shapes in the order that they were defined in the collision handler associated with this arbiter

  property surface_velocity: Vec2d

    The calculated surface velocity for this collision pair.

    Setting the value in a pre_solve() callback will override the value calculated by the space. the default calculation subtracts the surface velocity of the second shape from the first and then projects that onto the tangent of the collision. This is so that only friction is affected by default calculation. Using a custom calculation, you can make something that responds like a pinball bumper, or where the surface velocity is dependent on the location of the contact point.

  property total_impulse: Vec2d

    Returns the impulse that was applied this step to resolve the collision.

    This property should only be called from a post-solve or each_arbiter callback.

  property total_ke: float

    The amount of energy lost in a collision including static, but not dynamic friction.

    This property should only be called from a post-solve or each_arbiter callback.

class pymunk.BB(left: float = 0, bottom: float = 0, right: float = 0, top: float = 0)

  Bases: `NamedTuple`

  Simple axis-aligned 2D bounding box.

  Stored as left, bottom, right, top values.

  An instance can be created in this way:

        >>> BB(left=1, bottom=5, right=20, top=10)
        BB(left=1, bottom=5, right=20, top=10)

  Or partially, for example like this:

        >>> BB(right=5, top=10)
        BB(left=0, bottom=0, right=5, top=10)

  area() → float

    Return the area

  bottom: float

    Alias for field number 1

  center() → Vec2d

    Return the center

  clamp_vect(v: Tuple[float, float]) → Vec2d

    Returns a copy of the vector v clamped to the bounding box

  contains(other: BB) → bool

    Returns true if bb completley contains the other bb

  contains_vect(v: Tuple[float, float]) → bool

    Returns true if this bb contains the vector v

  expand(v: Tuple[float, float]) → BB

    Return the minimal bounding box that contans both this bounding box and the vector v

  intersects(other: BB) → bool

    Returns true if the bounding boxes intersect

  intersects_segment(a: Tuple[float, float], b: Tuple[float, float]) → bool

    Returns true if the segment defined by endpoints a and b intersect this bb.

  left: float

    Alias for field number 0

  merge(other: BB) → BB

    Return the minimal bounding box that contains both this bb and the other bb

  merged_area(other: BB) → float

    Merges this and other then returns the area of the merged bounding box.

  static newForCircle(p: Tuple[float, float], r: float) → BB

    Convenience constructor for making a BB fitting a circle at position p with radius r.

  right: float

    Alias for field number 2

  segment_query(a: Tuple[float, float], b: Tuple[float, float]) → float

    Returns the fraction along the segment query the BB is hit.

    Returns infinity if it doesnt hit

  top: float

    Alias for field number 3

class pymunk.Body(mass: float = 0, moment: float = 0, body_type: int = DYNAMIC)

  Bases: `PickleMixin`, `TypingAttrMixing`, `object`

  A rigid body

  - Use forces to modify the rigid bodies if possible. This is likely to be the most stable.

  - Modifying a body’s velocity shouldn’t necessarily be avoided, but applying large changes can cause strange results in the simulation. Experiment freely, but be warned.

  - Don’t modify a body’s position every step unless you really know what you are doing. Otherwise you’re likely to get the position/velocity badly out of sync.

  A Body can be copied and pickled. Sleeping bodies that are copied will be awake in the fresh copy. When a Body is copied any spaces, shapes or constraints attached to the body will not be copied.

  DYNAMIC: ClassVar[int]

    Dynamic bodies are the default body type.

    They react to collisions, are affected by forces and gravity, and have a finite amount of mass. These are the type of bodies that you want the physics engine to simulate for you. Dynamic bodies interact with all types of bodies and can generate collision callbacks.

  KINEMATIC: ClassVar[int]

    Kinematic bodies are bodies that are controlled from your code instead of inside the physics engine.

    They arent affected by gravity and they have an infinite amount of mass so they don’t react to collisions or forces with other bodies. Kinematic bodies are controlled by setting their velocity, which will cause them to move. Good examples of kinematic bodies might include things like moving platforms. Objects that are touching or jointed to a kinematic body are never allowed to fall asleep.

  STATIC: ClassVar[int]

    Static bodies are bodies that never (or rarely) move.

    Using static bodies for things like terrain offers a big performance boost over other body types- because Chipmunk doesn’t need to check for collisions between static objects and it never needs to update their collision information. Additionally, because static bodies don’t move, Chipmunk knows it’s safe to let objects that are touching or jointed to them fall asleep. Generally all of your level geometry will be attached to a static body except for things like moving platforms or doors. Every space provide a built-in static body for your convenience. Static bodies can be moved, but there is a performance penalty as the collision information is recalculated. There is no penalty for having multiple static bodies, and it can be useful for simplifying your code by allowing different parts of your static geometry to be initialized or moved separately.

  __init__(mass: float = 0, moment: float = 0, body_type: int = DYNAMIC) → None

    Create a new Body

    Mass and moment are ignored when body_type is KINEMATIC or STATIC.

    Guessing the mass for a body is usually fine, but guessing a moment of inertia can lead to a very poor simulation so it’s recommended to use Chipmunk’s moment calculations to estimate the moment for you.

    There are two ways to set up a dynamic body. The easiest option is to create a body with a mass and moment of 0, and set the mass or density of each collision shape added to the body. Chipmunk will automatically calculate the mass, moment of inertia, and center of gravity for you. This is probably preferred in most cases. Note that these will only be correctly calculated after the body and shape are added to a space.

    The other option is to set the mass of the body when it’s created, and leave the mass of the shapes added to it as 0.0. This approach is more flexible, but is not as easy to use. Don’t set the mass of both the body and the shapes. If you do so, it will recalculate and overwrite your custom mass value when the shapes are added to the body.

    Examples of the different ways to set up the mass and moment:

        >>> import pymunk
        >>> radius = 2
        >>> mass = 3
        >>> density = 3
        >>> def print_mass_moment(b):
        ...    print("mass={:.0f} moment={:.0f}".format(b.mass, b.moment))

        >>> # Using Shape.density
        >>> s = pymunk.Space()
        >>> b = pymunk.Body()
        >>> c = pymunk.Circle(b, radius)
        >>> c.density = density
        >>> print_mass_moment(b)
        mass=0 moment=0
        >>> s.add(b, c)
        >>> print_mass_moment(b)
        mass=38 moment=75

        >>> # Using Shape.mass
        >>> b = pymunk.Body()
        >>> c = pymunk.Circle(b, radius)
        >>> c.mass = mass
        >>> print_mass_moment(b)
        mass=0 moment=0
        >>> s.add(b, c)
        >>> print_mass_moment(b)
        mass=3 moment=6

        >>> # Using Body constructor
        >>> moment = pymunk.moment_for_circle(mass, 0, radius)
        >>> b = pymunk.Body()
        >>> c = pymunk.Circle(b, radius)
        >>> c.mass = mass
        >>> print_mass_moment(b)
        mass=0 moment=0
        >>> s.add(b, c)
        >>> print_mass_moment(b)
        mass=3 moment=6

    It becomes even more useful to use the mass or density properties of the shape when you attach multiple shapes to one body, like in this example with density:

        >>> # Using multiple Shape.density
        >>> b = pymunk.Body()
        >>> c1 = pymunk.Circle(b, radius, offset=(10,0))
        >>> c1.density = density
        >>> c2 = pymunk.Circle(b, radius, offset=(0,10))
        >>> c2.density = density
        >>> s.add(b, c1, c2)
        >>> print_mass_moment(b)
        mass=75 moment=3921

  activate() → None

    Reset the idle timer on a body.

    If it was sleeping, wake it and any other bodies it was touching.

  property angle: float

    Rotation of the body in radians.

    When changing the rotation you may also want to call `Space.reindex_shapes_for_body()` to update the collision detection information for the attached shapes if plan to make any queries against the space. A body rotates around its center of gravity, not its position.

    Note

    If you get small/no changes to the angle when for example a ball is “rolling” down a slope it might be because the Circle shape attached to the body or the slope shape does not have any friction set.

  property angular_velocity: float

    The angular velocity of the body in radians per second.

  apply_force_at_local_point(force: Tuple[float, float], point: Tuple[float, float] = (0, 0)) → None

    Add the local force force to body as if applied from the body local point.

  apply_force_at_world_point(force: Tuple[float, float], point: Tuple[float, float]) → None

    Add the force force to body as if applied from the world point.

    People are sometimes confused by the difference between a force and an impulse. An impulse is a very large force applied over a very short period of time. Some examples are a ball hitting a wall or cannon firing. Chipmunk treats impulses as if they occur instantaneously by adding directly to the velocity of an object. Both impulses and forces are affected the mass of an object. Doubling the mass of the object will halve the effect.

  apply_impulse_at_local_point(impulse: Tuple[float, float], point: Tuple[float, float] = (0, 0)) → None

    Add the local impulse impulse to body as if applied from the body local point.

  apply_impulse_at_world_point(impulse: Tuple[float, float], point: Tuple[float, float]) → None

    Add the impulse impulse to body as if applied from the world point.

  property body_type: int

    The type of a body (`Body.DYNAMIC`, `Body.KINEMATIC` or `Body.STATIC`).

    When changing an body to a dynamic body, the mass and moment of inertia are recalculated from the shapes added to the body. Custom calculated moments of inertia are not preserved when changing types. This function cannot be called directly in a collision callback.

  property center_of_gravity: Vec2d

    Location of the center of gravity in body local coordinates.

    The default value is (0, 0), meaning the center of gravity is the same as the position of the body.

  property constraints: Set[Constraint]

    Get the constraints this body is attached to.

    It is not possible to detach a body from a constraint. The only way is to delete the constraint fully by removing it from any spaces and remove any other references to it. The body only keeps a weak reference to the constraint, meaning that the when all other references to the constraint are removed and the constraint is garbage collected it will automatically be removed from this collection as well.

  copy() → T

    Create a deep copy of this object.

  each_arbiter(func: Callable[[...], None], *args: Any, **kwargs: Any) → None

    Run func on each of the arbiters on this body.

    > `func(arbiter, *args, **kwargs) -> None`

    > Callback Parameters
    >   arbiter`Arbiter`

    >     The Arbiter

    >   args

    >     Optional parameters passed to the callback function.

    >   kwargs

    >     Optional keyword parameters passed on to the callback function.

    Warning

    Do not hold on to the Arbiter after the callback!

  property force: Vec2d

    Force applied to the center of gravity of the body.

    This value is reset for every time step. Note that this is not the total of forces acting on the body (such as from collisions), but the force applied manually from the apply force functions.

  property is_sleeping: bool

    Returns true if the body is sleeping.

  property kinetic_energy: float

    Get the kinetic energy of a body.

  local_to_world(v: Tuple[float, float]) → Vec2d

    Convert body local coordinates to world space coordinates

    Many things are defined in coordinates local to a body meaning that the (0,0) is at the center of gravity of the body and the axis rotate along with the body.

    Parameters:

      v – Vector in body local coordinates

  property mass: float

    Mass of the body.

  property moment: float

    Moment of inertia (MoI or sometimes just moment) of the body.

    The moment is like the rotational mass of a body.

  property position: Vec2d

    Position of the body.

    When changing the position you may also want to call `Space.reindex_shapes_for_body()` to update the collision detection information for the attached shapes if plan to make any queries against the space.

  property position_func

    The position callback function.

    The position callback function is called each time step and can be used to update the body’s position.

    > `func(body, dt) -> None`

  property rotation_vector: Vec2d

    The rotation vector for the body.

  property shapes: Set[Shape]

    Get the shapes attached to this body.

    The body only keeps a weak reference to the shapes and a live body wont prevent GC of the attached shapes

  sleep() → None

    Forces a body to fall asleep immediately even if it’s in midair.

    Cannot be called from a callback.

  sleep_with_group(body: Body) → None

    Force a body to fall asleep immediately along with other bodies in a group.

    When objects in Pymunk sleep, they sleep as a group of all objects that are touching or jointed together. When an object is woken up, all of the objects in its group are woken up. `Body.sleep_with_group()` allows you group sleeping objects together. It acts identically to `Body.sleep()` if you pass None as group by starting a new group. If you pass a sleeping body for group, body will be awoken when group is awoken. You can use this to initialize levels and start stacks of objects in a pre-sleeping state.

  property space: Space | None

    Get the `Space` that the body has been added to (or None).

  property torque: float

    The torque applied to the body.

    This value is reset for every time step.

  static update_position(body: Body, dt: float) → None

    Default rigid body position integration function.

    Updates the position of the body using Euler integration. Unlike the velocity function, it’s unlikely you’ll want to override this function. If you do, make sure you understand it’s source code (in Chipmunk) as it’s an important part of the collision/joint correction process.

  static update_velocity(body: Body, gravity: Tuple[float, float], damping: float, dt: float) → None

    Default rigid body velocity integration function.

    Updates the velocity of the body using Euler integration.

  property velocity: Vec2d

    Linear velocity of the center of gravity of the body.

  velocity_at_local_point(point: Tuple[float, float]) → Vec2d

    Get the absolute velocity of the rigid body at the given body local point

  velocity_at_world_point(point: Tuple[float, float]) → Vec2d

    Get the absolute velocity of the rigid body at the given world point

    It’s often useful to know the absolute velocity of a point on the surface of a body since the angular velocity affects everything except the center of gravity.

  property velocity_func

    The velocity callback function.

    The velocity callback function is called each time step, and can be used to set a body’s velocity.

    > `func(body : Body, gravity, damping, dt)`

    There are many cases when this can be useful. One example is individual gravity for some bodies, and another is to limit the velocity which is useful to prevent tunneling.

    Example of a callback that sets gravity to zero for a object.

        >>> import pymunk
        >>> space = pymunk.Space()
        >>> space.gravity = 0, 10
        >>> body = pymunk.Body(1,2)
        >>> space.add(body)
        >>> def zero_gravity(body, gravity, damping, dt):
        ...     pymunk.Body.update_velocity(body, (0,0), damping, dt)
        ...
        >>> body.velocity_func = zero_gravity
        >>> space.step(1)
        >>> space.step(1)
        >>> print(body.position, body.velocity)
        Vec2d(0.0, 0.0) Vec2d(0.0, 0.0)

    Example of a callback that limits the velocity:

        >>> import pymunk
        >>> body = pymunk.Body(1,2)
        >>> def limit_velocity(body, gravity, damping, dt):
        ...     max_velocity = 1000
        ...     pymunk.Body.update_velocity(body, gravity, damping, dt)
        ...     l = body.velocity.length
        ...     if l > max_velocity:
        ...         scale = max_velocity / l
        ...         body.velocity = body.velocity * scale
        ...
        >>> body.velocity_func = limit_velocity

  world_to_local(v: Tuple[float, float]) → Vec2d

    Convert world space coordinates to body local coordinates

    Parameters:

      v – Vector in world space coordinates

class pymunk.Circle(body: Body | None, radius: float, offset: Tuple[float, float] = (0, 0))

  Bases: `Shape`

  A circle shape defined by a radius

  This is the fastest and simplest collision shape

  __init__(body: Body | None, radius: float, offset: Tuple[float, float] = (0, 0)) → None

    body is the body attach the circle to, offset is the offset from the body’s center of gravity in body local coordinates.

    It is legal to send in None as body argument to indicate that this shape is not attached to a body. However, you must attach it to a body before adding the shape to a space or used for a space shape query.

  property area: float

    The calculated area of this shape.

  property bb: BB

    The bounding box `BB` of the shape.

    Only guaranteed to be valid after `Shape.cache_bb()` or `Space.step()` is called. Moving a body that a shape is connected to does not update it’s bounding box. For shapes used for queries that aren’t attached to bodies, you can also use `Shape.update()`.

  property body: Body | None

    The body this shape is attached to. Can be set to None to indicate that this shape doesnt belong to a body.

  cache_bb() → BB

    Update and returns the bounding box of this shape

  property center_of_gravity: Vec2d

    The calculated center of gravity of this shape.

  property collision_type: int

    User defined collision type for the shape.

    See `Space.add_collision_handler()` function for more information on when to use this property.

  copy() → T

    Create a deep copy of this object.

  property density: float

    The density of this shape.

    This is useful when you let Pymunk calculate the total mass and inertia of a body from the shapes attached to it. (Instead of setting the body mass and inertia directly)

  property elasticity: float

    Elasticity of the 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.

  property filter: ShapeFilter

    Set the collision `ShapeFilter` for this shape.

  property friction: float

    Friction coefficient.

    Pymunk uses the Coulomb friction model, a value of 0.0 is frictionless.

    A value over 1.0 is perfectly fine.

    Some real world example values from Wikipedia (Remember that it is what looks good that is important, not the exact value).

    Material | Other | Friction
    --- | --- | ---
    Aluminium | Steel | 0.61
    Copper | Steel | 0.53
    Brass | Steel | 0.51
    Cast iron | Copper | 1.05
    Cast iron | Zinc | 0.85
    Concrete (wet) | Rubber | 0.30
    Concrete (dry) | Rubber | 1.0
    Concrete | Wood | 0.62
    Copper | Glass | 0.68
    Glass | Glass | 0.94
    Metal | Wood | 0.5
    Polyethene | Steel | 0.2
    Steel | Steel | 0.80
    Steel | Teflon | 0.04
    Teflon (PTFE) | Teflon | 0.04
    Wood | Wood | 0.4

  property mass: float

    The mass of this shape.

    This is useful when you let Pymunk calculate the total mass and inertia of a body from the shapes attached to it. (Instead of setting the body mass and inertia directly)

  property moment: float

    The calculated moment of this shape.

  property offset: Vec2d

    Offset. (body space coordinates)

  point_query(p: Tuple[float, float]) → PointQueryInfo

    Check if the given point lies within the shape.

    A negative distance means the point is within the shape.

    Returns:

      Tuple of (distance, info)

    Return type:

      (float, `PointQueryInfo`)

  property radius: float

    The Radius of the circle

  segment_query(start: Tuple[float, float], end: Tuple[float, float], radius: float = 0) → SegmentQueryInfo

    Check if the line segment from start to end intersects the shape.

    Return type:

      `SegmentQueryInfo`

  property sensor: bool

    A boolean value if this shape is a sensor or not.

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

  shapes_collide(b: Shape) → ContactPointSet

    Get contact information about this shape and shape b.

    Return type:

      `ContactPointSet`

  property space: Space | None

    Get the `Space` that shape has been added to (or None).

  property surface_velocity: Vec2d

    The surface velocity of the object.

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

  unsafe_set_offset(o: Tuple[float, float]) → None

    Unsafe set the offset of the circle.

    Note

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

  unsafe_set_radius(r: float) → None

    Unsafe set the radius of the circle.

    Note

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

  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.

class pymunk.CollisionHandler(_handler: Any, space: Space)

  Bases: `object`

  A collision handler is a set of 4 function callbacks for the different collision events that Pymunk recognizes.

  Collision callbacks are closely associated with Arbiter objects. You should familiarize yourself with those as well.

  Note #1: Shapes tagged as sensors (Shape.sensor == true) never generate collisions that get processed, so collisions between sensors shapes and other shapes will never call the post_solve() callback. They still generate begin(), and separate() callbacks, and the pre_solve() callback is also called every frame even though there is no collision response. Note #2: pre_solve() callbacks are called before the sleeping algorithm runs. If an object falls asleep, its post_solve() callback won’t be called until it’s re-awoken.

  __init__(_handler: Any, space: Space) → None

    Initialize a CollisionHandler object from the Chipmunk equivalent struct and the Space.

    Note

    You should never need to create an instance of this class directly.

  property begin: Callable[[Arbiter, Space, Any], bool] | None

    Two shapes just started touching for the first time this step.

    `func(arbiter, space, data) -> bool`

    Return true from the callback to process the collision normally or false to cause pymunk to ignore the collision entirely. If you return false, the pre_solve and post_solve callbacks will never be run, but you will still recieve a separate event when the shapes stop overlapping.

  property data: Dict[Any, Any]

    Data property that get passed on into the callbacks.

    data is a dictionary and you can not replace it, only fill it with data.

    Usefull if the callback needs some extra data to perform its function.

  property post_solve: Callable[[Arbiter, Space, Any], None] | None

    Two shapes are touching and their collision response has been processed.

    `func(arbiter, space, data)`

    You can retrieve the collision impulse or kinetic energy at this time if you want to use it to calculate sound volumes or damage amounts. See Arbiter for more info.

  property pre_solve: Callable[[Arbiter, Space, Any], bool] | None

    Two shapes are touching during this step.

    `func(arbiter, space, data) -> bool`

    Return false from the callback to make pymunk ignore the collision this step or true to process it normally. Additionally, you may override collision values using Arbiter.friction, Arbiter.elasticity or Arbiter.surfaceVelocity to provide custom friction, elasticity, or surface velocity values. See Arbiter for more info.

  property separate: Callable[[Arbiter, Space, Any], None] | None

    Two shapes have just stopped touching for the first time this step.

    `func(arbiter, space, data)`

    To ensure that begin()/separate() are always called in balanced pairs, it will also be called when removing a shape while its in contact with something or when de-allocating the space.

class pymunk.ContactPoint(point_a: Vec2d, point_b: Vec2d, distance: float)

  Bases: `object`

  Contains information about a contact point.

  point_a and point_b are the contact position on the surface of each shape.

  distance is the penetration distance of the two shapes. Overlapping means it will be negative. This value is calculated as dot(point2 - point1), normal) and is ignored when you set the Arbiter.contact_point_set.

  __init__(point_a: Vec2d, point_b: Vec2d, distance: float) → None
  distance: float
  point_a: Vec2d
  point_b: Vec2d

class pymunk.ContactPointSet(normal: Vec2d, points: List[ContactPoint])

  Bases: `object`

  Contact point sets make getting contact information simpler.

  normal is the normal of the collision

  points is the array of contact points. Can be at most 2 points.

  __init__(normal: Vec2d, points: List[ContactPoint]) → None
  normal: Vec2d
  points: List[ContactPoint]

class pymunk.PointQueryInfo(shape: Shape | None, point: Vec2d, distance: float, gradient: Vec2d)

  Bases: `NamedTuple`

  PointQueryInfo holds the result of a point query made on a Shape or Space.

  distance: float

    The distance to the point. The distance is negative if the point is inside the shape.

  gradient: Vec2d

    The gradient of the signed distance function.

    The value should be similar to PointQueryInfo.point/PointQueryInfo.distance, but accurate even for very small values of info.distance.

  point: Vec2d

    The closest point on the shape’s surface. (in world space coordinates)

  shape: Shape | None

    The nearest shape, None if no shape was within range.

class pymunk.Poly(body: Body | None, vertices: Sequence[Tuple[float, float]], transform: Transform | None = None, radius: float = 0)

  Bases: `Shape`

  A convex polygon shape

  Slowest, but most flexible collision shape.

  __init__(body: Body | None, vertices: Sequence[Tuple[float, float]], transform: Transform | None = None, radius: float = 0) → None

    Create a polygon.

    A convex hull will be calculated from the vertexes automatically.

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

    It is legal to send in None as body argument to indicate that this shape is not attached to a body. However, you must attach it to a body before adding the shape to a space or used for a space shape query.

    Note

    Make sure to put the vertices around (0,0) or the shape might behave strange.

    Either directly place the vertices like the below example:

        >>> import pymunk
        >>> w, h = 10, 20
        >>> vs = [(-w/2,-h/2), (w/2,-h/2), (w/2,h/2), (-w/2,h/2)]
        >>> poly_good = pymunk.Poly(None, vs)
        >>> print(poly_good.center_of_gravity)
        Vec2d(0.0, 0.0)

    Or use a transform to move them:

        >>> import pymunk
        >>> width, height = 10, 20
        >>> vs = [(0, 0), (width, 0), (width, height), (0, height)]
        >>> poly_bad = pymunk.Poly(None, vs)
        >>> print(poly_bad.center_of_gravity)
        Vec2d(5.0, 10.0)
        >>> t = pymunk.Transform(tx=-width/2, ty=-height/2)
        >>> poly_good = pymunk.Poly(None, vs, transform=t)
        >>> print(poly_good.center_of_gravity)
        Vec2d(0.0, 0.0)

    Parameters:

      - body (Body) – The body to attach the poly to

      - vertices ([(float,float)]) – Define a convex hull of the polygon with a counterclockwise winding.

      - transform (Transform) – Transform will be applied to every vertex.

      - radius (float) – Set the radius of the poly shape

  property area: float

    The calculated area of this shape.

  property bb: BB

    The bounding box `BB` of the shape.

    Only guaranteed to be valid after `Shape.cache_bb()` or `Space.step()` is called. Moving a body that a shape is connected to does not update it’s bounding box. For shapes used for queries that aren’t attached to bodies, you can also use `Shape.update()`.

  property body: Body | None

    The body this shape is attached to. Can be set to None to indicate that this shape doesnt belong to a body.

  cache_bb() → BB

    Update and returns the bounding box of this shape

  property center_of_gravity: Vec2d

    The calculated center of gravity of this shape.

  property collision_type: int

    User defined collision type for the shape.

    See `Space.add_collision_handler()` function for more information on when to use this property.

  copy() → T

    Create a deep copy of this object.

  static create_box(body: Body | None, size: Tuple[float, float] = (10, 10), radius: float = 0) → Poly

    Convenience function to create a box given a width and height.

    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 the normal constructor Poly(…).

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

    Parameters:

      - body (Body) – The body to attach the poly to

      - size ((float, float)) – Size of the box as (width, height)

      - radius (float) – Radius of poly

    Return type:

      `Poly`

  static create_box_bb(body: Body | None, bb: BB, radius: float = 0) → Poly

    Convenience function to create a box shape from a `BB`.

    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 the normal constructor Poly(..).

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

    Parameters:

      - body (Body) – The body to attach the poly to

      - bb (BB) – Size of the box

      - radius (float) – Radius of poly

    Return type:

      `Poly`

  property density: float

    The density of this shape.

    This is useful when you let Pymunk calculate the total mass and inertia of a body from the shapes attached to it. (Instead of setting the body mass and inertia directly)

  property elasticity: float

    Elasticity of the 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.

  property filter: ShapeFilter

    Set the collision `ShapeFilter` for this shape.

  property friction: float

    Friction coefficient.

    Pymunk uses the Coulomb friction model, a value of 0.0 is frictionless.

    A value over 1.0 is perfectly fine.

    Some real world example values from Wikipedia (Remember that it is what looks good that is important, not the exact value).

    Material | Other | Friction
    --- | --- | ---
    Aluminium | Steel | 0.61
    Copper | Steel | 0.53
    Brass | Steel | 0.51
    Cast iron | Copper | 1.05
    Cast iron | Zinc | 0.85
    Concrete (wet) | Rubber | 0.30
    Concrete (dry) | Rubber | 1.0
    Concrete | Wood | 0.62
    Copper | Glass | 0.68
    Glass | Glass | 0.94
    Metal | Wood | 0.5
    Polyethene | Steel | 0.2
    Steel | Steel | 0.80
    Steel | Teflon | 0.04
    Teflon (PTFE) | Teflon | 0.04
    Wood | Wood | 0.4

  get_vertices() → List[Vec2d]

    Get the vertices in local coordinates for the polygon

    If you need the vertices in world coordinates then the vertices can be transformed by adding the body position and each vertex rotated by the body rotation in the following way:

        >>> import pymunk
        >>> b = pymunk.Body()
        >>> b.position = 1,2
        >>> b.angle = 0.5
        >>> shape = pymunk.Poly(b, [(0,0), (10,0), (10,10)])
        >>> for v in shape.get_vertices():
        ...     x,y = v.rotated(shape.body.angle) + shape.body.position
        ...     (int(x), int(y))
        (1, 2)
        (9, 6)
        (4, 15)

    Returns:

      The vertices in local coords

    Return type:

      [`Vec2d`]

  property mass: float

    The mass of this shape.

    This is useful when you let Pymunk calculate the total mass and inertia of a body from the shapes attached to it. (Instead of setting the body mass and inertia directly)

  property moment: float

    The calculated moment of this shape.

  point_query(p: Tuple[float, float]) → PointQueryInfo

    Check if the given point lies within the shape.

    A negative distance means the point is within the shape.

    Returns:

      Tuple of (distance, info)

    Return type:

      (float, `PointQueryInfo`)

  property radius: float

    The radius of the poly shape.

    Extends the poly in all directions with the given radius.

  segment_query(start: Tuple[float, float], end: Tuple[float, float], radius: float = 0) → SegmentQueryInfo

    Check if the line segment from start to end intersects the shape.

    Return type:

      `SegmentQueryInfo`

  property sensor: bool

    A boolean value if this shape is a sensor or not.

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

  shapes_collide(b: Shape) → ContactPointSet

    Get contact information about this shape and shape b.

    Return type:

      `ContactPointSet`

  property space: Space | None

    Get the `Space` that shape has been added to (or None).

  property surface_velocity: Vec2d

    The surface velocity of the object.

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

  unsafe_set_radius(radius: float) → None

    Unsafe set the radius of the poly.

    Note

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

  unsafe_set_vertices(vertices: Sequence[Tuple[float, float]], transform: Transform | None = None) → None

    Unsafe set the vertices of the poly.

    Note

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

  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.

class pymunk.Segment(body: Body | None, a: Tuple[float, float], b: Tuple[float, float], radius: float)

  Bases: `Shape`

  A line segment shape between two points

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

  __init__(body: Body | None, a: Tuple[float, float], b: Tuple[float, float], radius: float) → None

    Create a Segment

    It is legal to send in None as body argument to indicate that this shape is not attached to a body. However, you must attach it to a body before adding the shape to a space or used for a space shape query.

    Parameters:

      - body (Body) – The body to attach the segment to

      - a – The first endpoint of the segment

      - b – The second endpoint of the segment

      - radius (float) – The thickness of the segment

  property a: Vec2d

    The first of the two endpoints for this segment

  property area: float

    The calculated area of this shape.

  property b: Vec2d

    The second of the two endpoints for this segment

  property bb: BB

    The bounding box `BB` of the shape.

    Only guaranteed to be valid after `Shape.cache_bb()` or `Space.step()` is called. Moving a body that a shape is connected to does not update it’s bounding box. For shapes used for queries that aren’t attached to bodies, you can also use `Shape.update()`.

  property body: Body | None

    The body this shape is attached to. Can be set to None to indicate that this shape doesnt belong to a body.

  cache_bb() → BB

    Update and returns the bounding box of this shape

  property center_of_gravity: Vec2d

    The calculated center of gravity of this shape.

  property collision_type: int

    User defined collision type for the shape.

    See `Space.add_collision_handler()` function for more information on when to use this property.

  copy() → T

    Create a deep copy of this object.

  property density: float

    The density of this shape.

    This is useful when you let Pymunk calculate the total mass and inertia of a body from the shapes attached to it. (Instead of setting the body mass and inertia directly)

  property elasticity: float

    Elasticity of the 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.

  property filter: ShapeFilter

    Set the collision `ShapeFilter` for this shape.

  property friction: float

    Friction coefficient.

    Pymunk uses the Coulomb friction model, a value of 0.0 is frictionless.

    A value over 1.0 is perfectly fine.

    Some real world example values from Wikipedia (Remember that it is what looks good that is important, not the exact value).

    Material | Other | Friction
    --- | --- | ---
    Aluminium | Steel | 0.61
    Copper | Steel | 0.53
    Brass | Steel | 0.51
    Cast iron | Copper | 1.05
    Cast iron | Zinc | 0.85
    Concrete (wet) | Rubber | 0.30
    Concrete (dry) | Rubber | 1.0
    Concrete | Wood | 0.62
    Copper | Glass | 0.68
    Glass | Glass | 0.94
    Metal | Wood | 0.5
    Polyethene | Steel | 0.2
    Steel | Steel | 0.80
    Steel | Teflon | 0.04
    Teflon (PTFE) | Teflon | 0.04
    Wood | Wood | 0.4

  property mass: float

    The mass of this shape.

    This is useful when you let Pymunk calculate the total mass and inertia of a body from the shapes attached to it. (Instead of setting the body mass and inertia directly)

  property moment: float

    The calculated moment of this shape.

  property normal: Vec2d

    The normal

  point_query(p: Tuple[float, float]) → PointQueryInfo

    Check if the given point lies within the shape.

    A negative distance means the point is within the shape.

    Returns:

      Tuple of (distance, info)

    Return type:

      (float, `PointQueryInfo`)

  property radius: float

    The radius/thickness of the segment

  segment_query(start: Tuple[float, float], end: Tuple[float, float], radius: float = 0) → SegmentQueryInfo

    Check if the line segment from start to end intersects the shape.

    Return type:

      `SegmentQueryInfo`

  property sensor: bool

    A boolean value if this shape is a sensor or not.

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

  set_neighbors(prev: Tuple[float, float], next: Tuple[float, float]) → None

    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.

  shapes_collide(b: Shape) → ContactPointSet

    Get contact information about this shape and shape b.

    Return type:

      `ContactPointSet`

  property space: Space | None

    Get the `Space` that shape has been added to (or None).

  property surface_velocity: Vec2d

    The surface velocity of the object.

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

  unsafe_set_endpoints(a: Tuple[float, float], b: Tuple[float, float]) → None

    Set the two endpoints for this segment

    Note

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

  unsafe_set_radius(r: float) → None

    Set the radius of the segment

    Note

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

  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.

class pymunk.SegmentQueryInfo(shape: Shape | None, point: Vec2d, normal: Vec2d, alpha: float)

  Bases: `NamedTuple`

  Segment queries return more information than just a simple yes or no, they also return where a shape was hit and it’s surface normal at the hit point. This object hold that information.

  To test if the query hit something, check if SegmentQueryInfo.shape == None or not.

  Segment queries are like ray casting, but because not all spatial indexes allow processing infinitely long ray queries it is limited to segments. In practice this is still very fast and you don’t need to worry too much about the performance as long as you aren’t using extremely long segments for your queries.

  alpha: float

    The normalized distance along the query segment in the range [0, 1]

  normal: Vec2d

    The normal of the surface hit.

  point: Vec2d

    The point of impact.

  shape: Shape | None

    Shape that was hit, or None if no collision occured

class pymunk.Shape(shape: Shape)

  Bases: `PickleMixin`, `TypingAttrMixing`, `object`

  Base class for all the shapes.

  You usually dont want to create instances of this class directly but use one of the specialized shapes instead (`Circle`, `Poly` or `Segment`).

  All the shapes can be copied and pickled. If you copy/pickle a shape the body (if any) will also be copied.

  __init__(shape: Shape) → None
  property area: float

    The calculated area of this shape.

  property bb: BB

    The bounding box `BB` of the shape.

    Only guaranteed to be valid after `Shape.cache_bb()` or `Space.step()` is called. Moving a body that a shape is connected to does not update it’s bounding box. For shapes used for queries that aren’t attached to bodies, you can also use `Shape.update()`.

  property body: Body | None

    The body this shape is attached to. Can be set to None to indicate that this shape doesnt belong to a body.

  cache_bb() → BB

    Update and returns the bounding box of this shape

  property center_of_gravity: Vec2d

    The calculated center of gravity of this shape.

  property collision_type: int

    User defined collision type for the shape.

    See `Space.add_collision_handler()` function for more information on when to use this property.

  copy() → T

    Create a deep copy of this object.

  property density: float

    The density of this shape.

    This is useful when you let Pymunk calculate the total mass and inertia of a body from the shapes attached to it. (Instead of setting the body mass and inertia directly)

  property elasticity: float

    Elasticity of the 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.

  property filter: ShapeFilter

    Set the collision `ShapeFilter` for this shape.

  property friction: float

    Friction coefficient.

    Pymunk uses the Coulomb friction model, a value of 0.0 is frictionless.

    A value over 1.0 is perfectly fine.

    Some real world example values from Wikipedia (Remember that it is what looks good that is important, not the exact value).

    Material | Other | Friction
    --- | --- | ---
    Aluminium | Steel | 0.61
    Copper | Steel | 0.53
    Brass | Steel | 0.51
    Cast iron | Copper | 1.05
    Cast iron | Zinc | 0.85
    Concrete (wet) | Rubber | 0.30
    Concrete (dry) | Rubber | 1.0
    Concrete | Wood | 0.62
    Copper | Glass | 0.68
    Glass | Glass | 0.94
    Metal | Wood | 0.5
    Polyethene | Steel | 0.2
    Steel | Steel | 0.80
    Steel | Teflon | 0.04
    Teflon (PTFE) | Teflon | 0.04
    Wood | Wood | 0.4

  property mass: float

    The mass of this shape.

    This is useful when you let Pymunk calculate the total mass and inertia of a body from the shapes attached to it. (Instead of setting the body mass and inertia directly)

  property moment: float

    The calculated moment of this shape.

  point_query(p: Tuple[float, float]) → PointQueryInfo

    Check if the given point lies within the shape.

    A negative distance means the point is within the shape.

    Returns:

      Tuple of (distance, info)

    Return type:

      (float, `PointQueryInfo`)

  segment_query(start: Tuple[float, float], end: Tuple[float, float], radius: float = 0) → SegmentQueryInfo

    Check if the line segment from start to end intersects the shape.

    Return type:

      `SegmentQueryInfo`

  property sensor: bool

    A boolean value if this shape is a sensor or not.

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

  shapes_collide(b: Shape) → ContactPointSet

    Get contact information about this shape and shape b.

    Return type:

      `ContactPointSet`

  property space: Space | None

    Get the `Space` that shape has been added to (or None).

  property surface_velocity: Vec2d

    The surface velocity of the object.

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

  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.

class pymunk.ShapeFilter(group: int = 0, categories: int = 4294967295, mask: int = 4294967295)

  Bases: `NamedTuple`

  Pymunk 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 collides with.

  For example, a game has four collision categories: player (0), enemy (1), player bullet (2), and enemy bullet (3). Neither players nor enemies should not collide with their own bullets, and bullets should not collide with other bullets. However, players collide with enemy bullets, and enemies collide with player bullets.

  Object | Object Category | Category Mask
  --- | --- | ---
  Player | 0b00001 (1) | 0b11000 (4, 5)
  Enemy | 0b00010 (2) | 0b01110 (2, 3, 4)
  Player Bullet | 0b00100 (3) | 0b10001 (1, 5)
  Enemy Bullet | 0b01000 (4) | 0b10010 (2, 5)
  Walls | 0b10000 (5) | 0b01111 (1, 2, 3, 4)

  Note that in the table the categories and masks are written as binary values to clearly show the logic. To save space only 5 digits are used. The default type of categories and mask in ShapeFilter is an unsigned int, with a resolution of 32 bits. That means that the you have 32 bits to use, in binary notation that is 0b00000000000000000000000000000000 to 0b11111111111111111111111111111111 which can be written in hex as 0x00000000 to 0xFFFFFFFF.

  Everything in this example collides with walls. Additionally, the enemies collide with each other.

  By default, objects exist in every category and collide with every category.

  Objects can fall into multiple categories. For instance, you might have a category for a red team, and have a red player bullet. In the above example, each object only has one category.

  The default type of categories and mask in ShapeFilter is unsigned int which has a resolution of 32 bits on most systems.

  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.

  Example of how category and mask can be used to filter out player from enemy object:

      >>> import pymunk
      >>> s = pymunk.Space()
      >>> player_b = pymunk.Body(1,1)
      >>> player_c = pymunk.Circle(player_b, 10)
      >>> s.add(player_b, player_c)
      >>> player_c.filter = pymunk.ShapeFilter(categories=0b1)
      >>> hit = s.point_query_nearest((0,0), 0, pymunk.ShapeFilter())
      >>> hit != None
      True
      >>> filter = pymunk.ShapeFilter(mask=pymunk.ShapeFilter.ALL_MASKS() ^ 0b1)
      >>> hit = s.point_query_nearest((0,0), 0, filter)
      >>> hit == None
      True
      >>> enemy_b = pymunk.Body(1,1)
      >>> enemy_c = pymunk.Circle(enemy_b, 10)
      >>> s.add(enemy_b, enemy_c)
      >>> hit = s.point_query_nearest((0,0), 0, filter)
      >>> hit != None
      True

  static ALL_CATEGORIES() → int
  static ALL_MASKS() → int
  categories: int

    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.

  group: int

    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.

  mask: int

    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.

class pymunk.ShapeQueryInfo(shape: Shape | None, contact_point_set: ContactPointSet)

  Bases: `NamedTuple`

  Shape queries return more information than just a simple yes or no, they also return where a shape was hit. This object hold that information.

  contact_point_set: ContactPointSet

    Alias for field number 1

  shape: Shape | None

    Shape that was hit, or None if no collision occured

class pymunk.Space(threaded: bool = False)

  Bases: `PickleMixin`, `object`

  Spaces are the basic unit of simulation. You add rigid bodies, shapes and joints to it and then step them all forward together through time.

  A Space can be copied and pickled. Note that any post step callbacks are not copied. Also note that some internal collision cache data is not copied, which can make the simulation a bit unstable the first few steps of the fresh copy.

  Custom properties set on the space will also be copied/pickled.

  Any collision handlers will also be copied/pickled. Note that depending on the pickle protocol used there are some restrictions on what functions can be copied/pickled.

  Example:

      >>> import pymunk, pickle
      >>> space = pymunk.Space()
      >>> space2 = space.copy()
      >>> space3 = pickle.loads(pickle.dumps(space))

  __init__(threaded: bool = False) → None

    Create a new instance of the Space.

    If you set threaded=True the step function will run in threaded mode which might give a speedup. Note that even when you set threaded=True you still have to set Space.threads=2 to actually use more than one thread.

    Also note that threaded mode is not available on Windows, and setting threaded=True has no effect on that platform.

  add(*objs: Body | Shape | Constraint) → None

    Add one or many shapes, bodies or constraints (joints) to the space

    Unlike Chipmunk and earlier versions of pymunk its now allowed to add objects even from a callback during the simulation step. However, the add will not be performed until the end of the step.

  add_collision_handler(collision_type_a: int, collision_type_b: int) → CollisionHandler

    Return the `CollisionHandler` for collisions between objects of type collision_type_a and collision_type_b.

    Fill the desired collision callback functions, for details see the `CollisionHandler` object.

    Whenever shapes with collision types (`Shape.collision_type`) a and b collide, this handler will be used to process the collision events. When a new collision handler is created, the callbacks will all be set to builtin callbacks that perform the default behavior (call the wildcard handlers, and accept all collisions).

    Parameters:

      - collision_type_a (int) – Collision type a

      - collision_type_b (int) – Collision type b

    Return type:

      `CollisionHandler`

  add_default_collision_handler() → CollisionHandler

    Return a reference to the default collision handler or that is used to process all collisions that don’t have a more specific handler.

    The default behavior for each of the callbacks is to call the wildcard handlers, ANDing their return values together if applicable.

  add_post_step_callback(callback_function: Callable[[...], None], key: Hashable, *args: Any, **kwargs: Any) → bool

    Add a function to be called last in the next simulation step.

    Post step callbacks are registered as a function and an object used as a key. You can only register one post step callback per object.

    This function was more useful with earlier versions of pymunk where you weren’t allowed to use the add and remove methods on the space during a simulation step. But this function is still available for other uses and to keep backwards compatibility.

    Note

    If you remove a shape from the callback it will trigger the collision handler for the ‘separate’ event if it the shape was touching when removed.

    Note

    Post step callbacks are not included in pickle / copy of the space.

    Parameters:

      - callback_function (func(space : Space, key, *args, **kwargs)) – The callback function

      - key (Any) – This object is used as a key, you can only have one callback for a single object. It is passed on to the callback function.

      - args – Optional parameters passed to the callback

      - kwargs – Optional keyword parameters passed on to the callback

    Returns:

      True if key was not previously added, False otherwise

  add_wildcard_collision_handler(collision_type_a: int) → CollisionHandler

    Add a wildcard collision handler for given collision type.

    This handler will be used any time an object with this type collides with another object, regardless of its type. A good example is a projectile that should be destroyed the first time it hits anything. There may be a specific collision handler and two wildcard handlers. It’s up to the specific handler to decide if and when to call the wildcard handlers and what to do with their return values.

    When a new wildcard handler is created, the callbacks will all be set to builtin callbacks that perform the default behavior. (accept all collisions in `begin()` and `pre_solve()`, or do nothing for `post_solve()` and `separate()`.

    Parameters:

      collision_type_a (int) – Collision type

    Return type:

      `CollisionHandler`

  bb_query(bb: BB, shape_filter: ShapeFilter) → List[Shape]

    Query space to find all shapes near bb.

    The filter is applied to the query and follows the same rules as the collision detection.

    Note

    Sensor shapes are included in the result

    Parameters:

      - bb – Bounding box

      - shape_filter – Shape filter

    Return type:

      [`Shape`]

  property bodies: List[Body]

    A list of the bodies added to this space

  property collision_bias: float

    Determines how fast overlapping shapes are pushed apart.

    Pymunk allows fast moving objects to overlap, then fixes the overlap over time. Overlapping objects are unavoidable even if swept collisions are supported, and this is an efficient and stable way to deal with overlapping objects. The bias value controls what percentage of overlap remains unfixed after a second and defaults to ~0.2%. Valid values are in the range from 0 to 1, but using 0 is not recommended for stability reasons. The default value is calculated as cpfpow(1.0f - 0.1f, 60.0f) meaning that pymunk attempts to correct 10% of error ever 1/60th of a second.

    ..Note::

      Very very few games will need to change this value.

  property collision_persistence: float

    The number of frames the space keeps collision solutions around for.

    Helps prevent jittering contacts from getting worse. This defaults to 3.

    ..Note::

      Very very few games will need to change this value.

  property collision_slop: float

    Amount of overlap between shapes that is allowed.

    To improve stability, set this as high as you can without noticeable overlapping. It defaults to 0.1.

  property constraints: List[Constraint]

    A list of the constraints added to this space

  copy() → T

    Create a deep copy of this object.

  property current_time_step: float

    Retrieves the current (if you are in a callback from Space.step()) or most recent (outside of a Space.step() call) timestep.

  property damping: float

    Amount of simple damping to apply to the space.

    A value of 0.9 means that each body will lose 10% of its velocity per second. Defaults to 1. Like gravity, it can be overridden on a per body basis.

  debug_draw(options: SpaceDebugDrawOptions) → None

    Debug draw the current state of the space using the supplied drawing options.

    If you use a graphics backend that is already supported, such as pygame and pyglet, you can use the predefined options in their x_util modules, for example `pygame_util.DrawOptions`.

    Its also possible to write your own graphics backend, see `SpaceDebugDrawOptions`.

    If you require any advanced or optimized drawing its probably best to not use this function for the drawing since its meant for debugging and quick scripting.

  property gravity: Vec2d

    Global gravity applied to the space.

    Defaults to (0,0). Can be overridden on a per body basis by writing custom integration functions and set it on the body: `pymunk.Body.velocity_func()`.

  property idle_speed_threshold: float

    Speed threshold for a body to be considered idle.

    The default value of 0 means the space estimates a good threshold based on gravity.

  property iterations: int

    Iterations allow you to control the accuracy of the solver.

    Defaults to 10.

    Pymunk uses an iterative solver to figure out the forces between objects in the space. What this means is that it builds a big list of all of the collisions, joints, and other constraints between the bodies and makes several passes over the list considering each one individually. The number of passes it makes is the iteration count, and each iteration makes the solution more accurate. If you use too many iterations, the physics should look nice and solid, but may use up too much CPU time. If you use too few iterations, the simulation may seem mushy or bouncy when the objects should be solid. Setting the number of iterations lets you balance between CPU usage and the accuracy of the physics. Pymunk’s default of 10 iterations is sufficient for most simple games.

  point_query(point: Tuple[float, float], max_distance: float, shape_filter: ShapeFilter) → List[PointQueryInfo]

    Query space at point for shapes within the given distance range.

    The filter is applied to the query and follows the same rules as the collision detection. If a maxDistance of 0.0 is used, the point must lie inside a shape. Negative max_distance is also allowed meaning that the point must be a under a certain depth within a shape to be considered a match.

    See `ShapeFilter` for details about how the shape_filter parameter can be used.

    Note

    Sensor shapes are included in the result (In `Space.point_query_nearest()` they are not)

    Parameters:

      - point (`Vec2d` or (float,float)) – Where to check for collision in the Space

      - max_distance (float) – Match only within this distance

      - shape_filter (ShapeFilter) – Only pick shapes matching the filter

    Return type:

      [`PointQueryInfo`]

  point_query_nearest(point: Tuple[float, float], max_distance: float, shape_filter: ShapeFilter) → PointQueryInfo | None

    Query space at point the nearest shape within the given distance range.

    The filter is applied to the query and follows the same rules as the collision detection. If a maxDistance of 0.0 is used, the point must lie inside a shape. Negative max_distance is also allowed meaning that the point must be a under a certain depth within a shape to be considered a match.

    See `ShapeFilter` for details about how the shape_filter parameter can be used.

    Note

    Sensor shapes are not included in the result (In `Space.point_query()` they are)

    Parameters:

      - point (`Vec2d` or (float,float)) – Where to check for collision in the Space

      - max_distance (float) – Match only within this distance

      - shape_filter (ShapeFilter) – Only pick shapes matching the filter

    Return type:

      `PointQueryInfo` or None

  reindex_shape(shape: Shape) → None

    Update the collision detection data for a specific shape in the space.

  reindex_shapes_for_body(body: Body) → None

    Reindex all the shapes for a certain body.

  reindex_static() → None

    Update the collision detection info for the static shapes in the space. You only need to call this if you move one of the static shapes.

  remove(*objs: Body | Shape | Constraint) → None

    Remove one or many shapes, bodies or constraints from the space

    Unlike Chipmunk and earlier versions of Pymunk its now allowed to remove objects even from a callback during the simulation step. However, the removal will not be performed until the end of the step.

    Note

    When removing objects from the space, make sure you remove any other objects that reference it. For instance, when you remove a body, remove the joints and shapes attached to it.

  segment_query(start: Tuple[float, float], end: Tuple[float, float], radius: float, shape_filter: ShapeFilter) → List[SegmentQueryInfo]

    Query space along the line segment from start to end with the given radius.

    The filter is applied to the query and follows the same rules as the collision detection.

    See `ShapeFilter` for details about how the shape_filter parameter can be used.

    Note

    Sensor shapes are included in the result (In `Space.segment_query_first()` they are not)

    Parameters:

      - start – Starting point

      - end – End point

      - radius (float) – Radius

      - shape_filter (ShapeFilter) – Shape filter

    Return type:

      [`SegmentQueryInfo`]

  segment_query_first(start: Tuple[float, float], end: Tuple[float, float], radius: float, shape_filter: ShapeFilter) → SegmentQueryInfo | None

    Query space along the line segment from start to end with the given radius.

    The filter is applied to the query and follows the same rules as the collision detection.

    Note

    Sensor shapes are not included in the result (In `Space.segment_query()` they are)

    See `ShapeFilter` for details about how the shape_filter parameter can be used.

    Return type:

      `SegmentQueryInfo` or None

  shape_query(shape: Shape) → List[ShapeQueryInfo]

    Query a space for any shapes overlapping the given shape

    Note

    Sensor shapes are included in the result

    Parameters:

      shape (`Circle`, `Poly` or `Segment`) – Shape to query with

    Return type:

      [`ShapeQueryInfo`]

  property shapes: List[Shape]

    A list of all the shapes added to this space

    (includes both static and non-static)

  property sleep_time_threshold: float

    Time a group of bodies must remain idle in order to fall asleep.

    The default value of inf disables the sleeping algorithm.

  property static_body: Body

    A dedicated static body for the space.

    You don’t have to use it, but many times it can be convenient to have a static body together with the space.

  step(dt: float) → None

    Update the space for the given time step.

    Using a fixed time step is highly recommended. Doing so will increase the efficiency of the contact persistence, requiring an order of magnitude fewer iterations to resolve the collisions in the usual case.

    It is not the same to call step 10 times with a dt of 0.1 and calling it 100 times with a dt of 0.01 even if the end result is that the simulation moved forward 100 units. Performing multiple calls with a smaller dt creates a more stable and accurate simulation. Therefor it sometimes make sense to have a little for loop around the step call, like in this example:

        >>> import pymunk
        >>> s = pymunk.Space()
        >>> steps = 10
        >>> for x in range(steps): # move simulation forward 0.1 seconds:
        ...     s.step(0.1 / steps)

    Parameters:

      dt – Time step length

  property threads: int

    The number of threads to use for running the step function.

    Only valid when the Space was created with threaded=True. Currently the max limit is 2, setting a higher value wont have any effect. The default is 1 regardless if the Space was created with threaded=True, to keep determinism in the simulation. Note that Windows does not support the threaded solver.

  use_spatial_hash(dim: float, count: int) → None

    Switch the space to use a spatial hash instead of the bounding box tree.

    Pymunk supports two spatial indexes. The default is an axis-aligned bounding box tree inspired by the one used in the Bullet Physics library, but caching of overlapping leaves was added to give it very good temporal coherence. The tree requires no tuning, and most games will find that they get the best performance using from the tree. The other available spatial index type available is a spatial hash, which can be much faster when you have a very large number (1000s) of objects that are all the same size. For smaller numbers of objects, or objects that vary a lot in size, the spatial hash is usually much slower. It also requires tuning (usually through experimentation) to get the best possible performance.

    The spatial hash data is fairly size sensitive. dim is the size of the hash cells. Setting dim to the average collision shape size is likely to give the best performance. Setting dim too small will cause the shape to be inserted into many cells, setting it too low will cause too many objects into the same hash slot.

    count is the suggested minimum number of cells in the hash table. If there are too few cells, the spatial hash will return many false positives. Too many cells will be hard on the cache and waste memory. Setting count to ~10x the number of objects in the space is probably a good starting point. Tune from there if necessary.

    Parameters:

      - dim – the size of the hash cells

      - count – the suggested minimum number of cells in the hash table

class pymunk.SpaceDebugDrawOptions

  Bases: `object`

  SpaceDebugDrawOptions configures debug drawing.

  If appropriate its usually easy to use the supplied draw implementations directly: pymunk.pygame_util, pymunk.pyglet_util and pymunk.matplotlib_util.

  DRAW_COLLISION_POINTS: ClassVar[int]

    Draw collision points.

    Use on the flags property to control if collision points should be drawn or not.

  DRAW_CONSTRAINTS: ClassVar[int]

    Draw constraints.

    Use on the flags property to control if constraints should be drawn or not.

  DRAW_SHAPES: ClassVar[int]

    Draw shapes.

    Use on the flags property to control if shapes should be drawn or not.

  __init__() → None
  property collision_point_color: SpaceDebugColor

    The color of collisions.

    Should be a tuple of 4 ints between 0 and 255 (r,g,b,a).

    Example:

        >>> import pymunk
        >>> s = pymunk.Space()
        >>> b = pymunk.Body(1,10)
        >>> c1 = pymunk.Circle(b, 10)
        >>> c2 = pymunk.Circle(s.static_body, 10)
        >>> s.add(b, c1, c2)
        >>> s.step(1)
        >>> options = pymunk.SpaceDebugDrawOptions()
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=52.0, g=152.0, b=219.0, a=255.0))
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))
        draw_segment (Vec2d(8.0, 0.0), Vec2d(-8.0, 0.0), SpaceDebugColor(r=231.0, g=76.0, b=60.0, a=255.0))
        >>> options.collision_point_color = (10,20,30,40)
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=52.0, g=152.0, b=219.0, a=255.0))
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))
        draw_segment (Vec2d(8.0, 0.0), Vec2d(-8.0, 0.0), SpaceDebugColor(r=10.0, g=20.0, b=30.0, a=40.0))

  color_for_shape(shape: Shape) → SpaceDebugColor
  property constraint_color: SpaceDebugColor

    The color of constraints.

    Should be a tuple of 4 ints between 0 and 255 (r,g,b,a).

    Example:

        >>> import pymunk
        >>> s = pymunk.Space()
        >>> b = pymunk.Body(1, 10)
        >>> j = pymunk.PivotJoint(s.static_body, b, (0,0))
        >>> s.add(j)
        >>> options = pymunk.SpaceDebugDrawOptions()
        >>> s.debug_draw(options)
        draw_dot (5.0, Vec2d(0.0, 0.0), SpaceDebugColor(r=142.0, g=68.0, b=173.0, a=255.0))
        draw_dot (5.0, Vec2d(0.0, 0.0), SpaceDebugColor(r=142.0, g=68.0, b=173.0, a=255.0))
        >>> options.constraint_color = (10,20,30,40)
        >>> s.debug_draw(options)
        draw_dot (5.0, Vec2d(0.0, 0.0), SpaceDebugColor(r=10.0, g=20.0, b=30.0, a=40.0))
        draw_dot (5.0, Vec2d(0.0, 0.0), SpaceDebugColor(r=10.0, g=20.0, b=30.0, a=40.0))

  draw_circle(pos: Vec2d, angle: float, radius: float, outline_color: SpaceDebugColor, fill_color: SpaceDebugColor) → None
  draw_dot(size: float, pos: Vec2d, color: SpaceDebugColor) → None
  draw_fat_segment(a: Vec2d, b: Vec2d, radius: float, outline_color: SpaceDebugColor, fill_color: SpaceDebugColor) → None
  draw_polygon(verts: Sequence[Vec2d], radius: float, outline_color: SpaceDebugColor, fill_color: SpaceDebugColor) → None
  draw_segment(a: Vec2d, b: Vec2d, color: SpaceDebugColor) → None
  draw_shape(shape: Shape) → None
  property flags: int

    Bit flags which of shapes, joints and collisions should be drawn.

    By default all 3 flags are set, meaning shapes, joints and collisions will be drawn.

    Example using the basic text only DebugDraw implementation (normally you would the desired backend instead, such as pygame_util.DrawOptions or pyglet_util.DrawOptions):

        >>> import pymunk
        >>> s = pymunk.Space()
        >>> b = pymunk.Body()
        >>> c = pymunk.Circle(b, 10)
        >>> c.mass = 3
        >>> s.add(b, c)
        >>> s.add(pymunk.Circle(s.static_body, 3))
        >>> s.step(0.01)
        >>> options = pymunk.SpaceDebugDrawOptions()

        >>> # Only draw the shapes, nothing else:
        >>> options.flags = pymunk.SpaceDebugDrawOptions.DRAW_SHAPES
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=52.0, g=152.0, b=219.0, a=255.0))
        draw_circle (Vec2d(0.0, 0.0), 0.0, 3.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))

        >>> # Draw the shapes and collision points:
        >>> options.flags = pymunk.SpaceDebugDrawOptions.DRAW_SHAPES
        >>> options.flags |= pymunk.SpaceDebugDrawOptions.DRAW_COLLISION_POINTS
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=52.0, g=152.0, b=219.0, a=255.0))
        draw_circle (Vec2d(0.0, 0.0), 0.0, 3.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))
        draw_segment (Vec2d(1.0, 0.0), Vec2d(-8.0, 0.0), SpaceDebugColor(r=231.0, g=76.0, b=60.0, a=255.0))

  shape_dynamic_color: SpaceDebugColor = (52, 152, 219, 255)
  shape_kinematic_color: SpaceDebugColor = (39, 174, 96, 255)
  property shape_outline_color: SpaceDebugColor

    The outline color of shapes.

    Should be a tuple of 4 ints between 0 and 255 (r,g,b,a).

    Example:

        >>> import pymunk
        >>> s = pymunk.Space()
        >>> c = pymunk.Circle(s.static_body, 10)
        >>> s.add(c)
        >>> options = pymunk.SpaceDebugDrawOptions()
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))
        >>> options.shape_outline_color = (10,20,30,40)
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=10.0, g=20.0, b=30.0, a=40.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))

  shape_sleeping_color: SpaceDebugColor = (114, 148, 168, 255)
  shape_static_color: SpaceDebugColor = (149, 165, 166, 255)
  property transform: Transform

    The transform is applied before drawing, e.g for scaling or translation.

    Example:

        >>> import pymunk
        >>> s = pymunk.Space()
        >>> c = pymunk.Circle(s.static_body, 10)
        >>> s.add(c)
        >>> options = pymunk.SpaceDebugDrawOptions()
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))
        >>> options.transform = pymunk.Transform.scaling(2)
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 20.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))
        >>> options.transform = pymunk.Transform.translation(2,3)
        >>> s.debug_draw(options)
        draw_circle (Vec2d(2.0, 3.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))

    Note

    Not all tranformations are supported by the debug drawing logic. Uniform scaling and translation are supported, but not rotation, linear stretching or shearing.

class pymunk.Transform(a: float = 1, b: float = 0, c: float = 0, d: float = 1, tx: float = 0, ty: float = 0)

  Bases: `NamedTuple`

  Type used for 2x3 affine transforms.

  See wikipedia for details: http://en.wikipedia.org/wiki/Affine_transformation

  The properties map to the matrix in this way:

  a | c | tx
  b | d | ty
  0 | 0 | 1

  An instance can be created in this way:

      >>> Transform(1,2,3,4,5,6)
      Transform(a=1, b=2, c=3, d=4, tx=5, ty=6)

  Or overriding only some of the values (on a identity matrix):

      >>> Transform(b=3,ty=5)
      Transform(a=1, b=3, c=0, d=1, tx=0, ty=5)

  Or using one of the static methods like identity or translation (see each method for details).

  The Transform supports the matrix multiplicaiton operator (@) with a Transform, Vec2d or tuple as second operand, which produces a transformed Transform or Vec2d as result:

      >>> Transform.scaling(2) @ Transform.scaling(3)
      Transform(a=6, b=0, c=0, d=6, tx=0, ty=0)
      >>> Transform.scaling(2) @ Vec2d(1, 2)
      Vec2d(2, 4)

  __matmul__(other: Tuple[float, float]) → Vec2d
  __matmul__(other: Tuple[float, float, float, float, float, float]) → Transform

    Multiply this transform with a Transform, Vec2d or Tuple of size 2 or 6.

    Examples (Transform @ Transform):

        >>> Transform() @ Transform() == Transform.identity()
        True
        >>> Transform.translation(2,3) @ Transform.translation(4,5)
        Transform(a=1, b=0, c=0, d=1, tx=6, ty=8)
        >>> Transform.scaling(2) @ Transform.scaling(3)
        Transform(a=6, b=0, c=0, d=6, tx=0, ty=0)
        >>> Transform.scaling(2) @ Transform.translation(3,4)
        Transform(a=2, b=0, c=0, d=2, tx=6, ty=8)
        >>> Transform.translation(3,4) @ Transform.scaling(2)
        Transform(a=2, b=0, c=0, d=2, tx=3, ty=4)

    Examples (Transform @ Vec2d):

        >>> Transform.identity() @ Vec2d(1, 2)
        Vec2d(1, 2)
        >>> Transform.scaling(2) @ Vec2d(1, 2)
        Vec2d(2, 4)
        >>> Transform.translation(3,5) @ Vec2d(1, 2)
        Vec2d(4, 7)
        >>> Transform.rotation(1) @ Vec2d(1, 2) == Vec2d(1, 2).rotated(1)
        True

  a: float

    Alias for field number 0

  b: float

    Alias for field number 1

  c: float

    Alias for field number 2

  d: float

    Alias for field number 3

  static identity() → Transform

    The identity transform

    Example:

        >>> Transform.identity()
        Transform(a=1, b=0, c=0, d=1, tx=0, ty=0)

    Returns a Transform with this matrix:

    1 | 0 | 0
    0 | 1 | 0
    0 | 0 | 1

  rotated(t: float) → Transform

    Rotate this Transform and return the result.

        >>> '%.2f, %.2f, %.2f, %.2f, %.2f, %.2f' % Transform.rotation(1).rotated(0.5)
        '0.07, 1.00, -1.00, 0.07, 0.00, 0.00'
        >>> '%.2f, %.2f, %.2f, %.2f, %.2f, %.2f' % Transform.rotation(1.5)
        '0.07, 1.00, -1.00, 0.07, 0.00, 0.00'

  static rotation(t: float) → Transform

    A rotation transform

    Example to rotate by 1 rad:

        >>> '%.2f, %.2f, %.2f, %.2f, %.2f, %.2f' % Transform.rotation(1)
        '0.54, 0.84, -0.84, 0.54, 0.00, 0.00'

    Returns a Transform with this matrix:

    cos(t) | -sin(t) | 0
    sin(t) | cos(t) | 0
    0 | 0 | 1

  scaled(s: float) → Transform

    Scale this Transform and return the result.

    Example:

        >>> Transform.translation(3,4).scaled(2)
        Transform(a=2, b=0, c=0, d=2, tx=3, ty=4)

  static scaling(s: float) → Transform

    A scaling transform

    Example to scale 4x:

        >>> Transform.scaling(4)
        Transform(a=4, b=0, c=0, d=4, tx=0, ty=0)

    Returns a Transform with this matrix:

    s | 0 | 0
    0 | s | 0
    0 | 0 | 1

  translated(x: float, y: float) → Transform

    Translate this Transform and return the result.

    Example: >>> Transform.scaling(2).translated(3,4) Transform(a=2, b=0, c=0, d=2, tx=6, ty=8)

  static translation(x: float, y: float) → Transform

    A translation transform

    Example to translate (move) by 3 on x and 5 in y axis:

        >>> Transform.translation(3, 5)
        Transform(a=1, b=0, c=0, d=1, tx=3, ty=5)

    Returns a Transform with this matrix:

    1 | 0 | x
    0 | 1 | y
    0 | 0 | 1

  tx: float

    Alias for field number 4

  ty: float

    Alias for field number 5

class pymunk.Vec2d(x: float, y: float)

  Bases: `NamedTuple`

  2d vector class, supports vector and scalar operators, and also provides some high level functions.

  property angle: float

    The angle (in radians) of the vector

  property angle_degrees: float

    Gets the angle (in degrees) of a vector

  convert_to_basis(x_vector: Tuple[float, float], y_vector: Tuple[float, float]) → Vec2d
  cpvrotate(other: Tuple[float, float]) → Vec2d

    Uses complex multiplication to rotate this vector by the other.

  cpvunrotate(other: Tuple[float, float]) → Vec2d

    The inverse of cpvrotate

  cross(other: Tuple[float, float]) → float
    The cross product between the vector and other vector

      v1.cross(v2) -> v1.x*v2.y - v1.y*v2.x

    Returns:

      The cross product

  dot(other: Tuple[float, float]) → float
    The dot product between the vector and other vector

      v1.dot(v2) -> v1.x*v2.x + v1.y*v2.y

    Returns:

      The dot product

  get_angle_between(other: Tuple[float, float]) → float

    Get the angle between the vector and the other in radians

    Returns:

      The angle

  get_angle_degrees_between(other: Vec2d) → float

    Get the angle between the vector and the other in degrees

    Returns:

      The angle (in degrees)

  get_dist_sqrd(other: Tuple[float, float]) → float

    The squared distance between the vector and other vector It is more efficent to use this method than to call get_distance() first and then do a sqrt() on the result.

    Returns:

      The squared distance

  get_distance(other: Tuple[float, float]) → float

    The distance between the vector and other vector

    Returns:

      The distance

  get_length_sqrd() → float

    Get the squared length of the vector. If the squared length is enough it is more efficient to use this method instead of first calling get_length() or access .length and then do a x**2.

        >>> v = Vec2d(3,4)
        >>> v.get_length_sqrd() == v.length**2
        True

    Returns:

      The squared length

  property int_tuple: Tuple[int, int]

    The x and y values of this vector as a tuple of ints. Uses round() to round to closest int.

        >>> Vec2d(0.9, 2.4).int_tuple
        (1, 2)

  interpolate_to(other: Tuple[float, float], range: float) → Vec2d
  property length: float

    Get the length of the vector.

        >>> Vec2d(10, 0).length
        10.0
        >>> '%.2f' % Vec2d(10, 20).length
        '22.36'

    Returns:

      The length

  normalized() → Vec2d

    Get a normalized copy of the vector Note: This function will return 0 if the length of the vector is 0.

    Returns:

      A normalized vector

  normalized_and_length() → Tuple[Vec2d, float]

    Normalize the vector and return its length before the normalization

    Returns:

      The length before the normalization

  static ones() → Vec2d

    A vector where both x and y is 1

        >>> Vec2d.ones()
        Vec2d(1, 1)

  perpendicular() → Vec2d
  perpendicular_normal() → Vec2d
  projection(other: Tuple[float, float]) → Vec2d

    Project this vector on top of other vector

  rotated(angle_radians: float) → Vec2d

    Create and return a new vector by rotating this vector by angle_radians radians.

    Returns:

      Rotated vector

  rotated_degrees(angle_degrees: float) → Vec2d

    Create and return a new vector by rotating this vector by angle_degrees degrees.

    Returns:

      Rotade vector

  scale_to_length(length: float) → Vec2d

    Return a copy of this vector scaled to the given length.

        >>> '%.2f, %.2f' % Vec2d(10, 20).scale_to_length(20)
        '8.94, 17.89'

  static unit() → Vec2d

    A unit vector pointing up

        >>> Vec2d.unit()
        Vec2d(0, 1)

  x: float

    Alias for field number 0

  y: float

    Alias for field number 1

  static zero() → Vec2d

    A vector of zero length.

        >>> Vec2d.zero()
        Vec2d(0, 0)

pymunk.chipmunk_version: str = 'pymunk._chipmunk.ffi.string.decode-5dd7d774053145fa37f352d7a07d2f75a9bd8039'

  The Chipmunk version used with this Pymunk version.

  This property does not show a valid value in the compiled documentation, only when you actually import pymunk and do pymunk.chipmunk_version

  The string is in the following format: <cpVersionString>R<github commit of chipmunk> where cpVersionString is a version string set by Chipmunk and the git commit hash corresponds to the git hash of the chipmunk source from github.com/viblo/Chipmunk2D included with Pymunk.

pymunk.moment_for_box(mass: float, size: Tuple[float, float]) → float

  Calculate the moment of inertia for a solid box centered on the body.

  size should be a tuple of (width, height)

pymunk.moment_for_circle(mass: float, inner_radius: float, outer_radius: float, offset: Tuple[float, float] = (0, 0)) → float

  Calculate the moment of inertia for a hollow circle

  (A solid circle has an inner radius of 0)

pymunk.moment_for_poly(mass: float, vertices: Sequence[Tuple[float, float]], offset: Tuple[float, float] = (0, 0), radius: float = 0) → float

  Calculate the moment of inertia for a solid polygon shape.

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

pymunk.moment_for_segment(mass: float, a: Tuple[float, float], b: Tuple[float, float], radius: float) → float

  Calculate the moment of inertia for a line segment

  The endpoints a and b are relative to the body

pymunk.version: str = '6.5.2'

  The release version of this pymunk installation. Valid only if pymunk was installed from a source or binary distribution (i.e. not in a checked-out copy from git).