Ferox
A lightweight 2D physics engine written in C, for educational purposes.
Install / Use
/learn @jdeokkim/FeroxREADME
<img src="docs/static/images/readme-logo.png" alt="jdeokkim/ferox"><br>
A lightweight 2D physics engine written in C, for educational purposes.
Documentation — Examples — Prerequisites
</div>Features
<div align="center"> <video src="https://github.com/user-attachments/assets/b8a8da2e-283b-4208-820b-914429b51e08" /> </div>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
Prerequisites
- GCC version 6.4.0+
- Git version 2.14.0+
- GNU Make version 4.1+ (or BSD Make 20181221+)
Optional
Make sure you have installed raylib 4.5.0+ to build all examples.
Building
<details> <summary>Compiling for Windows</summary>MSYS2 (MinGW-w64)
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/jdeokkim/ferox && cd ferox
$ make
Then you can install raylib by downloading the mingw-w64-x86_64-raylib package:
$ pacman -S mingw-w64-x86_64-raylib
$ cd examples
You 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
Visual Studio 2022
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.md
In order to build this library, do:
PS C:\Users\jdeokkim\source\repos> cd ferox
PS C:\Users\jdeokkim\source\repos\ferox> nmake -f NMakefile
w64devkit
Download 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/jdeokkim/ferox/archive/refs/heads/main.zip && unzip main.zip
$ mv ferox-main ferox && cd ferox
In order to build this library, do:
$ make -f Makefile.mingw
You 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 ./*.zip
Finally, in order to compile the examples, do:
$ cd ~/workspace/ferox/examples
$ make -f Makefile.mingw \
RAYLIB_INCLUDE_PATH=../../raylib/src RAYLIB_LIBRARY_PATH=../../raylib/src
Arch Linux / Manjaro Linux
$ sudo pacman -Syu && sudo pacman -S base-devel git
$ git clone https://github.com/jdeokkim/ferox ~/ferox && cd ~/ferox
$ make
In 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
Debian / Ubuntu
$ sudo apt install build-essential git
$ git clone https://github.com/jdeokkim/ferox ~/ferox && cd ~/ferox
$ make
In 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
Void Linux
$ sudo xbps-install base-devel git
$ git clone https://github.com/jdeokkim/ferox ~/ferox && cd ~/ferox
$ make
In 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 && make
FreeBSD
$ sudo pkg install git
$ git clone https://github.com/jdeokkim/ferox && cd ferox
$ make
Then 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/lib
Raspberry Pi OS (Raspbian)
$ sudo apt install build-essential git
$ git clone https://github.com/jdeokkim/ferox && cd ferox
$ make
You 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_DRM
Finally, in order to compile the examples, do:
$ cd examples
$ make -f Makefile.drm
Compiling for the Web requires installation of the Emscripten SDK.
Debian / Ubuntu
$ 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.sh
After setting up the environment variables for Emscripten SDK, do:
$ git clone https://github.com/jdeokkim/ferox && cd ferox
$ make -f Makefile.emcc
You 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 -B
Finally, in order to compile the examples, do:
$ cd examples
$ make -
