ferox

A lightweight 2D physics engine written in C, for educational purposes.

213
11
C

c-krit/ferox

Version Badge
Codefactor Badge
Code Size Badge
License Badge

A lightweight 2D physics engine written in C, for educational purposes.

Documentation
Examples
Prerequisites

Features

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

Compiling for Windows

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/c-krit/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/c-krit/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
Compiling for GNU/Linux

Arch Linux / Manjaro Linux

$ sudo pacman -Syu && sudo pacman -S base-devel git
$ git clone https://github.com/c-krit/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/c-krit/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/c-krit/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
Compiling for *BSD (FreeBSD)

FreeBSD

$ sudo pkg install git
$ git clone https://github.com/c-krit/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
Compiling for Raspberry Pi

Raspberry Pi OS (Raspbian)

$ sudo apt install build-essential git
$ git clone https://github.com/c-krit/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 (LLVM-to-WebAssembly)

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/c-krit/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 -f Makefile.emcc RAYLIB_PATH=../../raylib
$ emrun --no_browser ./bin/basic.html
Cross-compiling from GNU/Linux to Windows (WSL2)

Debian / Ubuntu

$ sudo apt install build-essential git mingw-w64
$ git clone https://github.com/c-krit/ferox && cd ferox
$ make -f Makefile.mingw

You 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_NT

Lastly, in order to compile the examples, do:

$ cd examples
$ make -f Makefile.mingw RAYLIB_INCLUDE_PATH=../../raylib RAYLIB_LIBRARY_PATH=../../raylib

References

Introduction

Collision Detection

Constraint Solver

Numerical Methods

Raycast Queries

Miscellaneous

License

MIT License

Copyright © 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.