THE ASSET PIPELINE EDITOR - PART 3

On part 2 of the series, I talked about some basic features of the APE, so it's time to show how to change the structure of a project and populate it with some raw files, that is, before starting to build assets.

I could begin this post by telling you how to create a new solution from scratch, but instead, I'll show you a nice small feature the editor has that allows you to open recent solutions, which spares you from having to use the Open Solution menu option ("Control + O") and browse folders until you locate the solution file.

Do you notice the small red (almost transparent) cross beside the only entry in the list of recent solutions? If you press it, you will be prompted to confirm entry's removal from the list. The cool thing is that APE does not need to restart in order to refresh the list. Ditto for "Clear All ..." option.

Once the solution is loaded we can start modifying the tree structure to meet the needs for our game. This is how the solution looks like so far:

Let's add a couple of nested folders to the Windows_Own container by selecting the "Add Folder" menu option (or clicking "Control + Shift + F") twice. Now our solution looks like this:

By default, folders will be created with the name "folder_<#>", so let's renamed them with a meaningful word (by double-clicking the node):

Better, right? But wait a minute! What if we want to have a similar structure on the default container? All you have to do is open a context menu for the node you want to copy (right-click over "textures") and you will be presented with this:

\

You have two options there: either you move or copy the node and all of its content to another non-nested location; in this case, to the Windows_Default container. Note: if you try to move or copy the "images" folder into the "backgrounds" folder the operation will fail.

Since we want to replicate the structure, we then select the copy option. Then, by opening the context menu fro the default container we will get the following:

By pressing paste, the new structure for our solution will look like this:

It's important to mention here than we could have obtained the same result by using drag'n'drop. Yes! Dragging the textures folder and dropping it onto the default container would have been allowed. In fact, when you drag'n'drop nodes in the solution explorer, the APE asks us what we want to do with them: move, copy or cancel.

Also, it's worth mentioning that, in this case, we could have copied the whole content of the self container ("Windows_Own") by using the context menu for the container. That is also allowed. The difference is that in this case the container it-self won't be moved or copied, just its child nodes.

Now, let's add some raw files. Shall we?

There are three ways to add raw files to containers or folders: (a) you select the container/folder and then use the "Add Raw File" menu option/button (or press "Control + Shift + R"), (b) you select the container/folder, open the context menu for it and click on the  "Add Raw File" option, or (c) you use drag'n'drop (you can import raw files into your solution by dragging them from the explorer and dropping them onto the container/folder).

In the picture below, you can see how to use the context menu for the target folder.

One important feature to mention here is that you can import more than one file at a time (batching) with any of the three ways the editor offers, including drag'n'drop.

For the example, we just added a nice cloud background to the backgrounds folder:

The picture above shows a lot of new information about the editor:

1. The name given to the added raw file is its filename (without the extension, if any). This is true provided that the name does not exist in the same "relative" location of the solution's structure, or else it will be renamed to "file_<#>".

2. On the container tab, the editor will show you the proper previewer for the file (remember that if none is found it will just show the system icon for it).

3. A new tab gets enabled: "Raw File". Here is were you tweak import settings for the raw file. The APE will try to assign an importer to it based on the file extension, giving priority to the importers marked as default (more on this on later posts).

4. The source file is copied into the "Sources" folder for the solution. This folder works as a repository for the entire solution, so you cannot have two source files co-existing with the same name on the folder since one of them will be replaced. This has nothing to do with the names you give to the nodes on the solution explorer (you can have two nodes with the same name in different "relative" locations on the solution tree).

In order to change the name of the raw file we could do it in the same way as before by double clicking on the node, but in this case we will use the "Name" field on the raw file tab and rename the node to "bkgClouds".

Now, before showing you how the structure of the solution currently looks like, let's add a new project for, say, the iPhone platform. And here it is ...

As you can see the default containers on both projects have the same exact structure; however, the self containers are different. In effect, that is the purpose of self containers.

Although the "bkgClouds" raw file is present in both default containers, it is treated as a deep copy; so mirror operations are bound only to add/remove/copy/move. For properties, like importer, processor and formatter-like settings, each node is independent, so you can have one set of settings for the raw file for the iPhone and a different set its sibbling on Windows. Really great!

Now, what if you want to import two different source files but keeping them under the same raw file on different projects? Let me translate it with an example ... say that you want to replace the source image for bkgClouds but only on the iPhone project with a lower_res version, well ... yes, you can! How? Simple. Look at the picture below:

On the Raw File tab there is field named "File" with a button labeled "..." (marked all in red), which shows the location to the source file in the solution. When you click on the button you can browse your folders until you get the file you desire.

In this case, we'll select the 320x200 texels version of the cloud image for the iPhone platform to get this window:

The APE will prompt us to confirm the operation and also it'll let us delete the existing source file if needed. Since this is not the case, given that we need both of them (one for Windows and the new one for iPhone) we let this checkbox unmarked.

Once the operation completes, the image previewer for the "bkgClouds" raw file on the iPhone project will show the new information. Now we have two different source files for the same logical name. And therefore, after building assets, when you load the "bkgClouds" texture on your game, you will get the 640x400 version on Windows and the 320x200 on the iPhone. No need to add "_640x400" or "_320x200" to the load operation.

Let's have a look at our solution's Source folder:

As you can see, the respository has both source files for the same raw file. And I guess that you now fully understand the difference between "source" and "raw"" file (if not, the former is the actual file and the latter its representation on the solution's tree).

Ok, before finishing this post, let me show you one more relevant feature the APE offers. For this task, say that you accidentally messed with the Source folder and deleted one of the images; for instance, the one ending in _640x400. What would happen? Well, when you re-open the editor, you will see the following:

The APE is indicating you that the solution is corrupted and also marks the path to the offending raw file. To fix it, you can either manually copy+paste the source file to the Sources folder or you can use the Raw File tab -as we did before- by clicking the "..." button beside the "File" field and browsing to the location of the source file.

In order to valdiate the solution you have to options, either you save, close and re-open the solution (in which case the APE will warn you that you are attempting to save a corrupt solution) or use the validate menu option ("Control + Shift + V") ...

Having finished the validation processed, the editor will look like this:

So, we can now safely continue to work normally with our solution and save it whenever we want.

Btw, you can browse to the folder where you solution is located by using the "Open In Explorer" menu item (ditto for projects) ...

And you'll get to ...

Do you notice the icon on "MySolution"? When the editor is closed you can open it and also load the solution by clicking its file. Indeed. The APE will open and load the solution for you.

Ok guys, this is all for this post. On my next post we'll talk about building assets.

See ya!
~Pete