PhysicsFS
October 22nd, 2012: 2.0.3 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 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.
- PhysFS++ is a third-party C++ wrapper around the PhysicsFS API.
- Probably other software uses PhysicsFS. If you know of one,
drop me a line.
Operating Systems and distros known to provide PhysicsFS:
What works:
- Support for .ZIP files (PkZip/Info-ZIP/WinZip compatible).
- version 1.1+: support for .7z files (7zip/lzma).
- 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 Mac OS X (x86, PPC, and x86-64 tested; gcc and clang).
- Compiles/runs on iOS (iPhone, iPad tested; xcode).
- Compiles/runs on BeOS, YellowTab, Zeta, and Haiku (x86 tested; gcc).
- 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 OS/2 Warp (x86 tested; EMX).
- up to version 2.0: Compiles/runs on Microsoft PocketPC.
- Third parties have reported easily porting PhysicsFS to PlayStation 2, PlayStation 3, and Xbox360.
- 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.
License:
PhysicsFS is licensed under the
zlib license.
Documentation:
-
A Doxygen-generated API reference
can be found here (or
here for the development branch). You can generate your own
HTML, manpage, LaTeX, RTF, etc documents with this program; download
the PhysicsFS source and use the included Doxyfile.
-
Some kind folks put together a brief
PhysicsFS tutorial.
Downloads:
Prepackaged source code:
- Here is the download directory. You can
find official source code releases here. ".tar.gz" files are like
ZIP files, and can be unarchived by WinZip and Stuffit Expander.
- 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
Mercurial website
for more information on using hg, where you can also download
software for Mac OS X, 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-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/
Mailing list:
There is a mailing list for PhysicsFS available. To subscribe or
view archives, go
here.
To send mail to the list, subscribe, then write to
physfs@icculus.org.
Page maintained by
Ryan C. Gordon.