PhysicsFS/PhysFS++ Tutorial

This is a follow-up from a promise that I made in my tutorial video on designing an asset manager using SFML. That video can be found here.

This tutorial is centred around PhysFS++, a C++ wrapper for PhysicsFS. For the sake of the tutorial, it’s assumed that the reader is familiar with PhysicsFS and what it’s capable of. Described here is a workflow for simple use of the library. Anything more discrete is beyond the scope and will have to be ascertained by the reader on their own accord.

Lastly of note, PhysFS++ encapsulates PhysicsFS calls in a PhysFS namespace. The functions are global within this namespace and there are only a few classes that are provided. PhysFS++ further encapsulates key PhysicsFS constructs, notably those corresponding to archived files, into said classes that are derivatives of STL stream classes (a huge boon).

Like some other libraries, PhysicsFS requires explicit initialisation before it can be used. This is facilitated by a function named init. It takes one argument of type const char* and is semantically directed at a terminal invocation argument triaged through the much loved argv. However, this can be an empty string especially if you’re not expecting to handle terminal invocations. Thus, a very general call to init can be performed as such:

PhysFS::init (nullptr);

Right of the bat we have to mention a caveat here. From PhysFS++, there’s no way to assert the initialisation process of PhysicsFS. This is counter-intuitive to the upstream library which relies on the tried-and-true zero on failure, non-zero on success return values as sanity checks. Furthermore, while PhysFS++ implements C++ exceptions, the init function doesn’t throw any at all. Ostensibly, what one is left with is an unchecked call to init. Because one needs to compile PhysFS++ from the source, it is possible to modify the code, as I have done, to add a check to this call.

Once init has successfully completed, the next step is to mount an archive file into the virtual filesystem created by init. This is performed with the mount function. mount expects three arguments: the archive file on disk, a string specifying a mount point in the virtual filesystem, and a boolean which appends the mount point to the search path. One should place the archive file in the working directory for the binary file of their executable so PhysFS++ can see it. The second argument can be an empty string which would force root mounting, and the third can be true. Thus, for our example, if we assume we have an archive file named funphotos.zip on our disk in the binary’s working directory, we can issue a call to mount as such:

PhysFS::mount (“funphotos.zip”, “”, 1);

Unfortunately, as was the case with init, mount wraps an upstream function that adheres to the zero-or-nonzero return value paradigm that is outright dropped by PhysFS++ with no exception catering otherwise. Thus, if mount fails to mount the archive for whatever reason, it’ll be a little difficult to ascertain why; plan accordingly.

Assuming mount has returned properly, one can start to work with the files that are contained in the archive. At this point, you should begin working in the mentality of filesystem calls. It’s possible to have archive files with complex directory layouts which would require one to perform recursive searches. That being said, everything should be considered a file – even a directory. An analysis of the PhysicsFS and PhysFS++ APIs will provide for you the full breadth of your available capabilities so for the sake of brevity, only a select number of those will be touched here.

Enumeration of files in a directory can be performed with the enumerateFiles function. It takes as an argument a string which indicates the directory to use as a root for the enumeration. As a return it provides the caller with a vector of strings indicating the name of the file. For ease of use, a call to this to enumerate the files in root can be performed as such:

auto rootfiles = PhysFs::enumerateFiles (“/”);

To actually work with a file in the filesystem, one needs to use the PHYSFS_file ADT. This upstream ADT is encapsulated by one of three classes: PhysFS::ifstream, PhysFS::ostream, or PhysFS::fstream. Each of these is fantastic in that they encapsulate a PHYSFS_file ADT in a standard stream which means that one can now perform established stream operations on the file itself. Each class has its own use: fstream for reading files, ostream for writing to files, and ifstream for bidirectional file handling. In any case, any of these classes can be instantiated with a string argument that contains a fully qualified pathname to a file in the virtual filesystem that one wants to work with. For example, given that our virtual filesystem has a file named goofycats.png located at the path /textures/cats, we could instantiate a read file as such:

PhysFS::fstream gc (“/textures/cats/goofycats.png”);

Again, the underlying upstream call to open the file goes unchecked.

What you do from here is largely subjective relative to your program’s context. Say, for example (and this is actually pretty specific to my own use case), that you have a series of files of various formats in an archive that are being used in a video game program. The multimedia library you’re using should have ADTs that represent types of assets such as textures, fonts, etc. One could do some work to transpose the raw data of these streams into the aforementioned ADTs for use in the multimedia library. The following snippet of code, borrowed from one of my own projects, illustrates this. A PhysFS::fstream instance named f is created with a certain file. Following up is a char array named d is instantiated with the size of f. The read function of f is called to transpose the bytes from f into d. Then, d is used to instantiate an instance of sf::Music from SFML contained in a std::unordered_map:

code

This covers most the basic and general needs of users of PhysicsFS. Should you require anything else from it, you’d do well to read up on the Doxygen file of PhysicsFS or the source for PhysFS++. Lastly, when one is done with the library, you’ll need to call a deinitialization function called deinit:

PhysFS::deinit ();

Clicky Game – Development Journal 0001

Because I have no life, and because I really suck at having good ideas, the concept of Clicky Game was born.

Now ordinarily I wouldn’t bat two shits at this thing after having written something like that, but I wanted to use this as an opportunity to really dig deep back into C++ and use some of the features in C++11. I just want an excuse to use lambdas liberally. 🙂

I’m doing a few interesting things with this project. First of all, I’m writing it in Visual Studio. Yes, I know, blasphemy. The reason for this though is because my new job throws me into a DevOps-type position where I’m going to have to be writing code for integration into an ERP Package we use. Unfortunately they only provide an API in C# and since we’re a majority Microsoft Shop, I need a MSVS Primer. This would be it.

Sticking with the badassery that is MSVS, I’m trying out Team Foundation Server for VCS. This is drastically different from my traditional use of Git. So far, I hate it. It’s OVERKILL for a single dev such that it’s almost not quite suitable for a single dev. But we’re going to stick with it.

So far, I’ve had two solid days of coding (about 12 hours a day) and I’ve gotten into this interesting area where I’m very heavily extending the SFML Framework that I’m using for the major library. It’s actually a really good library. It’s just missing a lot of things that I need. For example, there is no native construct for handling 2D animation. I find this to be a little odd since it’s primarily a 2D library. But that’s sort of cool since it lets your roll your own implementation. It also doesn’t have any native constructs for UI. This leaves me in a bit of a predicament since there’s no real solid UI library that integrates with SFML (guichan is strictly for SDL/Allegro) so now my current task has been to create a bit of a library that does this.

Doing all of this seemingly extra work is actually pretty cool since I’m able to use modern coding features like named lambdas for event handling (by use of std::function wrapper for class member). As another challenge, all allocations are dynamic keeping as little overhead on the stack as possible. So far, this seems to have a tremendous performance benefit but, as you could imagine, it’s requiring A LOT of double checking for things like new/delete pairing, reference/dereference members for appropriate address/value access syntax, test assertions on members prior to use in expressions even in places where it may be safe to assume that the memory should be successfully allocated and the respective member instantiated, thread safety, cross-member asset access, etc… A lot of really interesting technical hurdles.

I think I’m going to do a little bit of a piece on this for the next installment of “Something with Greg” which is shaping up to be the programmer episode.

Sometimes, Silence is Bronze

I have officially gone under a rock.

Most of it was my fault. I gambled (in an ethereal sense), I lost (more than just money mind you) and now I’m paying for it. So-to-speak anyway.

So the things that I have been working on – LinuxInstall and WIPN for example, have been without my presence for some time and may continue that way for just a bit longer.

That doesn’t mean I haven’t been busy and working on things in abstentia.

All I’m going to leave here is this single image.

The Oily Cow

Game Development – Migrating to Classical Mechanics

Let’s clear up some possible confusion regarding the title of this post. I’m not necessarily directly talking about game play mechanics as I am talking about the branch of physics called Classical Mechanics. You know, the fun stuff that helps us describe motion of mass under certain types of forces and the effects, both direct and indirect, resulting.

Well it’s fun for me anyway. Even though I hadn’t necessarily realized how much I’d forgotten about really simple stuff.

And let’s clear one more thing up here. I’m not a professional mathematician or physicist. I’m a software engineer. So if you’re looking for a primer on those areas, you’d be better served by Wikipedia/Wolfram, sites dedicated to those areas, or proper coursework. More importantly, my understanding of certain concepts might not be as robust as a skilled professional in either of those areas but I’m confident enough that I can describe what I see in everyday life enough with classical mechanics to be proficient in what’s called applied mechanics (that was actually my strongest point).

What I wanted to talk about here is something that I’m sure every game developer has dealt with at some point in time when designing a 2D game (strictly 2D). But to best describe what I’m getting at, I should probably start with an example.

Moving a block from one point to another is a relatively simple task to accomplish. Assuming that you’re not using an origin offset of some type, moving from point A to point B would look like this:

A simple affine transformation
A simple affine transformation

Geometrically speaking, this can be accomplished by a simple affine transformation. However, even though you could get away with expressing this event with an affine transformation, it’s not taking into account how this would happen in the real world. Even autonomous movement doesn’t occur without some type of external force being applied to the object to make it move in a certain direction. That being said, an affine transformation like this wouldn’t actually happen without some force being applied to the rectangle to make it move from vector A to vector B. Visually, the player may or may not be able to tell the difference between which method you chose to use. But we all know which one is more fun. 🙂

With that example, I wanted to point out that even in the most seemingly simple situations, it’s really easy to avoid the use of classical mechanics. But should you even if you could?

The really nice thing about classical mechanics is that the rules for movement, collision, and forces are all already laid bare before you. Even better is that these rules and observations are and have been made about real-world objects and these rules can be expressed mathematically (thus you’re translation point into software). At that point, it’s nothing more than to write a utility class or a series of methods that parameterize those expressions and make arbitrary calls to them in code as needed.

Ignoring classical mechanics means that you’re basically left to invent your own set of rules for these behaviors. Not only would that mean that things would probably not do what a player would expect them to do, but it makes a significant amount of work for a developer.

One particular point of difficulty for developers looking to migrate to using classical mechanics would be the change in understanding of objects in the game world. You can no longer look at your objects and entities as mere rectangles and circles with dimensions based in pixels. Now you have to start thinking about how these objects relate to real-world counterparts. Gravity now comes into play thus properties like mass, density, volume, etc.. are all now factors. It’s not enough to simply say “the user pressed this key so now I call this method to do a transformation to make the player move from here to here”. Now it’s more or less along the lines of “the user pressed this key so based on the current factors like gravity, applied friction of the area they’re standing on, if the wind is blowing or not and how fast, how fast can they move in the direction requested and move them accordingly”.

It all comes with the territory transition though.

A really simple but fun exercise for this transition would be to try and write a Pong clone implementing as much of classical mechanics as possible. It’d be fun to discuss this so I think I might try to do so soon.