March 18th, 2019: 3.0.2 released!
(PhysicsFS development is funded by my Patreon! If you like me working
on things like PhysicsFS and other useful pieces of code, consider
throwing some money in the pot:
Become a Patron!
PhysicsFS is a library to provide abstract access to various archives.
It is intended for use in video games, and the design was somewhat
inspired by Quake 3's file subsystem. The programmer defines a "write
directory" on the physical filesystem. No file writing done through the
PhysicsFS API can leave that write directory, for security. For example,
an embedded scripting language cannot write outside of this path if it
uses PhysFS for all of its I/O, which means that untrusted scripts can
run more safely. Symbolic links can be disabled as well, for added
safety. For file reading, the programmer lists directories and archives
that form a "search path". Once the search path is defined, it becomes
a single, transparent hierarchical filesystem. This makes for easy
access to ZIP files in the same way as you access a file directly on
the disk, and it makes it easy to ship a new archive that will override
a previous archive on a per-file basis. Finally, PhysicsFS gives you
platform-abstracted means to determine if CD-ROMs are available, the
user's home directory, where in the real filesystem your program is
To explain better, you have two zipfiles, one has these files:
...the other's got these:
...and, finally, in your game's real directory:
When you create the search path in PhysicsFS with those three
components, and ask for what's in the "music" directory, you are told:
...in the maps directory:
...in the graphics directory:
...and, finally, in the root (toplevel) directory:
The programmer does not know and does not care where each of these
files came from, and what sort of archive (if any) is storing them.
But if he needs to know, he can find out through the PhysicsFS API.
Furthermore, he can take comfort in knowing that those untrusted
scripts we mentioned earlier can't access any other files than these.
The file entries "." and ".." are explicitly forbidden in PhysicsFS.
Places PhysicsFS can be found in use:
- The Build Engine can optionally be compiled with PhysicsFS support, which is good, because its standard packfile format offers no compression or long filenames.
- ParaGUI is a cross platform toolkit built on Simple Directmedia Layer. That library has, among other useful stuff, a C++ wrapper for PhysicsFS. Here is an API reference for their interface to PhysicsFS.
- SDL_sound comes with a technology demonstration program, playsound, that is a generalized sound file playback program. playsound can use PhysicsFS to stream audio out of archive files on-the-fly.
- Falling Block Game is a Tetris-style game that uses PhysicsFS under the hood.
- Excido is a 3D arcade game using PhysicsFS.
- Tales of Middle Earth is an Angband-based RPG that uses PhysicsFS.
- Dead Meat is a Bomberman clone with PhysicsFS support.
- netPanzer, a multiplayer tactical warfare game, utilizes PhysicsFS.
- Z-Raid is a River Raid clone using PhysicsFS on PocketPC devices!
- Final Frontier Trader is a 2D single player space strategy, combat, and trading game powered by PhysicsFS.
- Yac3De is a 3D engine that is using PhysicsFS to access Doom3 pakfiles in order to load their maps.
- The maya2q3 plugin uses PhysicsFS to load shader resources from Quake 3 packages.
- MindBender uses PhysicsFS for resource management.
- Lincity-NG is a highly-polished SimCity clone that makes use of PhysicsFS.
- Project Xenocide uses PhysicsFS for their data management.
- Warzone 2100 makes use of PhysicsFS so modders can use standard .zip processing utilities.
- SuperTux is a side-scroller using PhysicsFS.
- The Mana World makes use of PhysicsFS.
- LÖVE uses PhysicsFS behind the scenes.
- Daimonin is an MMORPG that uses PhysicsFS.
- Puzzle Quest for the iPhone appears to use PhysicsFS.
- Seventh Sense is using PhysicsFS for playing Lone Wolf adventure books on a computer.
- The Legend of Mazzeroth, a 2D isometric RPG, uses PhysicsFS.
- Allegro 5.0 provides a PhysicsFS addon.
- Shank, Klei Entertainment's side-scrolling beat-em-up, uses PhysicsFS, ported to various game consoles.
- Dungeons of Dredmor dropped PhysicsFS into the game at a moment's notice, enabling modders to go crazy.
- Polycode is an open source, cross-platform framework that uses PhysicsFS for file management.
- Battle Brothers is a strategy/RPG hybrid that uses PhysicsFS.
- Cogmind is a roguelike with a unique aesthetic that uses PhysicsFS.
- PhysFS++ is a third-party C++ wrapper around the PhysicsFS API.
- Quetoo, a heavily-modified Quake 2 engine, uses PhysicsFS.
- hyper3DGE, a 3D-Accelerated open-source DOOM engine, uses PhysicsFS.
- Probably other software uses PhysicsFS. If you know of one,
drop me a line.
Operating Systems and distros known to provide PhysicsFS:
- Support for .ZIP files (PkZip/Info-ZIP/WinZip compatible).
- version 1.1+: support for .7z files (7zip/lzma).
- version 3.0+: support for .iso files (CD-ROM image files).
- version 3.0+: support for .vdf files (Gothic/Gothic II).
- version 3.0+: support for .slb files (Independence War).
- Support for the Build Engine's GRP format.
- Support for Quake 1 and Quake 2's PAK file format.
- Support for Descent 1 and Descent 2's HOG file format.
- Support for Descent 1 and Descent 2's MVL file format.
- Support for Doom WAD files.
- Support for access to the native filesystem.
- version 1.1+: Fully supports Unicode filenames.
- Compiles/runs on GNU/Linux (x86, PPC, MIPS, Sparc, Alpha, Itanium, and x86-64 tested; gcc).
- Compiles/runs on Windows XP and later (x86 and x64 tested; Visual Studio, Cygwin, and MinGW).
- Compiles/runs on WinRT, UWP, Windows Phone, Windows Store: (x86-64 and ARM tested; Visual Studio).
- Compiles/runs on macOS (x86, PPC, and x86-64 tested; gcc and clang).
- Compiles/runs on iOS (iPhone, iPad tested; xcode).
- Compiles/runs on OS/2, eComStation, ArcaOS (x86 tested; EMX and OpenWatcom).
- Compiles/runs on Haiku (x86 tested; gcc2 and gcc4)
- Compiles/runs on QNX 7 (x86, x86-64 and ARM tested).
- Compiles/runs on Android.
- Compiles/runs on the Nintendo Switch! (Contact Ryan for source code).
- Compiles/runs on Emscripten.
- Compiles/runs on generic Unix, like FreeBSD, OpenBSD, Solaris, etc (x86 and Alpha tested; gcc).
- up to version 1.0: Compiles/runs on MacOS 8/9 (PPC tested; CodeWarrior 6).
- up to version 2.0: Compiles/runs on Windows 95 and later (x86 and x64 tested; Visual Studio, Cygwin, and MinGW).
- up to version 2.0: Compiles/runs on Microsoft PocketPC.
- up to version 2.0: Compiles/runs on BeOS, YellowTab, Zeta, and Haiku (x86 tested; gcc).
- Third parties have reported easily porting PhysicsFS to PlayStation 2, PlayStation 3, and Xbox360 (Contact Ryan about lending him a devkit!).
- May compile and run elsewhere with little to no modification. Success stories and patches are welcome.
What doesn't work:
- Other stuff in the docs/TODO.txt file.
- Contributions of other ports are, of course, welcome.
PhysicsFS is licensed under the
A Doxygen-generated API reference
can be found here. You can generate your own
HTML, manpage, LaTeX, RTF, etc documents with this program; download
the PhysicsFS source and build with "make docs".
Some kind folks put together a brief
Prepackaged source code:
- Here is the download directory. You can
find official source code releases here. ".tar.bz2" files are like
ZIP files, and can be unarchived by WinZip and most other things.
- Here is a real-time listing of changes between versions.
- We no longer do binary packages for several reasons. Please
build from source.
Downloading with Mercurial:
PhysicsFS's source code may be downloaded using
Mercurial (aka: "hg"). Hg
allows you to get up-to-the-minute fixes and enhancements; as a developer
works on a source tree, you can use hg to mirror that source tree
instead of waiting for an official release. Please look at the
for more information on using hg, where you can also download
software for macOS, Windows, and Unix systems.
PhysicsFS is no longer hosted in a CVS or Subversion repository. You
have to use hg or wait for an official release.
Here is the web interface to PhysicsFS's Mercurial repository.
To download PhysicsFS via Mercurial:
hg clone https://hg.icculus.org/icculus/physfs/
...or, for the stable (non-development) branch:
hg clone -r stable-3.0 https://hg.icculus.org/icculus/physfs/
...or, for the obsolete stable 2.0 branch:
hg clone -r stable-2.0 https://hg.icculus.org/icculus/physfs/
...or, for the obsolete stable 1.0 branch:
hg clone -r stable-1.0 https://hg.icculus.org/icculus/physfs/
There is a mailing list for PhysicsFS available. To subscribe or
view archives, go
To send mail to the list, subscribe, then write to
Page maintained by
Ryan C. Gordon.