-- | Description: Low-level Haskell bindings to Chipmunk2D physics library -- Chiphunk is a __low-level__ Haskell bindings for the . -- It includes most (almost all) of the functions mentioned in the main documentation for Chipmunk2D, -- except for some (relatively) exotic ones, which may be added later per request. module Chiphunk.Low ( -- * Disclaymer -- | This bindings are so low-level so that they even require you to free the memory the Chipmunk2D has allocated -- for your objects. Module with more high-level api can be built around this low-level bingings at some point, -- in the meantime, however, you're advised to provide wrapper layer for your games so that you do not have to -- keep track of such things in the core of your game's logic. -- -- See below for an adoptation of the original Chipmunk documentation available -- . I've skipped some sections not related -- to the bindings, like the reason author chose C language in the first place and limitations of the C api. -- Obviously, it's thanks to that choice that I was able to write bindings around the library in Haskell. -- -- __Howling Moon Software is not affiliated with this bindings.__ -- __In all of the following \"I\" refers to the original documentation author for Chipmunk2D.__ -- * Chipmunk2D 7.0.2 -- | Chipmunk2D is a 2D rigid body physics library distributed under the MIT license. -- It is blazingly fast, portable, numerically stable, and easy to use. -- For this reason it has been used in hundreds of games across just about every system you can name. -- This includes top quality titles such as Night Sky for the Wii and many #1 sellers on the iPhone App Store! -- I’ve put thousands of hours of work over many years to make Chipmunk2D what it is today. -- If you find Chipmunk2D has saved you a lot of time, please consider -- . -- You’ll make an indie game developer very happy! -- | First of all, I would like to give a Erin Catto a big thank you, as Chipmunk2D’s impulse solver -- was directly inspired by his example code way back in 2006. -- (Now a full fledged physics engine all its own: ). -- His contact persistence idea allows for stable stacks of objects with very few iterations of the solver. -- My previous solver produced mushy piles of objects or required a large amount of CPU to operate stably. -- ** Support -- | The best way to get support is to visit the . -- There are plenty of people around using Chipmunk on the just about every platform -- I’ve ever heard of. If you are working on a commercial project, Howling Moon Software -- (my company) is . -- We can help with implementing custom Chipmunk behaviors, -- as well as priority bug fixes and performance tuning. -- ** Contact -- | If you find any bugs in Chipmunk, errors or broken links in this document, -- or have a question or comment about Chipmunk you can contact me at -- slembcke(at)gmail(dot)com. (email or GTalk) -- ** License -- | Chipmunk is licensed under the MIT license. -- -- @ -- Copyright (c) 2007-2015 Scott Lembcke and Howling Moon Software -- -- Permission is hereby granted, free of charge, to any person obtaining a copy -- of this software and associated documentation files (the "Software"), to deal -- in the Software without restriction, including without limitation the rights -- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -- copies of the Software, and to permit persons to whom the Software is -- furnished to do so, subject to the following conditions: -- -- The above copyright notice and this permission notice shall be included in -- all copies or substantial portions of the Software. -- -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -- SOFTWARE. -- @ -- -- This means that you do not have to buy a license or pay to use Chipmunk in commercial projects. (Though we really appreciate donations) -- ** Links -- | -- * – The official forum Chipmunk2D forum. -- -- * – The software company I co-founded. -- (We are available for contract work!) -- -- * – A small list of games we know that use Chipmunk. -- * Hello Chipmunk (World) -- | Hello world Chipmunk style. Create a simple simulation where a ball falls onto a static line segment, -- then rolls off. Print out the coordinates of the ball. -- -- @ -- module Main where -- -- import Chiphunk.Low -- import Text.Printf (printf) -- import Control.Concurrent (threadDelay) -- -- main :: IO () -- main = do -- let gravity = 'Vect' 0 (-100) -- -- -- Create an empty space. -- space <- 'spaceNew' -- 'spaceGravity' space $= gravity -- -- -- Add a static line segment shape for the ground. -- -- We'll make it slightly tilted so the ball will roll off. -- -- We attach it to a static body to tell Chipmunk it shouldn't be movable. -- static <- get $ 'spaceStaticBody' space -- ground <- 'segmentShapeNew' static (Vect (-20) 5) (Vect 20 (-5)) 0 -- 'shapeFriction' ground $= 1 -- 'spaceAddShape' space ground -- -- -- Now let's make a ball that falls onto the line and rolls off. -- -- First we need to make a cpBody to hold the physical properties of the object. -- -- These include the mass, position, velocity, angle, etc. of the object. -- -- Then we attach collision shapes to the 'Body' to give it a size and shape. -- -- let radius = 5 -- let mass = 1 -- -- -- The moment of inertia is like mass for rotation -- -- Use the momentFor* functions to help you approximate it. -- let moment = 'momentForCircle' mass 0 radius (Vect 0 0) -- -- -- The spaceAdd* functions return the thing that you are adding. -- ballBody <- 'bodyNew' mass moment -- 'spaceAddBody' space ballBody -- 'bodyPosition' ballBody $= Vect 0 15 -- -- -- Now we create the collision shape for the ball. -- -- You can create multiple collision shapes that point to the same body. -- -- They will all be attached to the body and move around to follow it. -- ballShape <- 'circleShapeNew' ballBody radius (Vect 0 0) -- 'spaceAddShape' space ballShape -- 'shapeFriction' ballShape $= 0.7 -- -- -- Now that it's all set up, we simulate all the objects in the space by -- -- stepping forward through time in small increments called steps. -- -- It is *highly* recommended to use a fixed size time step. -- let timeStep = 1/60 -- runFor 2 timeStep $ \\time -> do -- pos <- get $ 'bodyPosition' ballBody -- vel <- get $ 'bodyVelocity' ballBody -- printf "Time is %4.2f. ballBody is at (%6.2f, %6.2f), it's velocity is (%6.2f, %6.2f).\\n" -- time (vX pos) (vY pos) (vX vel) (vY vel) -- -- threadDelay $ round $ 1000000 * timeStep -- 'spaceStep' space timeStep -- -- 'shapeFree' ballShape -- 'bodyFree' ballBody -- 'shapeFree' ground -- 'spaceFree' space -- where -- runFor time step inner = go time -- where -- go time' -- | time' <= 0 = pure () -- | otherwise = inner (time - time') *> go (time' - step) -- @ -- * Chipmunk2D Basics -- ** Overview -- | There are 4 basic object types you will use in Chipmunk. -- | -- * __Rigid Bodies__ ('Body'): A rigid body holds the physical properties of an object. -- (mass, position, rotation, velocity, etc.) It does not have a shape until you attach one or more collision shapes -- to it. If you’ve done physics with particles before, rigid bodies differ in that they are able to rotate. -- Rigid bodies generally tend to have a 1:1 correlation to sprites in a game. -- You should structure your game so that you use the position and rotation of the rigid body -- for drawing your sprite. -- -- * __Collision Shapes__ ('Shape'): By attaching shapes to bodies, you can define the a body’s shape. -- You can attach as many shapes to a single body as you need to in order to define a complex shape. -- Shapes contain the surface properties of an object such as how much friction or elasticity it has. -- -- * __Constraints/Joints__ ('Constraint'): Constraints and joints describe how bodies are attached to each other. -- -- * __Spaces__ ('Space'): Spaces are containers for simulating objects in Chipmunk. -- You add bodies, shapes and joints to a space and then update the space as a whole. -- They control how all the rigid bodies, shapes, and constraints interact together. -- -- There is often confusion between rigid bodies and their collision shapes in Chipmunk -- and how they relate to sprites. A sprite would be a visual representation of an object, -- while a collision shape is an invisible property that defines how objects should collide. -- Both the sprite’s and the collision shape’s position and rotation are controlled by the motion of a rigid body. -- Generally you want to create a game object type that ties these things all together. -- ** Memory Management the Chipmunk way -- | For most of the structures you will use, Chipmunk uses a more or less standard and straightforward set -- of memory management functions. Take the 'Space' struct for example: -- -- * 'spaceNew' — Allocates and initializes a 'Space' struct. -- -- * 'spaceFree' — Destroys and frees the 'Space' struct. -- -- You are responsible for freeing any structs that you allocate. Chipmunk does not do reference counting or garbage collection. If you call a new function, you must call the matching free function or you will leak memory. -- ** Math the Chipmunk way -- | First of all, Chipmunk uses double precision floating point numbers throughout its calculations by default. -- This is likely to be faster on most modern desktop processors, -- and means you don’t have to worry as much about floating point accuracy. -- -- However, there are a few unique functions you will probably find very useful: fClamp , fLerp , fLerpConst -- * Chipmunk Vectors -- ** Struct Definition, Constants and Constructors , Vect (..) , vZero , cpv -- ** Operations -- | (__Note for bindings__: Most of these are Chipmunk2D-style aliases for 'Vect' typeclasses methods: -- 'Eq', 'Data.VectorSpace.AdditiveGroup', 'Data.VectorSpace.VectorSpace', 'Data.VectorSpace.InnerSpace', -- 'Data.Cross.HasCross2') , vEql , vAdd , vSub , vNeg , vMult , vDot , vCross , vPerp , vRPerp , vProject , vRotate , vUnRotate , vLength , vLengthSq , vLerp , vLerpConst , vSLerp , vSLerpConst , vNormalize , vClamp , vDist , vDistSq , vNear , vForAngle , vToAngle -- * Chipmunk Axis Aligned Bounding Boxes -- ** Struct Definition and Constructors , BB (..) , bbNew , bbNewForExtents , bbNewForCircle -- ** Operations , bbIntersects , bbContainsBB , bbContainsVect , bbMerge , bbExpand , bbCenter , bbArea , bbMergedArea , bbSegmentQuery , bbIntersectsSegment , bbClampVect , bbWrapVect -- * Chipmunk Rigid Bodies , Body -- ** Dynamic, Kinematic, and Static Bodies , BodyType (..) -- ** Movement, Teleportation, and Velocity -- | A graphics engine only needs to know the position of an object for each frame that its drawn. -- For a physics engine, this isn’t enough information to calculate a collision response. -- When you set the position of a body, you are effectively asking it to teleport itself. -- This means that it will instantly move to its new position instead of moving through space and time -- like a normal object. If you teleport an object so that it overlaps another one, -- the best the physics engine can do is to attempt to push the objects apart again -- since there is no information about their movement. This generally results in very mushy looking collisions. -- So instead of setting the position of an object, it’s better to set its velocity and allow the physics engine -- to update the position. That way it can resolve any resulting colisions natuarally since it knows -- how the objects were moving. This is why kinematic bodies work the way they do. -- You set the velocity, and the physics updates their position so the two are never out of sync. -- -- For dynamic bodies, setting the velocity explicitly every frame can cause problems. -- For example, a problem occurs when a light dynamic body (like a person) is pressed against a heavy dynamic body -- (like a car), and you set velocity of the small object so that it’s pushing it into the big body. -- To the physics engine, the change in velocity is the same as applying a large impulse -- (a very short, very large force). Even if the velocity is low, the large force can allow the small body -- to push the big body, even when it normally wouldn’t be able to. For example, a person walking into a car -- can overpower the car’s friction and cause it to creep along the ground slowly. -- Additionally, when you set the velocity of an object that is already in contact, -- it can cause the two objects to overlap by a small amount. The easiest way to avoid both of these problems -- is to make smaller changes to the body’s velocity, accelerating it over a fraction of a second -- instead of a single frame. An even better solution, which is covered more thoroughly later, -- is to use constraints to move the object. -- ** Memory Management Functions -- | Standard set of Chipmunk memory management functions. , bodyNew , bodyNewKinematic , bodyNewStatic , bodyFree -- ** Creating Dynamic Bodies -- | 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. -- -- 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 overwite your custom mass value when the shapes are added to the body. -- ** Properties -- | Chipmunk provides getter/setter functions for a number of properties on rigid bodies. -- Setting most properties automatically wakes the rigid bodies up if they were sleeping. , bodyType , bodyMass , bodyMoment , bodyPosition , bodyCenterOfGravity , bodyVelocity , bodyForce , bodyAngle , bodyAngularVelocity , bodyTorque , bodyRotation , bodySpace , bodyUserData -- ** Moment of Inertia and Area Helper Functions -- | Use the following functions to approximate the moment of inertia for your body, -- adding the results together if you want to use more than one. , momentForCircle , momentForSegment , momentForPoly , momentForBox -- | Use the following functions to get the area for common Chipmunk shapes if you want to approximate masses -- or density or whatnot. , areaForCircle , areaForSegment , areaForPoly -- ** Coordinate Conversion Functions -- | 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. , bodyLocalToWorld , bodyWorldToLocal -- ** Velocity Conversion Functions -- | 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. , bodyVelocityAtWorldPoint -- ** Applying Forces and Torques -- | 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. , bodyApplyForceAtWorldPoint , bodyApplyForceAtLocalPoint , bodyApplyImpulseAtWorldPoint , bodyApplyImpulseAtLocalPoint -- ** Sleeping Functions -- | Chipmunk supports a sleeping feature which improves performance by not simulating groups of objects -- that aren’t moving. Read more about it in the 'Space' section. , bodyIsSleeping , bodyActivate , bodySleep , bodyActivateStatic , bodySleepWithGroup -- ** Iterators , BodyShapeIteratorFunc , bodyEachShape , BodyConstraintIteratorFunc , bodyEachConstraint , BodyArbiterIteratorFunc , bodyEachArbiter -- * Chipmunk Collision Shapes , Shape -- ** Properties -- | Chipmunk provides getter/setter functions for a number of properties on collision shapes. -- Setting most properties will automatically wake the attached rigid body, if it’s sleeping. , shapeBody , shapeBB , shapeSensor , shapeElasticity , shapeFriction , shapeSurfaceVelocity , shapeCollisionType , shapeMass , shapeDensity , ShapeFilter (..) , shapeFilter , shapeSpace , shapeUserData -- ** Fast Collision Filtering using ShapeFilter -- | 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. -- -- 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\" | 1 | 4, 5 | -- +-----------------+-----------------+---------------+ -- | \"Enemy\" | 2 | 2, 3, 5 | -- +-----------------+-----------------+---------------+ -- | "Player Bullet" | 3 | 1, 5 | -- +-----------------+-----------------+---------------+ -- | "Enemy Bullet" | 4 | 2, 5 | -- +-----------------+-----------------+---------------+ -- | \"Walls\" | 5 | 1, 2, 3, 4 | -- +-----------------+-----------------+---------------+ -- -- Note that everything in this example collides with walls. Additionally, the enemies collide with eachother. -- -- 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. -- -- 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. -- ** Memory Management Functions , shapeFree -- ** Misc functions , shapeCacheBB , shapeUpdate -- ** Working With Circle Shapes , circleShapeNew -- ** Working With Segment Shapes , segmentShapeNew , segmentShapeNeighbors -- ** Working With Polygon Shapes , polyShapeNew , polyShapeNewRaw -- *** Boxes -- | Because boxes are so common in physics games, Chipmunk provides shortcuts to create box shaped polygons. -- The boxes will always be centered at the center of gravity of the body you are attaching them to. -- Adding a small radius will bevel the corners and can significantly reduce problems -- where the box gets stuck on seams in your geometry. If you want to create an off-center box, -- you will need to use 'polyShapeNew'. , boxShapeNew , boxShapeNew2 -- *** Poly Shape Helper Functions , centroidForPoly -- *** Convex Hull Helper Functions , convexHull , convexDecomposition -- ** Modifying 'Shape's -- | The short answer is that you can’t because the changes would be only picked up as a change to the position -- of the shape’s surface, but not its velocity. -- ** Notes -- | -- * You can attach multiple collision shapes to a rigid body. This should allow you to create almost any shape -- you could possibly need. -- -- * Shapes attached to the same rigid body will never generate collisions. You don’t have to worry -- about overlap when attaching multiple shapes to a rigid body. -- -- * Make sure you add both the body and its collision shapes to a space. -- * Chipmunk Spaces , Space -- ** What Are Iterations, and Why Should I Care? -- | Chipmunk 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. -- Chipmunk’s default of 10 iterations is sufficient for most simple games. -- ** Sleeping -- | Spaces can disable entire groups of objects that have stopped moving to save CPU time and battery life. -- In order to use this feature you must do two things. You must enable sleeping explicitly -- by choosing a time threshold value with 'spaceSetSleepTimeThreshold'. This threshold is the amount of time -- something must be idle before it falls asleep. 'spaceSetIdleSpeedThreshold' defines what is considered idle. -- If you do not set idle speed threshold explicitly, a value will be chosen automatically -- based on the current amount of gravity. Be mindful that objects cannot fall asleep if they are touching -- or jointed to a kinematic body. -- ** Properties , spaceIterations , spaceGravity , spaceDamping , spaceIdleSpeedThreshold , spaceSleepTimeThreshold , spaceCollisionSlop , spaceCollisionBias , spaceCollisionPersistence , spaceCurrentTimeStep , spaceIsLocked , spaceUserData , spaceStaticBody -- ** Memory Management Functions -- | More standard Chipmunk memory functions. , spaceNew , spaceFree -- ** Operations -- | These functions add and remove shapes, bodies and constraints from space. The add/remove functions -- cannot be called from within a callback other than a 'postStep' callback (which is different than a 'postSolve' -- callback!). Attempting to add or remove objects from the space while 'spaceStep' is still executing -- will throw an assertion. See the callbacks section for more information. Be careful not to free bodies -- before removing shapes and constraints attached to them or you will cause crashes.. -- The contains functions allow you to check if an object has been added to the space or not. , spaceAddShape , spaceAddBody , spaceAddConstraint , spaceRemoveShape , spaceRemoveBody , spaceRemoveConstraint , spaceContainsShape , spaceContainsBody , spaceContainsConstraint -- ** Spatial Indexing -- | Occasionally, you might want to update the collision detection data for a shape. -- If you move a static shape or a static body you must do this to let Chipmunk know -- it needs to have its collision detection data updated. You may also want to manually update the collision data -- for normal shapes if you move them and still want to perform queries against them -- before the next call to 'spaceStep'. , spaceReindexShape , spaceReindexShapesForBody , spaceReindexStatic -- ** Iterators , SpaceBodyIteratorFunc , spaceEachBody , SpaceShapeIteratorFunc , spaceEachShape , SpaceConstraintIteratorFunc , spaceEachConstraint -- ** Simulating the Space , spaceStep -- * Notes -- | -- * 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. -- -- * Using more iterations or smaller time steps will increase the physics quality, but also increase the CPU usage. -- * Chipmunk Constraints , Constraint -- ** What constraints are and what they are not -- | Constraints in Chipmunk are all velocity based constraints. -- This means that they act primarily by synchronizing the velocity of two bodies. -- A pivot joint holds two anchor points on two separate bodies together by defining equations that say -- that the velocity of the anchor points must be the same and calculating impulses to apply to the bodies -- to try and keep it that way. A constraint takes a velocity as it’s primary input and produces a velocity change -- as its output. Some constraints, (joints in particular) apply velocity changes to correct differences -- in positions. More about this in the next section. -- -- A spring connected between two bodies is not a constraint. It’s very constraint-like as it creates forces -- that affect the velocities of the two bodies, but a spring takes distances as input and produces forces -- as its output. If a spring is not a constraint, then why do I have two varieties of spring constraints you ask? -- The reason is because they are damped springs. The damping associated with the spring is a true constraint -- that creates velocity changes based on the relative velocities of the two bodies it links. -- As it is convenient to put a damper and a spring together most of the time, I figured I might as well just apply -- the spring force as part of the constraint instead of having a damper constraint and having the user -- calculate and apply their own spring forces separately. -- ** Properties , constraintBodyA , constraintBodyB , constraintMaxForce , constraintErrorBias , constraintMaxBias , constraintSpace , constraintCollideBodies , constraintUserData , constraintImpulse -- ** Error correction by Feedback -- | Joints in Chipmunk are not perfect. A pin joint can’t maintain the exact correct distance between its anchor -- points, nor can a pivot joint hold its anchor points completely together. Instead, they are designed -- to deal with this by correcting themselves over time. Since Chipmunk 5, you have a fair amount of extra control -- over how joints correct themselves and can even use this ability to create physical effects -- that allow you to use joints in unique ways: -- -- * Servo motors – Ex: open/close doors or rotate things without going over a maximum force. -- -- * Winches – Pull one object towards another at a constant speed without going over a maximum force. -- -- * Mouse manipulation – Interact with objects smoothly given coarse/shaky mouse input. -- -- There are three properties of 'Constraint' structs that control the error correction, -- maxForce, maxBias, and biasCoef. maxForce is pretty self explanatory, a joint or constraint -- will not be able to use more than this amount of force in order to function. If it needs more force -- to be able to hold itself together, it will fall apart. maxBias is the maximum speed at which error correction -- can be applied. If you change a property on a joint so that the joint will have to correct itself, -- it normally does so very quickly. By setting a maxSpeed you can make the joint work like a servo, -- correcting itself at a constant rate over a longer period of time. Lastly, biasCoef is the percentage -- of error corrected every step before clamping to a maximum speed. You can use this -- to make joints correct themselves smoothly instead of at a constant speed, but is probably the least useful -- of the three properties by far. -- ** Constraints and Collision Shapes -- | Neither constraints or collision shapes have any knowledge of the other. -- When connecting joints to a body the anchor points don’t need to be inside of any shapes attached to the body -- and it often makes sense that they shouldn’t. Also, adding a constraint between two bodies -- doesn’t prevent their collision shapes from colliding. In fact, this is the primary reason -- that the collision group property exists. -- ** Video Tour of Current Joint Types -- | http://www.youtube.com/watch?v=ZgJJZTS0aMM -- ** Shared Memory Management Functions , constraintFree -- ** Constraint Types -- *** Pin Joints , pinJointNew -- **** Properties , pinJointAnchorA , pinJointAnchorB , pinJointDist -- *** Slide Joints , slideJointNew -- **** Properties , slideJointAnchorA , slideJointAnchorB , slideJointMin , slideJointMax -- *** Pivot Joints -- | (__Note for bindings__: So each instance of pivot joint can be replaced with pin joint with dist of 0?) , pivotJointNew , pivotJointNew2 -- **** Properties , pivotJointAnchorA , pivotJointAnchorB -- *** Groove Joint , grooveJointNew -- **** Properties , grooveJointGrooveA , grooveJointGrooveB , grooveJointAnchorB -- *** Damped Spring , dampedSpringNew -- **** Properties , dampedSpringAnchorA , dampedSpringAnchorB , dampedSpringRestLength , dampedSpringStiffness , dampedSpringDamping -- *** Damped Rotary Spring -- | Like a damped spring, but works in an angular fashion. , dampedRotarySpringNew -- **** Properties , dampedRotarySpringRestAngle , dampedRotarySpringStiffness , dampedRotarySpringDamping -- *** Rotary Limit Joint -- | Constrains the relative rotations of two bodies. -- It is implemented so that it’s possible to for the range to be greater than a full revolution. , rotaryLimitJointNew -- **** Properties , rotaryLimitJointMin , rotaryLimitJointMax -- *** Ratchet Joint -- | Works like a socket wrench. , ratchetJointNew -- **** Properties , ratchetJointAngle , ratchetJointPhase , ratchetJointRatchet -- *** Gear Joint -- | Keeps the angular velocity ratio of a pair of bodies constant. , gearJointNew -- **** Properties , gearJointPhase , gearJointRatio -- *** Simple Motor -- | Keeps the relative angular velocity of a pair of bodies constant. -- You will usually want to set an force (torque) maximum for motors as otherwise -- they will be able to apply a nearly infinite torque to keep the bodies moving. , simpleMotorNew -- **** Properties , simpleMotorRate -- ** Notes -- | * You can add multiple joints between two bodies, but make sure that they don’t fight. -- Doing so can cause the bodies jitter or spin violently. -- * Overview of Collision Detection in Chipmunk -- | In order to make collision detection in Chipmunk as fast as possible, the process is broken down -- into several stages. While I’ve tried to keep it conceptually simple, the implementation can be a bit daunting. -- Fortunately as a user of the library, you don’t need to understand everything about how it works. -- Though if you are trying to squeeze every bit of performance out of Chipmunk, understanding this section -- can be helpful. -- ** Spatial Indexing -- | A for loop that checks every object against every other object in the scene would be very slow. -- So the first stage of the collision detection, commonly called the broadphase, uses a high level -- spatial algorithm to decide which pairs of objects to check for collisions. -- Currently Chipmunk supports two spatial indexes, an axis-aligned bounding box tree and a spatial hash. -- These spatial indexes are able to quickly identify which pairs of shapes are near each other -- and should be checked for a collision. -- ** Fast Collision Filtering -- | After the spatial index figures out which pairs of shapes are likely to be near each other, -- it passes each pair back to the space using a callback to perform some additional filtering on the pairs. -- Before doing anything else, Chipmunk performs a few quick tests to check if shapes should collide. -- -- * __Bounding Box Test__: The shapes are not colliding if their bounding boxes are not overlapping. -- Objects like diagonal line segments can trigger a lot of false positives here, -- but it’s unlikely to be something you should worry about. -- -- * __Category Mask Test__: The categories of each shape are bitwise ANDed against the category mask -- of the other shape. If either result is 0, the shapes do not collide. -- -- * __Group Test__: Shapes shouldn’t collide with other shapes in the same non-zero group. -- ** Constraint Based Filtering -- | After fast collision filtering, Chipmunk checks the list of joints on one of the bodies -- to see if it has a constraint that attaches it to the other body. If that constraint’s collideBodies -- property is false, the collision will be ignored. This check is often very fast -- since most scenes don’t contain a lot of constraints. -- ** Primitive Shape to Shape Collision Detection -- | The most expensive test is to actually check for overlap based on their geometry. -- Circle to circle and circle to line collisions are very fast. Segment to segment and poly to poly collisions -- are handled using the GJK/EPA algorithms, and get more expensive as the number of vertexes increases. -- Simpler shapes make for faster collisions, and often more important, fewer collision points -- for the solver to run. Chipmunk uses a small dispatch table to figure out which function to use to check -- if the shapes overlap. -- -- Without going into too much detail, the GJK algorithm checks the distance between two objects, -- and the EPA algorithm checks how much they are overlapping. If you give you segment and poly shapes -- a small radius when creating them, the EPA algorithm can usually be skipped, speeding up the collision detection -- considerably. The radius should be at least as big as the amount of allowed collision slop. -- ** Collision Handler Filtering -- | After checking if two shapes overlap Chipmunk will look to see if you have defined a collision handler -- for the collision types of the shapes. This is vital to process collisions events for the gameplay, -- but also gives you a very flexible way to filter out collisions. The return value of the begin and preSolve -- callbacks determines whether or not the colliding pair of shapes is discarded or not. -- Returning true will keep the pair, false will discard it. Rejecting a collision from a begin callback -- is permanent, rejecting it from the preSolve only applies to the step it occured in. If you don’t define -- a handler for the given collision types, Chipmunk will call the space’s default handler, which by default -- is defined to simply accept all collisions. -- -- Wildcard collisions can also return a value, but they are handled in a more complicated way. -- When you create a collision handler between two specific collision types, it’s your responsibility -- to decide when to call the wildcard handlers and what to do with their return values. -- Otherwise, the default is to call the wildcard handler for the first type, then the second type, -- and use a logical AND of their return values as filtering value. See DefaultBegin() in cpSpace.c -- for more information. -- -- While using callbacks to filter collisions is the most flexible way, keep in mind that by the time your callback -- is called all of the most expensive collision detection has already been done. For simulations -- with a lot of colliding objects each frame, the time spent finding collisions is small compared to the time -- spent solving the physics for them so it may not be a big deal. Fast collision filtering should be preferred -- if possible. -- * Collision Callbacks -- | A physics library without any events or feedback would not be very useful for games. -- How would you know when the player bumped into an enemy so that you could take some health points away? -- How would you know how hard the car hit something so you don’t play a loud crash noise when a pebble hits it? -- What if you need to decide if a collision should be ignored based on specific conditions, -- like implementing one way platforms? Chipmunk has a number of powerful callback systems -- that you can use to solve these problems. -- ** Collision Handlers -- | Collision handler function types. While all of them take an arbiter, space, and a user data pointer, -- only the begin and preSolve callbacks return a value. See above for more information. , CollisionCallback -- Collision callbacks are closely associated with 'Arbiter' structs. -- You should familiarize yourself with those as well. -- -- __Note__: Shapes tagged as sensors (cpShape.sensor == true) never generate collisions that get processed, -- so collisions between sensors shapes and other shapes will never call the postSolve callback. -- They still generate begin, and separate callbacks, and the preSolve callback is also called -- every frame even though there is no collision response. -- -- __Note #2__: preSolve callbacks are called before the sleeping algorithm runs. -- If an object falls asleep, its postSolve callback won’t be called until it’s reawoken. , CollisionType , CollisionHandler (..) , CollisionHandlerPtr , spaceAddCollisionHandler , spaceAddWildcardHandler , spaceAddDefaultCollisionHandler , modifyCollisionHandler , mkCallback , mkCallbackB -- ** Post-Step Callbacks -- | Post-step callbacks are the one place where you can break the rules about adding or removing objects -- from within a callback. In fact, their primary function is to help you safely remove objects from the space -- that you wanted to disable or destroy in a collision or query callback. -- -- Post step callbacks are registered as a function and a pointer that is used as a key. -- You can only register one postStep callback per key. This prevents you from accidentally removing -- an object more than once. For instance, say that you get a collision callback between a bullet and object A. -- You want to destroy both the bullet and object A, so you register a postStep callback -- to safely remove them from your game. Then you get a second collision callback between the bullet and object B. -- You register a postStep callback to remove object B, and a second postStep callback to remove the bullet. -- Because you can only register one callback per key, the postStep callback for the bullet -- will only be called once and you can’t accidentally try to remove it twice. , PostStepFunc , spaceAddPostStepCallback -- ** Examples -- | See -- -- for more information. -- * Chipmunk Collision Pairs , Arbiter -- ** Memory Management -- | You will never need to create or free an arbiter. More importantly, -- because they are entirely managed by the space you should never store a reference to an arbiter -- as you don’t know when they will be freed or reused. Use them within the callback where they are given to you -- and then forget about them or copy out the information you need. -- ** Properties , arbiterRestitution , arbiterFriction , arbiterSurfaceVelocity , arbiterUserData -- *** Collision Point(s) , arbiterCount , arbiterNormal , arbiterPointA , arbiterPointB , arbiterDepth -- *** Other , arbiterIsFirstContact , arbiterIsRemoval -- *** Bodies and shapes , arbiterShapes , arbiterBodies -- *** Running wildcard handlers -- | These functions invoke the wildcard handlers for a given collision. For custom collision handlers -- between specific types or overriding the default handler, you must decide how to invoke the wildcard handlers -- since it may be important to call the wildcards first, last, or possibly skip them entirely. -- For the begin and preSolve callbacks, you also need to decide what to do with their return values -- since they may not agree with each other or the specific handler they were called from. -- Every collision handler is defined for two types, the “A” variants of these functions call the wildcard handler -- for the first type, and the “B” variants call the handler for the second type. , arbiterCallWildcardBeginA , arbiterCallWildcardBeginB , arbiterCallWildcardPreSolveA , arbiterCallWildcardPreSolveB , arbiterCallWildcardPostSolveA , arbiterCallWildcardPostSolveB , arbiterCallWildcardSeparateA , arbiterCallWildcardSeparateB -- * Misc , DataPtr , Transform (..) -- * Re-exports , nullPtr , HasGetter (..) , HasSetter (..) ) where import Foreign import Data.StateVar import Chiphunk.Low.Types import Chiphunk.Low.Math import Chiphunk.Low.Helper import Chiphunk.Low.Vect import Chiphunk.Low.BB import Chiphunk.Low.Body import Chiphunk.Low.Shape import Chiphunk.Low.Space import Chiphunk.Low.Constraint import Chiphunk.Low.Callback import Chiphunk.Low.Arbiter