- Notifications
You must be signed in to change notification settings - Fork10
A lightweight 2D physics engine written in C, for educational purposes.
License
jdeokkim/ferox
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
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 asBox2D andChipmunk2D.
- 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 byraylib
- GCC version 6.4.0+
- Git version 2.14.0+
- GNU Make version 4.1+ (or BSD Make 20181221+)
Make sure you have installedraylib 4.5.0+ to build all examples.
Compiling for Windows
Download the latest release of MSYS2 fromhere 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 themingw-w64-x86_64-raylib package:
$pacman -S mingw-w64-x86_64-raylib$cd examples
You will also need to configure theRAYLIB_INCLUDE_PATH andRAYLIB_LIBRARY_PATH variables inMakefile.mingw:
$ vim Makefile.mingw# TODO: Edit these values to match your raylib installation path!RAYLIB_INCLUDE_PATH ?= /mingw64/include RAYLIB_LIBRARY_PATH ?= /mingw64/libFinally, in order to compile the examples, do:
$ make -f Makefile.mingwDownload the latest release of this library fromhere and extract the.zip file to your working directory. Then, startWindows PowerShell and type the following command to start theDeveloper 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\feroxMode LastWriteTime Length Name---- ------------- ------ ----d----- 2023-09-13 오후 9:15 .githubd----- 2023-09-13 오후 9:15 docsd----- 2023-09-13 오후 9:15 examplesd----- 2023-09-13 오후 9:15 included----- 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 feroxPS C:\Users\jdeokkim\source\repos\ferox> nmake -f NMakefile
Download the latest release of w64devkit fromhere, runw64devkit-x64-2.0.0.exe and wait for the archive to be extracted to your working directory, and runw64devkit/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.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 ./*.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
$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$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$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&& makeCompiling for *BSD (FreeBSD)
$sudo pkg install git$git clone https://github.com/jdeokkim/ferox&&cd ferox$make
Then you can install raylib by downloading theraylib package:
$ sudo pkg install raylibFinally, 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
$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 (LLVM-to-WebAssembly)
Compiling for the Web requires installation of theEmscripten 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.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 -f Makefile.emcc RAYLIB_PATH=../../raylib$emrun --no_browser ./bin/basic.html
Cross-compiling from GNU/Linux to Windows (WSL2)
$sudo apt install build-essential git mingw-w64$git clone https://github.com/jdeokkim/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
- C. Hecker, “Behind the Screen: Physics, Part 1,” Game Developer Magazine, 1996.
- C. Hecker, “Behind the Screen: Physics, Part 2,” Game Developer Magazine, 1997.
- E. Catto, “How Do Physics Engines Work?” USC GamePipe Laboratory, Jan. 2019.
- R. Gaul, “How to Create a Custom Physics Engine,” Envato Tuts+, Apr. 2013.
- E. Coumans, “Collision Detection – Contact Generation and GPU Acceleration,” ACM SIGGRAPH ASIA 2010, Jul. 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, Jul. 2005.
- G. van den Bergen, “Physics for Game Programmers: Spatial Data Structures.” Game Developers Conference 2013, Mar. 2013.
- M. Bostock, “Sutherland–Hodgman Clipping,” observablehq.com, Aug. 2020.
- S. Boyd, “Convex Optimization,” Cambridge University Press, Mar. 2004, pp. 46–51.
- T. MacDonald, “Spatial Hashing.” GameDev.net, Oct. 2009.
- W. Bittle, “Contact Points Using Clipping,” dyn4j.org, Nov. 2011.
- W. Bittle, “SAT (Separating Axis Theorem),” dyn4j.org, Jan. 2010.
- E. Catto, “Fast and Simple Physics Using Sequential Impulses,” San Jose, CA. Mar. 2006.
- E. Catto, “Iterative Dynamics with Temporal Coherence,” Crystal Dynamics, Menlo Park, CA, Jun. 2005.
- E. Catto, “Solver2D,” box2d.org, Feb. 2024.
- R. Tonge, “Iterative Rigid Body Solvers,” Game Developers Conference 2013, Mar. 2013.
- M. Chou, “Game Physics: Resolution – Contact Constraints,” allenchou.net, Dec. 2013.
- O. Strunk, “Stop my Constraints from Blowing Up!” Game Developers Conference 2013, Mar. 2013.
- A. Witkin, and D. Baraff, “An Introduction to Physically Based Modeling: Differential Equation Basics,” ACM SIGGRAPH 1995, Aug. 1995.
- E. Catto, “Numerical Methods,” San Jose, CA, Mar. 2015.
- G. Fiendler, “Integration Basics,” Gaffer on Games, Jun. 2004.
- G. Rees, “How do you detect where two line segments intersect?” stackoverflow.com, Feb. 2009.
- Scratchapixel, “A Minimal Ray-Tracer: Rendering Simple Shapes (Sphere, Cube, Disk, Plane, etc.),” scratchapixel.com, Nov. 2022.
- J. Allan, “An Extensive Benchmark of C and C++ Hash Tables,” jacksonallan.github.io, May. 2024.
- S. Anderson, “Bit Twiddling Hacks,” graphics.stanford.edu, 1997.
MIT License
Copyright (c) 2021-2025 Jaedeok Kim (jdeokkim@protonmail.com)
Permission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, 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 THESOFTWARE.
About
A lightweight 2D physics engine written in C, for educational purposes.