Timm Murray

NAME

Games::Chipmunk - Perl API for the Chipmunk 2D v7 physics library

SYNOPSIS

    use strict;
    use warnings;
    use Games::Chipmunk;

    # cpVect is a 2D vector and cpv() is a shortcut for initializing them.
    my $gravity = cpv(0, -100);

    # Create an empty space.
    my $space = cpSpaceNew();
    cpSpaceSetGravity($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 space->staticBody to tell Chipmunk it shouldn't be movable.
    my $ground = cpSegmentShapeNew(
        cpSpaceGetStaticBody( $space ), cpv(-20, 5), cpv(20, -5), 0 );
    cpShapeSetFriction($ground, 1);
    cpSpaceAddShape($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 cpBody to give it a size and shape.

    my $radius = 5;
    my $mass = 1;

    # The moment of inertia is like mass for rotation
    # Use the cpMomentFor*() functions to help you approximate it.
    my $moment = cpMomentForCircle($mass, 0, $radius, $CPV_ZERO);

    # The cpSpaceAdd*() functions return the thing that you are adding.
    # It's convenient to create and add an object in one line.
    my $ballBody = cpSpaceAddBody($space, cpBodyNew($mass, $moment));
    cpBodySetPosition($ballBody, cpv(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.
    my $ballShape = cpSpaceAddShape($space, cpCircleShapeNew($ballBody, $radius, $CPV_ZERO));
    cpShapeSetFriction($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.
    my $timeStep = 1.0/60.0;
    my $last_y = 0;

    # For our tests, we want to check that there was some kind of movement.
    # Problem is, there might not be enough acceleration at the start to actually 
    # move anything.  We'll just do a few runs to prime the system.
    cpSpaceStep($space, $timeStep) for 1 .. 5;
    for(my $time = $timeStep * 5; $time < 2; $time += $timeStep){
        my $pos = cpBodyGetPosition($ballBody);
        my $vel = cpBodyGetVelocity($ballBody);
        $last_y = $pos->y;

        cpSpaceStep($space, $timeStep);
    }

    # Clean up our objects and exit!
    cpShapeFree($ballShape);
    cpBodyFree($ballBody);
    cpShapeFree($ground);
    cpSpaceFree($space);

DESCRIPTION

Chipmunk 2D is a physics library that supports fast, lightweight rigid body physics for games or other simulations.

This Perl module is a pretty straight implementation of the C library, so the Chipmunk API docs should give you most of what you need. The complete API is exported when you use the module.

A few cavets:

  • The cpvzero global is accessible as $CPV_ZERO

  • Callback functions in the cpSpatialIndex header are not implemented

Callbacks elsewhere in the library can all take Perl functions. For example:

    cpBodySetVelocityUpdateFunc( $body, sub {
        my ($body, $gravity, $damping, $dt) = @_;
        cpBodyUpdateVelocity( $body, $gravity, 0, $dt );
        return;
    });

TODO

Write the callback function mappings inside cpSpatialIndex

Convert to Dist::Zilla

SEE ALSO

Chipmunk 2D Website: http://chipmunk-physics.net

Alien::Chipmunk

AUTHOR

Timm Murray <tmurray@wumpus-cave.net>

LICENSE

Copyright (c) 2016, Timm Murray All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice, this list of 
      conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice, this list of 
      conditions and the following disclaimer in the documentation and/or other materials 
      provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.