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:

...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:

Operating Systems and distros known to provide PhysicsFS:

What works:


What doesn't work:


License:

PhysicsFS is licensed under the zlib license.


Documentation:


Downloads:

Prepackaged source code:

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 http://hg.icculus.org/icculus/physfs/

...or, for the stable (non-development) branch:

hg clone -r stable-2.0 http://hg.icculus.org/icculus/physfs/

...or, for the obsolete stable 1.0 branch:

hg clone -r stable-1.0 http://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.