I'm Marc, the programmer here at DROOL. This is the first in a series of technical posts where I'll go "under the hood" of our game engine and THUMPER. These will be aimed at game programmers -- non-technical DROOLers might need a quick toke before reading further. We've recently started using URL "links" to our game objects that we can easily share via e-mail. It's simple and probably not a unique solution. But it's been useful and feels like a feature every engine should have. It was quick and easy to implement, but the most time was spent working around some minor annoyances.

Our need for "Object URLs"

Brian (the DROOL artist) lives in Providence, Rhode Island, and I live in Seoul, South Korea. Because of the distance (and 14 hour time difference), our opportunities for liquid communication via voice and video chat are limited and we often resort to e-mailing each other about development issues.

Like most game engines, our assets are divided into files, each containing multiple objects (meshes, animations, sounds, etc.). For our first game, THUMPER, we've accumulated hundreds of files and thousands of objects. During development, there could be an issue with any one of those files or objects. For example, Brian might have a rendering problem and send me an e-mail like this:

SUP FLURY. There is a rendering problem with bug_eyed.mesh in gameplay/resource/bugs.objlib. I'm not sure if there's a problem with material settings or a code issue?

Writing e-mails like this isn't hard, but we send hundreds of e-mails to each other every month. Even in this simple example, there's opportunity for the sender to mistype file and object names. And the receiver has to navigate to the appropriate file, search the file for the object, and open the object editor. Wouldn't it be nice to avoid this error-prone and manual labor?

Now we do, with "Object URLs" that directly reference our files/objects. These links can be pasted into an e-mail by the sender and clicked by the receiver. For example, Brian's e-mail now looks like this:

SUP FLURY. There is a rendering problem with http://drool.ws/gameplay/resource/bugs.objlib?obj=bug_eyed.mesh. I'm not sure if there's a problem with material settings or a code issue?

When I click that link, the DROOL editor is launched, the "bugs.objlib" file is opened, and the editor for the "bug_eyed.mesh" object is opened automatically.

Registering a Custom URL protocol

The first step is to register a custom URL protocol for your editor's executable. For example, the "http" protocol is associated with your web browser. For the DROOL engine, we defined a custom "drl" protocol and associated it with our editor's executable. Full details for multiple operating systems are described here, but these quick steps assume you're using Windows:

Copy the text below into a text editor.
Replace all the drl protocols with your own custom protocol.
Replace C:\\path\\to\\your\\editor.exe with the path to your editor's executable (don't forget to double backslashes).
Save the text as a file with the .reg extension (e.g. custom_url.reg).
Run the file via the command line or by double-clicking in Explorer. You'll have to click through some security warnings.

REGEDIT4
[HKEY_CLASSES_ROOT\drl]
 @="URL:drl Protocol"
 "URL Protocol"=""
[HKEY_CLASSES_ROOT\drl\shell]
[HKEY_CLASSES_ROOT\drl\shell\open]
[HKEY_CLASSES_ROOT\drl\shell\open\command]
 @="\"C:\\path\\to\\your\\editor.exe\" \"%1\""

Since we're a two person team, my "deployment" method was to simply check this .reg file into source control and tell Brian to run it on his machine. Large teams probably already have a way to deploy scripts like this to every team member's machine. Large teams might also have multiple editors installed on each machine (for different source branches or projects). For brevity, I'm skipping over these issues here.

URL Format and Parsing

Now that your URL protocol is registered, you can test it by typing a link starting with your protocol (e.g. drl://test) into your web browser. You might have to click through another security warning, but your executable should be launched and the full URL will be passed to it as a command line argument. Now your next coding task is to parse the URL into a file name and object, open that file, and open the object editor automatically. I'll leave the details to you, but if you already support double-clicking your editor files in Windows Explorer, then you've already done 90% of the work.

My URL parsing is bare bones to minimize overhead. I just used standard C string functions to extract the file and object name and I don't worry about properly encoding/decoding special characters (all our file and object names are alphanumeric without spaces anyway). But I did follow the standard URL "query string" syntax so that if I do use a legitimate URL parsing library, it will be trivial to extract the values. You can use any format, but I prefer something that is short while still being human-readable. Our format is simple:

drl://relative_path_to_file?obj=object_name

Making URL Links "Paste-able"

At this point, I thought I was finished with URL protocols, but I discovered that unlike standard http:// protocol URLs, if you paste a URL with a custom protocol (like drl://) into most e-mail clients (like Gmail), they don't automatically get turned into "click-able" links when you send the e-mail. Of course, you can manually make links with custom URLs into click-able links by using your e-mail app's GUI, but that is not quick and easy enough for me. I just want to paste the link and send it!

After some research, I learned that custom protocol URLs aren't automatically click-able in most e-mail clients for security reasons. Unfortunately, the standard workaround is a bit gruesome. The "done thing" is to use a standard http:// URL that sends the user to a webserver, then the webserver redirects to the desired custom protocol URL. It's sad to complicate our tool chain with a webserver like this, but that's what we've done.

So now this URL: http://drool.ws/relative_path_to_file?obj=object_name

Gets redirected here by our webserver: drl://path_to_file?obj=object_name

Now everything works. There are many ways to redirect a URL, but probably the easiest way is to use Apache's mod_rewrite and a regular expression rule. I recommend that you don't do any actual parsing of your URL in your webserver, just do a simple find/replace and then redirect. I prefer to keep all the parsing in my editor and involve the webserver as little as possible.

UPDATE: As commenter F Fulin suggested on #AltDevBlog, an alternative to redirecting is to use a standard, but out-dated, protocol (e.g. gopher://) instead of a custom one. If your e-mail client automatically highlights links using a protocol (and you don't need to use it for anything else) you can hijack it and avoid redirecting.

More Editor Integration

Once you have this much working, everything else is gravy. Now that we can go from an Object URL to a specific file/object in our editor, the obvious next step is to make it easy to extract Object URLs from our editor. When you right-click objects in our editor, the context menu has a "Copy URL" option. Selecting that copies the Object URL for a particular object to the clipboard.

Object URL copying in action

Other Applications for Object URLs

The convenience of Object URLs has already paid off in other ways. Like most game engines, when we detect an error, we print out an error message to standard output. Including the relevant Object URL(s) in our errors makes them more useful and actionable. Conveniently enough for me, in the Visual Studio Output window, http:// URLs are automatically click-able.

It's typical for a large team to have a server that continuously grinds through game files and objects, potentially producing errors for each object based on certain validation criteria. On a large project, you might have thousands of object-related errors at any one time. From my experience, it's challenging to manage this process. Artists and other content creators might not appreciate the importance of these errors and it's hard to keep the overall error count under control. If you include Object URLs with these errors, I suspect that everyone on the team will appreciate the added convenience and will be more likely to fix their errors promptly.

This was also posted to #AltDevBlog.

Hey DROOLERS, Brian here. Resident artist at DROOL. Today, as an introduction to THUMPER, I'm going to talk about the menacing and mesmerizing ZILLAPEDE, one of many hate spewing enemies of Thumper you will meet over the course of development.

I made this guy gradually over the winter as a test as we developed our 'object sequencer'. The object sequencer is one of our fundamental tools. It's a simple system for creating and manipulating sequential data. We use it to create most of the art, music, and gameplay in THUMPER. When I made this, clearly I was drinking too much coffee. I was a bit edgy. I also remember I was listening to the Harmonia album Deluxe on a daily basis, a soothing distraction from the terrors unfolding on my laptop. Occasionally I would run into a roadbock with the tool and need Marc (the DROOL programmer) to help out. We went back and forth on the Zillapede for a few weeks.

There was a point early in the project where we both realized that from an art/design perspective, the tools ARE the game. In game development, the tools have an embedded influence over how everything is created and perceived. Using our tool, the ZILLAPEDE was created by repeating (or instancing) a single mesh many times in a connected sequence.

Don't worry, it's just an instanced mesh.

Unlike most game engines, the DROOL engine has no way to import animation data from the popular 3D animation programs. But that limitation is fine because it forces me to use the object sequencer. I like the challenge of making as much of the art as I can using this tool. It naturally ties everything together to create a universe with a specific and bold look... But seriously, its creeping me out way more than I expected.

Our need for "Object URLs"

Registering a Custom URL protocol

URL Format and Parsing

Making URL Links "Paste-able"

More Editor Integration

Other Applications for Object URLs

SIGN-UP FOR UPDATES

LATEST POSTS

LATEST TWEETS