A lightweight 2D physics engine written in C, for educational purposes.
raylib-44.1.mp4
NOTE: This project was made for educational purposes (mainly for me to learn how a physics engine works), and therefore it is not recommended to use this library in production. Consider using other 2D physics engines with better performance such as Box2D and Chipmunk2D.
- Broad-phase collision detection with spatial hashing algorithm
- Narrow-phase collision detection with SAT (Separating Axis Theorem)
- Numerical integration with semi-implicit Euler method
- Projected Gauss-Seidel iterative constraint solver
- Persistent contacts (contact cache) with warm starting
- Point-in-Convex-Hull, proximity and raycast queries
- Support for basic collision event callbacks
- WebAssembly examples powered by raylib
- GCC version 6.4.0+
- Git version 2.14.0+
- GNU Make version 4.1+ (or BSD Make 20181221+)
Make sure you have installed raylib 4.5.0+ to build all examples.
Compiling for Windows
Download the latest release of MSYS2 from here and follow the instructions on the homepage.
# MSYS2, UCRT 64-bit
$ pacman -Syu && pacman -S mingw-w64-ucrt-x86_64-gcc
$ git clone https://github.com/c-krit/ferox && cd ferox
$ makeThen you can install raylib by downloading the mingw-w64-x86_64-raylib package:
$ pacman -S mingw-w64-x86_64-raylib
$ cd examplesYou will also need to configure the RAYLIB_INCLUDE_PATH and RAYLIB_LIBRARY_PATH variables in Makefile.mingw:
$ vim Makefile.mingw
# TODO: Edit these values to match your raylib installation path!
RAYLIB_INCLUDE_PATH ?= /mingw64/include
RAYLIB_LIBRARY_PATH ?= /mingw64/lib
Finally, in order to compile the examples, do:
$ make -f Makefile.mingw
Download the latest release of this library from here and extract the .zip file to your working directory. Then, start Windows PowerShell and type the following command to start the Developer PowerShell:
PS C:\Users\jdeokkim> & 'C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Launch-VsDevShell.ps1' -Arch amd64
**********************************************************************
** Visual Studio 2022 Developer PowerShell v17.7.4
** Copyright (c) 2022 Microsoft Corporation
**********************************************************************
PS C:\Users\jdeokkim\source\repos> ls ferox
디렉터리: C:\Users\jdeokkim\source\repos\ferox
Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 2023-09-13 오후 9:15 .github
d----- 2023-09-13 오후 9:15 docs
d----- 2023-09-13 오후 9:15 examples
d----- 2023-09-13 오후 9:15 include
d----- 2023-09-13 오후 9:15 src
-a---- 2023-09-13 오후 9:15 2599 .clang-format
-a---- 2023-09-13 오후 9:15 1323 .gitignore
-a---- 2023-09-13 오후 9:15 629 CREDITS.md
-a---- 2023-09-13 오후 9:15 1099 LICENSE
-a---- 2023-09-13 오후 9:15 2388 Makefile
-a---- 2023-09-13 오후 9:15 1497 Makefile.emcc
-a---- 2023-09-13 오후 9:15 1499 Makefile.mingw
-a---- 2023-09-13 오후 9:15 2442 NMakefile
-a---- 2023-09-13 오후 9:15 12944 README.mdIn order to build this library, do:
PS C:\Users\jdeokkim\source\repos> cd ferox
PS C:\Users\jdeokkim\source\repos\ferox> nmake -f NMakefileDownload the latest release of w64devkit from here, run w64devkit-x64-2.0.0.exe and wait for the archive to be extracted to your working directory, and run w64devkit/w64devkit.exe.
$ mkdir ~/workspace && cd ~/workspace
$ wget https://github.com/c-krit/ferox/archive/refs/heads/main.zip && unzip main.zip
$ mv ferox-main ferox && cd feroxIn order to build this library, do:
$ make -f Makefile.mingwYou may need to compile raylib for Windows before compiling the examples:
$ cd .. && wget https://github.com/raysan5/raylib/archive/refs/tags/4.5.0.zip
$ unzip 4.5.0.zip && mv raylib-4.5.0 raylib
$ make -C raylib/src -j`nproc`
$ rm ./*.zipFinally, in order to compile the examples, do:
$ cd ~/workspace/ferox/examples
$ make -f Makefile.mingw \
RAYLIB_INCLUDE_PATH=../../raylib/src RAYLIB_LIBRARY_PATH=../../raylib/srcCompiling for GNU/Linux
$ sudo pacman -Syu && sudo pacman -S base-devel git
$ git clone https://github.com/c-krit/ferox ~/ferox && cd ~/ferox
$ makeIn order to compile the examples, do:
$ sudo pacman -Syu && sudo pacman -S alsa-lib mesa libx11 libxrandr \
libxi libxcursor libxinerama
$ git clone https://github.com/raysan5/raylib ~/raylib && cd ~/raylib/src
$ make PLATFORM=PLATFORM_DESKTOP GLFW_LINUX_ENABLE_WAYLAND=OFF && make install$ cd ~/ferox/examples && make$ sudo apt install build-essential git
$ git clone https://github.com/c-krit/ferox ~/ferox && cd ~/ferox
$ makeIn order to compile the examples, do:
$ sudo apt update && sudo apt install libasound2-dev libgl1-mesa-dev \
libglu1-mesa-dev libx11-dev libxrandr-dev libxi-dev libxcursor-dev \
libxinerama-dev libxkbcommon-dev
$ git clone https://github.com/raysan5/raylib ~/raylib && cd ~/raylib/src
$ make PLATFORM=PLATFORM_DESKTOP GLFW_LINUX_ENABLE_WAYLAND=OFF && make install$ cd ~/ferox/examples && make$ sudo xbps-install base-devel git
$ git clone https://github.com/c-krit/ferox ~/ferox && cd ~/ferox
$ makeIn order to compile the examples, do:
$ sudo xbps-install -Syu && sudo xbps-install alsa-lib-devel libglvnd-devel \
libX11-devel libXrandr-devel libXi-devel libXcursor-devel libXinerama-devel mesa
$ git clone https://github.com/raysan5/raylib ~/raylib && cd ~/raylib/src
$ make PLATFORM=PLATFORM_DESKTOP GLFW_LINUX_ENABLE_WAYLAND=OFF && make install$ cd ~/ferox/examples && makeCompiling for *BSD (FreeBSD)
$ sudo pkg install git
$ git clone https://github.com/c-krit/ferox && cd ferox
$ makeThen you can install raylib by downloading the raylib package:
$ sudo pkg install raylib
Finally, in order to compile the examples, do:
$ cd examples
$ make RAYLIB_INCLUDE_PATH=/usr/local/include RAYLIB_LIBRARY_PATH=/usr/local/libCompiling for Raspberry Pi
$ sudo apt install build-essential git
$ git clone https://github.com/c-krit/ferox && cd ferox
$ makeYou may need to recompile raylib for Raspberry Pi before compiling the examples:
$ sudo apt install libdrm-dev libegl1-mesa-dev libgles2-mesa-dev libgbm-dev
$ git clone https://github.com/raysan5/raylib && cd raylib/src
$ make -j`nproc` PLATFORM=PLATFORM_DRMFinally, in order to compile the examples, do:
$ cd examples
$ make -f Makefile.drmCompiling for the Web (LLVM-to-WebAssembly)
Compiling for the Web requires installation of the Emscripten SDK.
$ sudo apt install build-essential git
$ git clone https://github.com/emscripten-core/emsdk && cd emsdk
$ ./emsdk install latest
$ ./emsdk activate latest
$ source ./emsdk_env.shAfter setting up the environment variables for Emscripten SDK, do:
$ git clone https://github.com/c-krit/ferox && cd ferox
$ make -f Makefile.emccYou may need to recompile raylib for the Web before compiling the examples:
$ git clone https://github.com/raysan5/raylib && cd raylib/src
$ make -j`nproc` PLATFORM=PLATFORM_WEB -BFinally, in order to compile the examples, do:
$ cd examples
$ make -f Makefile.emcc RAYLIB_PATH=../../raylib
$ emrun --no_browser ./bin/basic.htmlCross-compiling from GNU/Linux to Windows (WSL2)
$ sudo apt install build-essential git mingw-w64
$ git clone https://github.com/c-krit/ferox && cd ferox
$ make -f Makefile.mingwYou may need to recompile raylib for Windows before compiling the examples:
$ git clone https://github.com/raysan5/raylib && cd raylib/src
$ make -j`nproc` CC=x86_64-w64-mingw32-gcc AR=x86_64-w64-mingw32-ar OS=Windows_NTLastly, in order to compile the examples, do:
$ cd examples
$ make -f Makefile.mingw RAYLIB_INCLUDE_PATH=../../raylib RAYLIB_LIBRARY_PATH=../../raylib- Catto, Erin. “How Do Physics Engines Work?” USC GamePipe Laboratory. January, 2019.
- Gaul, Randy. “How to Create a Custom Physics Engine.” Envato Tuts+. April–June, 2013.
- Hecker, Chris. “Behind the Screen: Physics, Parts 1-3.” Game Developer Magazine. 1996–1997.
- Bittle, William. “Contact Points Using Clipping.” dyn4j.org. November 17, 2011.
- Bittle, William. “SAT (Separating Axis Theorem).” dyn4j.org. January 01, 2010.
- Bostock, Mike. “Sutherland–Hodgman Clipping.” observablehq.com. August 02, 2020.
- Boyd, Stephen P. “Convex Optimization.”, 46–51. Cambridge University Press. March, 2004.
- Coumans, Erwin. “Collision Detection – Contact Generation and GPU Acceleration.” ACM SIGGRAPH ASIA 2010. July 26, 2010.
- E. J. Hastings, J. Mesit, and R. K. Guha. “Optimization of Large-Scale, Real-Time Simulations by Spatial Hashing. Proc. 2005 Summer Computer Simulation Conference, Cherry Hill, NJ, USA. July 24–28, 2005.
- MacDonald, Tristam. “Spatial Hashing.” GameDev.net. October 01, 2009.
- Teschner, Matthias, Bruno Heidelberger, Matthias Müller, Danat Pomeranets, and Markus Gross. n.d. “Optimized Spatial Hashing for Collision Detection of Deformable Objects.” Computer Graphics Laboratory, ETH Zurich. January 2005.
- Van den Bergen, Gino. “Physics for Game Programmers: Spatial Data Structures.” Game Developers Conference 2013. March, 2013.
- Catto, Erin. “Fast and Simple Physics Using Sequential Impulses.” San Jose, CA. March, 2006.
- Catto, Erin. “Iterative Dynamics with Temporal Coherence.” Crystal Dynamics, Menlo Park, CA. June, 2005.
- Catto, Erin. “Solver2D.” box2d.org. February 05, 2024.
- Chou, Ming-Lun. “Game Physics: Resolution – Contact Constraints.” allenchou.net. December 31, 2013.
- Chou, Ming-Lun. “Game Physics: Stability – Warm Starting.” allenchou.net. January 04, 2014.
- Strunk, Oliver. “Stop my Constraints from Blowing Up!” Game Developers Conference 2013. March, 2013.
- Tonge, Richard. “Iterative Rigid Body Solvers.” Game Developers Conference 2013. March, 2013.
- Catto, Erin. “Numerical Methods.” San Jose, CA. March, 2015.
- Fiedler, Glenn. “Integration Basics.” Gaffer on Games. June 01, 2004.
- Witkin, Andrew, and David Baraff. n.d. “An Introduction to Physically Based Modeling: Differential Equation Basics.” ACM SIGGRAPH 1995. August, 1995.
- Rees, Gareth. “How do you detect where two line segments intersect?” stackoverflow.com. February, 2009.
- Scratchapixel. “A Minimal Ray-Tracer: Rendering Simple Shapes (Sphere, Cube, Disk, Plane, etc.).” scratchapixel.com. November, 2022.
- Allan, Jackson. “An Extensive Benchmark of C and C++ Hash Tables.” jacksonallan.github.io. May 29, 2024.
- Anderson, Sean. “Bit Twiddling Hacks.” graphics.stanford.edu. 1997.
MIT License
Copyright (c) 2021-2024 Jaedeok Kim ([email protected])
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.