PhysicsFS
March 18th, 2019: 3.0.2 released!
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
running, etc.
To explain better, you have two zipfiles, one has these files:
- music/intro.mid
- graphics/splashscreen.bmp
- mainconfig.cfg
...the other's got these:
- music/hero.mid
- maps/desert.map
...and, finally, in your game's real directory:
- maps/city.map
- graphics/gun.bmp
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:
- maps
- music
- graphics
- mainconfig.cfg
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 they need to know, they can find out through the PhysicsFS API.
Furthermore, they 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.
PhysicsFS is written in portable C, runs on dozens of platforms, and is
easy to add to your project by just adding a handful of C files and one
header directly to your build process.
What works:
- 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 and Xbox consoles (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:
License:
Documentation:
-
An API reference for PhysicsFS can be found here.
Downloads:
- Source code is available from the GitHub page.
- We no longer publish binary packages ourselves. Please build from source.
- Linux users: there's a good chance your distro already provides a PhysicsFS package! Check with your package manager.
Funding:
- Like PhysicsFS? Contribute to my Patreon! Become a Patron!
- Or sponsor me on GitHub:
Page maintained by
Ryan C. Gordon.