Easy Collaboration with Object URLs

Original Author: Marc Flury

At DROOL, 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:

  1. Copy the text below into a text editor.
  2. Replace all the drl protocols with your own custom protocol.
  3. Replace C:\path\to\your\editor.exe with the path to your editor’s executable (don’t forget to double backslashes).
  4. Save the text as a file with the .reg extension (e.g. custom_url.reg).
  5. Run the file via the command line or by double-clicking in Explorer.  You’ll have to click through some security warnings.
   @="URL:drl Protocol"
   "URL Protocol"=""
   @=""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:


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 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 below, 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 the DROOL Development Blog.