Today, I’m releasing a command line utility for people working with XNA Game Studio and targeting Xbox 360. This utility is pretty simple and supports four commands:
- Send a local file to an existing title container on Xbox 360.
- Delete a remote file from an existing title container on Xbox 360.
- Print out the title ID of a game from its CCGAME file.
- Launch a game in an existing title container on Xbox 360.
This isn’t groundbreaking, but it enables some useful development scenarios for more advanced developers.
One of the most compelling abilities of xnacmd.exe is that it allows you to deploy a file to a title container while the game is running.
Another compelling ability is that it lets you add files to title containers created from CCGAME files. This is interesting for play testing and peer review scenarios, where all you have is the CCGAME file, and the title ID has been reassigned by Microsoft.
The ability to delete files from a container is really just there for parity, to allow you to remove files that you deployed.
Launching a game from the command line without Visual Studio can also be useful.
So that’s it; it’s just four commands.
A particularly interesting scenario for this utility is content editing and preview. There are numerous samples floating around that illustrate how to host the content pipeline to build your content from an editor, but zero samples that show how to easily deploy that content to your console and see it in-game.
With this tool, you now have the ability to update content without rebuilding your whole game, and without even restarting it. The catch is that you need to add a feature into your game that triggers a content reload. This may not be easy, but it can be worth figuring out if you can simplify life for your designers and artists.
Another scenario that I particularly like is to unlock game features or cheats using a specially-named file. You could have your game check for the existence of a file at startup (eg, “unlock.txt”), and expose hidden features only if the file is present. Then, of course, you could put your game into playtest or peer review without the unlock file, but provide it to testers and reviewers to deploy with xnacmd.exe. That way, your game can’t fail for having unreviewable content, but the features will not be unlockable except through legitimate gameplay or secret codes after the game is approved and hits the marketplace.
Now, please be aware that xnacmd.exe only works when XNA Game Studio Connect is running, or when a game launched through XNA Game Studio Connect is running, and it will only connect to your default console because I was lazy and wanted to keep the command line options simple. It will not work with games downloaded from the marketplace.
Finally, you need to have XNA Game Studio 4.0 installed in order for this command line tool to work. The stuff it depends on is not redistributable, so don’t bother asking me for a way to install it stand-alone.
A few notes about usage:
XNA games are deployed into virtual file systems called title containers (similar in concept to a ZIP file). When deploying files, the title containers are referenced by something called, “title ID” (note: You’ll see this mentioned in the VS Output window when you deploy your games). When sending or deleting files from a title container with XnaCmd, you need to specify the title ID as part of the remote file path.
For example, this is a command I used for testing:
xnacmd send test.txt f6c44f88-a295-4b24-9709-80b5d4708bba\test.txt
When deploying from Visual Studio, the title ID is the GUID used in your startup assembly’s GuidAttribute (see your project’s AssemblyInfo.cs). This same GUID is used as the title ID when you build a CCGAME. However, when you submit your CCGAME to XBLIG for play testing or peer review, the CCGAME that everyone else downloads is given a new title ID by Microsoft. Use the “xnacmd titleid <ccgame>” command to see this GUID.
- Be sure to close/dispose any files that you plan on updating at run time.
- If something goes wrong and you can’t deploy anything anymore, even from Visual Studio, try killing xnatransx.exe (using Task Manager).