Main Page

Introduction

libsatcr is a collision detection and response library using the Separating Axis Theorem. More specifically, it is a port of SAT.JS to C (with extra features, of course).

Main features:

• Free and open-source (licensed under the Simplified BSD License)
• Written in C
• Very small (library compiles to 48K with symbols and no optimizations)
• Simple to use/integrate
• Supports circles and convex polygons

Known limitations:

• Only works in 2D (3D support might be added in a later release)
• Concave polygons are not supported (the SAT algorithm does not support this)

Installing

First, make sure these libraries/applications are installed:

• libc (might be named glibc on some systems)
• git
• cmake

Next, clone the source:

git clone https://github.com/MiJyn/libsatcr.git

Compile it:

cd libsatcr
cmake .
make

Then install (you might have to prepend sudo):

make install

Basics

I personally always like examples to guide me through a library, so here is a basic "hello world" program:

// main.c - Tests two circles for collision, and un-collides them

#include <satcr.h>
#include <stdio.h>

int main() {
    sat_shape first_circle = sat_circle_new(sat_vector_new(0, 0), 10);
    sat_shape second_circle = sat_circle_new(sat_vector_new(4, 4), 10);
    sat_collision collision = sat_collision_detect(&first_circle, &second_circle);
    if (collision.collided) {
        printf("Overlap vector: %f %f\n", collision.overlap.x, collision.overlap.y);
        sat_vector_sub(&first_circle.pos, collision.overlap); // Un-collide the circles
    } else {
        // This should never happen!
    }
    sat_shape_destroy(&first_circle);
    sat_shape_destroy(&second_circle);
    sat_collision_destroy(&collision);
    return 0;
}

To compile, use:

cc -static -l satcr main.c -o main

As you can see, libsatcr is only (officially) distributed statically, because not only is it very small, but the API changes a lot from version to version. Backwards compatability between versions is not a huge priority for me, because you can't overload functions in C (therefore making new versions harder to use).

Anyways, going on to the code, as you can see, it creates two circles, the first at (0, 0), and the second at (4, 4), both with a radius of 10:

//                       New circle    New vector  Position  Radius
//                           ↓              ↓           ↓      ↓
sat_shape first_circle = sat_circle_new(sat_vector_new(0, 0), 10);
sat_shape second_circle = sat_circle_new(sat_vector_new(4, 4), 10);

Then it checks for a collision between both objects (referencing is only for not duplicating memory, it doesn't modify the objects themselves). Though it can be easy to think that sat_collision_detect does the actual collision detection/response (CR) calculations, all it actually does is that it finds the shape type of both shapes passed, and it calls the correct function from that.

If you know exactly what both objects are, you might want to consider calling the correct CR test directly. For example, in our case, we could replace sat_collision_detect by sat_collision_test_circle_circle, like this:

sat_collision collision = sat_collision_test_circle_circle(&first_circle, &second_circle);

Going on, as you can see, the CR tests return a collision object (sat_collision). Usually, you would only need to use the sat_collision::collided parameter, and if you are using it for response, then you would also use the sat_collision::overlap vector. In the example, we un-collided both circles by subtracting the first circle's position by the overlap vector:

//  Subtract        Position    by    Overlap
sat_vector_sub(&first_circle.pos, collision.overlap);

Lastly, we destroyed each object so that any memory allocated by libsatcr would be freed.

sat_shape_destroy(&first_circle);
sat_shape_destroy(&second_circle);
sat_collision_destroy(&collision);

Licensing

libsatcr is released under the Simplified BSD License, as follows:

Copyright (c) 2012, Joel Leclerc
All rights reserved.

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

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer. 
2. 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 OWNER 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.

The views and conclusions contained in the software and documentation are those
of the authors and should not be interpreted as representing official policies, 
either expressed or implied, of libsatcr.

SAT.js (the original library, to which libsatcr ported to C) is released under the MIT license, as follows:

Copyright (C) 2012 by Jim Riecken

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.

I am sorry for any formatting issues with the licenses, I did my best :)

Credits

Author and maintainer: Joel Leclerc (MiJyn) <lkjoe.nosp@m.l@ub.nosp@m.untu..nosp@m.com>

Original library (SAT.JS) by Jim Riecken (jriecken)