How can I create a strongly typed structure for accessing files in an XNA Content Project?

Question

Preamble:
I'm working with an XNA Content project to hold all of the various textures (and possibly other resources) that I'm using as part of developing a game.

The default method of loading images from the Content project into an XNA texture object involves the use of hard coded string literals to point to the various files.

I would like to automate the projection of the directory/file tree inside the content project into an object hierarchy to avoid using string literals directly, and to gain the benefits of using strongly typed objects.

Example:
Instead of using
Texture2D tex = Content.Load("Textures/defaultTexture32");
I'd much prefer
Texture2D tex = Content.Load(Content.Textures.defaultTexture32);

Question:
Is there an already existing solution to this problem? (I couldn't find anything with Google)

Extra details:
I'm fairly certain this can be done through a T4 template; probably in conjunction with the DTE tools. I've made an initial attempt to do this, but I keep hitting blocks due to my inexperience with both tool sets, but I've worked with T4MVC in the past which does something similar; unfortunately it projects class structure rather than the file system and is not easily adapted.

I do not require the solution to use T4 or DTE, they simply seem as though they're likely to be part of a solution.

Only including files that are part of the VS project (rather than the entire on-disk file system) would be preferable, but not necessary.

The ability to additionally filter by file types, etc. would be an extra special bonus.

For anyone that doesn't immediately see the benefits of doing this; consider what would happen if you renamed or deleted the file. The application would continue to compile fine, but it would crash at runtime. Perhaps not until a very special set of circumstances are met for a certain file to be accessed. If all the file names are projected into an object structure (which is regenerated every time you build the project, or perhaps even every time you modify) then you will get compile-time errors pointing out the missing resources and possibly avoid a lot of future pain.

Thanks for your time.

Rawhide

It's hard to argue against coding defensively like this.... but I will: The vast majority of games are not/should not be coded to cause "unusual" content loads. They will generally happen at startup or well-defined points (eg: level changes) - ie: they fail early, and should always be exercised in testing. And, rather than "a lot of future pain", a broken filename is trivial to find and fix. So in the vast majority of cases it's not worth expending any effort on this. But it's a very interesting question, and a zero-effort solution would be handy to have, so +1 – Hasten

+1 @Andrew Rusell. It's a common practice in games development not to fail on broken content paths, but to load a fallback texture instead. The fallback texture in most cases would be something like a big red cross with the words "missing texture" or similar. The point is that invalid content references shouldn't cause runtime errors, but visual warnings in the game - for testers to pick up. I believe Shawn Hargreaves goes into a lot of detail on this topic in his excellent tools article on gamasutra. – Ruination

@Ruination You're absolutely correct about the missing texture idea. I've already compensated for that by wrapping a try block around the texture loads which will load a default texture and emit to a log file in the case that a texture fails to load. This is more or less a separate issue. – Rawhide

@AndrewRussell: I accept that it's not a big issue. It's more of a personal distaste for hard coded strings (although really, they're always going to be there somewhere... just abstracted away). I got a peevish at it, and decided to try and fix it; More of an educational exercise than a productivity necessity if you like. – Rawhide

Answer 1

Here is a T4-template which will read all the files in a "Textures" folder from your project-directory. Then they'll be written into a class as strings, you can just change Directory.GetFiles() if you wish to limit the file-search.

After adding/removing files you can click "Transform All Templates" in Solution Explorer to generate a new class.

Hope this helps!

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".cs" #>
<#@ import namespace="System.IO" #>
<# var files = Directory.GetFiles(Host.ResolvePath("Textures"), "*.*"); #>
namespace Content
{
    class Textures
    {
<#      foreach (string fileName in files) { #>
        public const string <#= Path.GetFileNameWithoutExtension(fileName) #> = @"Textures/<#= Path.GetFileNameWithoutExtension(fileName) #>";
<#      } #>
    }
}

Unison

Thanks for the template. With a little perseverance I've actually managed to write a slightly more complex T4 template. I'll add it once I've tested a few more things, but your quick template helped me get there. – Rawhide

Answer 2

I created a more complicated T4 template that uses DTE to scan through the VS project.

I'm leaving Ronny Karlsson's answer marked as the accepted answer as he helped me get to this point with his simpler solution, but I wanted to make this available to anyone that might find it useful.

Before you use this code yourself, please remember that I'm new to T4 and DTE, so use with caution, and although it seems to work fine for me your mileage may vary.

This template will create nested namespaces for the project and all the folders inside of it... inside those namespaces it will create a class for each file. The classes contain a set of strings for useful things about the file.

Also note the two variables near the top... they define which project to scan and build objects for, and the second, List<string> AcceptableFileExtensions does as you might expect, and indicates which file extensions to consider for creating objects. For example you might want not want to include any .cs or .txt, etc. files. Or you might. Adjust as appropriate. I've only included png at the moment, since that's all I need right now.

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".cs" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE"#>
<#@ import namespace="System"#>
<#@ import namespace="System.IO"#>
<#@ import namespace="System.Collections.Generic"#>
<#
    // Global Variables (Config)
    var ContentProjectName = "GameContent";
    List<string> AcceptableFileExtensions = new List<string>(){".png"};

    // Program
    IServiceProvider serviceProvider = (IServiceProvider)this.Host;
    DTE dte = (DTE) serviceProvider.GetService(typeof(DTE));

    Project activeProject = null;

    foreach(Project p in dte.Solution.Projects)
    {
        if(p.Name == ContentProjectName)
        {
            activeProject = p;
            break;
        }
    }

    emitProject(activeProject, AcceptableFileExtensions);
#>

<#+
private void emitProject(Project p, List<string> acceptableFileExtensions)
{
    this.Write("namespace GameContent\r\n{\r\n");
    foreach(ProjectItem i in p.ProjectItems)
    {
        emitProjectItem(i, 1, acceptableFileExtensions);
    }
    this.Write("}\r\n");
}

private void emitProjectItem(ProjectItem p, int indentDepth, List<string>         acceptableFileExtensions)
{
    if(String.IsNullOrEmpty(Path.GetExtension(p.Name)))
    {
        emitDirectory(p, indentDepth, acceptableFileExtensions);
    }
    else if(acceptableFileExtensions.Contains(Path.GetExtension(p.Name)))
    {
        emitFile(p, indentDepth);
    }
}

private void emitDirectory(ProjectItem p, int indentDepth, List<string>     acceptableFileExtensions)
{
    emitIndent(indentDepth);
    this.Write("/// Directory: " + Path.GetFullPath(p.Name) + "\r\n");
    emitIndent(indentDepth);
    this.Write("namespace " + Path.GetFileNameWithoutExtension(p.Name) + "\r\n");
    emitIndent(indentDepth);
    this.Write("{" + "\r\n");

    foreach(ProjectItem i in p.ProjectItems)
    {
        emitProjectItem(i, indentDepth + 1, acceptableFileExtensions);
    }

    emitIndent(indentDepth);
    this.Write("}" + "\r\n" + "\r\n");
}

private void emitFile(ProjectItem p, int indentDepth)
{
    emitIndent(indentDepth);
    this.Write("/// File: " + Path.GetFullPath(p.Name) + "\r\n");
    emitIndent(indentDepth);
    this.Write("public static class " + Path.GetFileNameWithoutExtension(p.Name) +     "\r\n");
    emitIndent(indentDepth);
    this.Write("{" + "\r\n");

    emitIndent(indentDepth + 1);
    this.Write("public static readonly string Path      = @\"" +     Path.GetDirectoryName(Path.GetFullPath(p.Name)) + "\";" + "\r\n");
    emitIndent(indentDepth + 1);
    this.Write("public static readonly string Extension = @\"" +     Path.GetExtension(p.Name) + "\";" + "\r\n");
    emitIndent(indentDepth + 1);
    this.Write("public static readonly string Name      = @\"" +     Path.GetFileNameWithoutExtension(p.Name) + "\";" + "\r\n");

    emitIndent(indentDepth);
    this.Write("}" + "\r\n" + "\r\n");
}

private void emitIndent(int depth)
{
    for(int i = 0; i < depth; i++)
    {
        this.Write("\t");
    }
}
#>

Rawhide

Thanks for posting back your solution. Looks really useful. – Jacquijacquie

Answer 3

I've never seen anything like this done before. The way I would do it would be to create a separate c# console app that scans either the content folder or the content project xml and writes the desired c# code to a file included in your project. You can then run that as a pre-build step (or manually each time you add content). I'm not familiar with T4 or DTE so I can't comment on those options.

Keep in mind that scanning the content project XML has it's drawbacks. You will be able to extract the type of the content item (or at least the content importer/processor assigned), but it may not pick up all content. For example, 3D models automatically include their referenced textures, so these wouldn't be listed in the content project. This might be fine as you are unlikely to want to reference them directly.

Jacquijacquie

If you plan to scan for the XNB output of the content pipeline, you may want to double check whether the pre-build step happens before or after the content build. If it's before, then scanning the file-system is a non-starter and you'd have to scan the XML in the content project file. – Hasten

Right, good point. Another reason to scan the XML: You can have define the target name for the output XNB file there. – Jacquijacquie

Of course, if you scan the filesystem, you'll also get the output filename ;) But you are quite right to mention it: when scanning the XML take the <Name> element, not the Include= attribute, as you can customise the output name. – Hasten