When the Ape starts, the editor looks like the picture below:
By default, the only tab that is enabled is the one named "General", where you can configure general settings to control the editor's behavior. There are a few options that speak for them-selves, like "Automatic check for updates", so I will refer to others which I believe deserve a few words since they will affect each solution/project created in a cascade manner:
1. Default Main Folder: every time you create a new solution, this is the folder that will be shown by default on the Folder dialog. Think of it as the directory that will hold your solutions and projects.
2. Default Root Folder: for every project created, this is the relative root folder assigned by default to each container. For those like me who come from XNA-based games, this is usally set to "content".
3. Default Build Action: this is the action to execute when building assets from raw files in solutions/projects, which can be "Build Always", "Build If Newer" and "Do Not Build".
4. Default Copy Action: this is the action to execute when copying assets after a build action finishes on a project, which can be "Copy Always", "Copy If Newer" and "Do Not Copy". You will see later that this also refers to "moving assets".
5. Available Platforms: this is the platforms that a solution can support and you can add/remove custom platforms to the ones provided by default. The one marked with an asterisk "(*)" indicates the project that will be automatically added when a new solution is created.
6. Default Writers Per Profile: this control has two purposes; you can add/remove/modify custom compilation profiles as well as the write units assigned by default to each and every one of them; again, the compilation profile marked with an asterisk "(*)" indicates the one that will be selected by default when a new solution is created.
When you add a new profile, you can set its name, the relative folder where assets will copy/move when built, and the default write unit for it. We'll get to the concept of a write unit on a later post.
7. Default Importers Per Category: every import unit corresponds to a category (that you can set when creating the importer), so what you can define here is which will be the default importer for each category. When you add a raw file, the editor will find the category it fits in and from there it will try to assign the default importer; if no importer is found, it will move to a default category and importer (pass through).
Note: both, import and write units are plugged into to the APE as add-ons, so when you execute the tool, the editor will automatically create the collection of available import and write units.
8. Save/Reload Settings: when you change general settings you have to options: either you save the settings for future use or you reoad settings previously saved; if no settings are found (or saved settings get corrputed) the APE will generate and save default settings for you.
Now, what are Solutions and Projects?
A solution is the root node in the APE's logical tree which will directly hold projects as its child nodes. In other words, is the root node that will contain asset projects.
A project is the node that will contain the structure that will be used to build assets for a specific target platform. You can have as many projects you want on a solution but only one per target platform.
When you build a solution, all the project it contains will be built (unless you specify not to build one or more projects). Conversely, when you execute the build action on a specific project, the other will remain intact.
In order to create a new solution, you can open the "File" menu and select the "New Solution" option, click on the "New Solution" icon on the main tool bar, or press "Control + Shift + N".
When you do that, a pop-ip window will prompt you to enter specific information like the name to give to your new solution, the folder where the solution file will be saved, whether a subfolder with the name you enter must be created or not and the "Output folder".
The latter is quite important since it indicates the path to the root folder where all assets generated for the default project will be copied or moved. It works like this, say you have a Visual Studio solution for a game you are developing (or a repository for the assets, not the raw files- to be used); you browse to this path, you select it, and from there the APE will append at build time the relative folders corresponding to the selected compilation profile as well as to each container, when it corresponds.
The initial structure of a solution is the following:
Being the only project created the one that corresponds to the target platform inidicated as the default one on the general settings.
As you can see in the picture above there are two more nodes that are created by default within the project: the initial containers ending in "_Default" and "_Own".
The former holds raw files shared with all projects. Thus, when you add a new raw file to that container, a new node will be also added to the default containers in all remaining projects, with the same name.
And the latter holds raw files assigned only to that project. So, this container is where you put raw files that you don't want to share with other projects.
Now, there is a third type of container: partial containers (to which I also refer sometimes as "shared" containers).
Say that you have three projects in the solution (Windows, XBoxOne, PS4) and you want to share content on the first two (Windows and XBoxOne); well, in order to do that you create a partial container for the windows project, add the XBox One platform and presto!
To add more projects to your solution you either select the "Add Project" item on the "Solution" menu, you click the "Create Project" button or press "Control + Shift + P".
Again, you will be prompted to specify the output folder for the new project.
Ok, moving on ...
When you create or load a new solution, you will see that other tabs will get enabled: "Solution", "Project" and "Container".
Many options in the Solution tab are similar to the ones found in the General tab; in fact, this is where you start to benefit from the cascade approach given that you have the possibility to override the default values given to each "shared" option.
But there is one more relevant option you can set for a solution: "Move Assets". The only explanation I will post for now is that when you build assets, the APE save them on a specific repository for each project and then, copy or moves each asset to its final destination folder (the one located in the output folder for a project).
For projects, the logic is the same as before, tweak parameters to override default values coming from the solution or general settings.
Here you can also indicate:
1. Group Id: even though you can set different behaviors per platform, you can also indicate affinity among specific platforms in order to set the course of action for import/write units. For instance, for XNA-based projects, and id of zero ("0") would mean a "HiDef" profile meanwhile one ("1") or above would mean "Reach" profile.
2. Copy To: remember that for new solutions you had to sepcify the output folder for the initial project? Well, you will have to do the same for the new project. So, each project can have its own output path, which is strongly recommended so that you avoid the risk of overwriting asset files.
3. Default Writers: not only you can override the values that come from the solution or general settings, but also you can change the folder that will be added to the output path when building assets for a specific compilation profile (like Debug, Release, etc.).
Regarding the Container tab, there is no much you can do there other than change the root folder, which is initially set to its default value (usually, "Content").
For default and self containers, names cannot be changed. For partial containers, you can set a different name, and you will also get a list of the projects it shares content with.
There is another tab that is also activated when a solution is created or loaded ("Writers") but I will refer to it on my next post.
Before reaching the end of this part, I would like to refer to the search tool, which you can use when you want to find nodes in the solution that start with a specific character or group of characters ("Control+F").
The beauty of this control is that you can do a new search recursively, that is, on top a previous search. So if you first search for "Windows" and then for "myImage", you will get all the nodes (and its children) that start with "myImage" within the nodes that start with "Windows". By the way, the top-most node (the solution) is not considered for this feature, so the result it would have been the same if you had entered "my" instead of "myImage".
By pressing the "Reset Search" button or "Control+Alt+F" the whole solution is again displayed on the explorer.
This is a powerful tool and I'm planing to extend it with additional features in the middle run.
Well, that's it for now. On part 3 I will talk about adding raw files, compiling projects and a few more useful features available on the APE.
Stay tuned,
~Pete
