Guide to PhyreEngine Part III: Setting up Media Paths

This is the third and final part of my little “Guide to PhyreEngine” series of posts. The objective of this post is to describe how to set up local media directories for your project. I will begin by describing how the PhyreEngine samples handle this and explain why we may not want to do it like the samples. Note that there are tons of ways to do this and in this post I am describing how we did it.

Media Paths in the PhyreEngine Samples

Excerpt from the Asset XML file used in the Basic Sample

As mentioned in the previous post, the PhyreEngine uses an XML file to specify locations to assets. The assets listed in this XML file are converted to a platform specific binary format and the paths for the newly generated files are stored in a header file. In the line of code in the red box, you can see the name of the generated header file (“BasicAssets.h”) this header file is stored relative to your media directory. In the bit in the green box, you can see the path to the asset, relative to media directory.

Definition: Media directory, the directory where all of your assets are located.

As you can see by examining the file path to the asset, the asset in this sample are stored in a directory under the PhyreEngine install directory. For our project, we do not want to store our assets in this directory. We want to store our assets in a directory local to our project directory.

Setting Up a Local Media Directory

This is one of those things that is very simple and trivial to do, but required some figuring out. Let’s begin by creating some folders for our assets.

%ProjectDir%\src           //folder for source code
%ProjectDir%\media         //folder for assets
%ProjectDir%\media\models  //sub directory for models
%ProjectDir%\media\shaders //sub directory for shaders

You may want to make more sub directories for other types of assets but for the sake of simplicity, I will keep this guide to the bare minimums and use source from the Basic sample.

Using the project we set up from the first part of this guide, copy the following files into the, %ProjectDir%\src folder: (if you made any changes to them, make sure they are all vanilla)

%SCE_PHYRE%\Samples\Basic\Basic.cpp
%SCE_PHYRE%\Samples\Basic\Basic.h

Copy the following files into the %ProjectDir%\media folder.

%SCE_PHYRE%\Samples\Basic\Assets.xml    //stores file paths for assets
%SCE_PHYRE%\Media\PhyreAssetScript.lua  //black magic used by the PhyreAssetProcessor
%SCE_PHYRE%\Media\PhyreAssetSpec.xml  //Specs for the PhyreAssetProcessor, allows us to specify where binary files will be generated and what types of files to attempt to convert to binary

Copy all of the contents from: %SCE_PHYRE%\Media\Shaders to %ProjectDir%\media\shaders

Now that we have the bare minimums, we can modify them to suit our needs. Let’s begin by modifying Basic.cpp:

We just need to change one line of code which specifies the Media Directory for our project.

Vanilla Basic.cpp, currently the Media directory is set to the media directory in the PhyreEngine install path

As you can see in the above excerpt (shout out to well commented code!), the media directory is set to the PhyreEngine install directory (%SCE_PHYRE%), we want to set this to our local media directory. We do this by simply making the following change:

Modified Basic.cpp, now our project uses our local media folder

Now that we have set our media directory, we may specify our asset paths relative to this directory in the XML file.

Remember, ALL assets must be inside the media directory, so this means we just have to copy the assets from figure one into our local media directory and it will just work…right?

Before we can test this, we must set up our pre-build event which converts the asset to a binary platform. 

The easiest way to call a batch file, I don’t want to get in trouble posting SCE confidential code so I’ll try to describe how to create this batch file:

Copy the following file to your project directory:

%SCE_PHYRE%\Media\DonkeyTrader\ConvertDonkeyTraderAssetsForPlatform.bat

Open the file in NotePad and change it to say this:

Modified ConvertDonkeyTraderAssetsForPlatform.bat

Now we simply tell visual studio to call this batch file as a pre-build event:

Setting the Pre-Build Event in Visual Studio. Note this is only for the Win32GL platform with a Debug configuration, for other configurations see the Phyre documentation.

Now when we build our project, this command will be executed. Note that I am only showing you how to do this for Win32GL with a Debug configuration, I’m sure you can infer how to set this up for other platforms.

Anyways, if we try running the project, it will not work. Even though we put our Collada asset file in our media folder, it references other assets files (textures, shaders) which are not in our media folder. When assets reference other assets, it is important to make sure that all assets are in the media directory.

For simplicity, I will show how to export a simple cube in Maya:

Create a cube, right click on it and click add new material:

Add a collada Shader:

Now navigate to the shader’s attributes and set the shader.

We want to make sure our reference to the shader asset is relative, not absolute. There are two ways to do this. The sure-fire way would be to create an environment variable which stores your project’s directory and reference all of your assets using that variable or the shoddy way to do it is to use the “Set Project” option in Maya. For simplicity, I will show you the shoddy way, I call this the shoddy way because sometimes the paths are relative, sometimes they’re not. This is only an issue if you want to recompile the project on different computers, or if you move your project directory after you export an asset.

Click set project (shown above), navigate to your media directory and set the directory.

Now select the ColladaDefaultShader.cfgx located in your media directory, and export the model to the model folder in your media directory.

Now we just modify the XML file to use the cube we just exported and we should see it! Of course, since we are not exporting any lights, it will not be shaded but now that you have an asset loading, I’ll let you figure out the rest J.

Remember that this guide just showed the bare minimums to get started, for example, in my project I modified the PhyreAssetSpec.xml and the intermediate directory property to organize the generated data a bit better.

I hope that my "Guide to Phyre" series of posts was enough to give you a push in the right direction with PhyreEngine. I know when I had to figure this stuff out, the internet was pretty much useless, and it was up to me to figure everything out. 

Perhaps this isn't the best way or maybe you're still having troubles, if you have any questions or comments tweet me @MikeGameDev