Friday, December 13, 2013

THE ASSET PIPELINE EDITOR - PART 5

In this part of the series I'll answer some of the questions that some of you've been asking me lately, in particular:

  • Does the APE watch source files?
  • Is there a command-line version of it? And
  • Why not publish it as open-source?
I attempted to give brief answers to a couple of them in this thread at GameDev, and also by email to the guys behind the WaveEngine, but I think they deserve a post here with further details.

So, let's begin ...

Does the APE watch source files?


To aswer this question, I need to explain what happens when a new solution is created and saved.

Basically, after saving a solution you will find the following structure on disk:

   + Root Path
      + [Solution's Name] folder
         - [SolutionFileName].fps
         + "Sources" folder
             - sourcefile1
             ...
             - sourcefileN
         + "Projects" folder
            + [Platform1's Name] folder
                - [ProjectFileName1].fpp
               + "Builds" folder
                  + [Profile1] folder
                     - output.fpb
                    + Content folder
             ...
            + [PlatformN's Name] folder
                - [ProjectFileNameN].fpp
               + "Builds" folder
                  + [Profile1] folder
                     - output.fpb
                    + Content folder

The APE creates a folder named "Sources" which will be used as a "local" repository for the whole solution. Within it, you will only find files (no folders). Thus, when you add a new file to any of your projects, the APE will copy that source file to the respository and create the corresponding raw file to the strcuture of your solution.

Following this rationale there is no need to dynamically watch file changes. Why? Simple, if you manually change one of the source files directly then the next time you build content that source file will be used to build assets provided it complies with the condition indicated for building: Always|New|None.

In other words, the APE watch changes over an existing source file only at the moment that new builds are requested. If a project is marked as "Build Always" then no matter what, all included raw files will generate a new asset file. If a project is marked as "Build If New" then only raw files with new source files assigned will end up having a new asset file. Finally, "None" will exclude the project from the build process.

Now, there was a second part in the question posted on GameDev's forum with had to do more with the processing-side of things than with what I've explained above.

The APE will NOT replace production tools like Photoshop, Sound Forge, and so on so forth. So you will need to create your source files there: jpegs, wavs, mov, etc.

What the APE provides is a way to indicate how to process source files to get the file format you need for your games. In case the built-in import/write units or the ones provided later on by me and or any other user are not useful to you, then you can implement your own with full control over them.

So, if you guys want to implement a processor that converts WAVs into OGGs, you can go ahead and do it with ease. What about resizing a texture? Sure. What else? Everything you can imagine of that can be achieved by setting parameters on a property grid.

For example, for the case of XNA'ers, in part 4 of the series I showed a processor with many features that pre-multiply alpha, resize textures, change formats and so on.

So to sum up this part of the question, to create source files you will need to use production tools. But to import them to your games with as asset files with given format, you can use the APE.

Is there a command-line version of it?


Yes, there is! And it's name is "APEBuild" (thanks Javier for suggesting the name!).

When I designed the APE I took into consideration server-side-like use cases. As a matter of fact, it resulted as a corolary when I develop the base test assembly for import/write units (please refer to part 1 to see an image of it).

In the current state of this command-like tool, only two actions can be executed: either you build an entire solution or only a set of projects. Let's have a look of the structure ...


The picture above shows what you get when execute the tool with no parameters (and also with wrong parameters).

So, if you want to build a solution, just execute the tool with one parameter: the path to the solution file. And if you want to build some of the projects in the solution, then add "p:" as an argument, followed by the names of the target platforms, separated by a comma. See the example in that picture.

Now, there are a few restrictions: first, the solution filename must always end with ".fps"; second, the tool will handle trimmed versions of the platforms' names; third, all passed platforms must exist in the solution or the tool won't execute; and fourth, when you pass a relative path to the solution, the path to the folder where APEBuild is located will be considered the root folder in order to build the absolute path.

So, when we execute the command for the entire solution we have been using as an example on the series, this is the result for a successful build:


And when you execute the command for a couple of pojects, the result would be the following:


You will also get messages in case of warnings and exceptions:


The above picture shows a warning indicating that an import unit that should have been plugged into the tool as an add-on is missing. However, since it's not used during the build process, the latter runs normally.

So, it is important to remember that:

1. Before executing the command you will need to check that all the import/write units are present in the corresponding folders associated to APEBuild (as you would also do with the APE's editor), and

2. When you commit source files, you will also need to commit the updated versions of the APE's solution/project files to the server or otherwise you won't get the results you were most-likely looking for.

There are some features I'd like to add in future versions like, say, verbosity control (that is, the level of detail you get as output), but the tool gets the job done in its current state, what is really handy!

Why not publish it as open-source?


I'd have prefered to address this question more close to the campaign's launch date, but since a few of you've asked this question recently, I decided to answer it now.

But before moving forward, I'd like to state that I will neither argue nor open a discussion regarding whether open source is good or bad business-wise, since that depends on factors whose relevance may vary per person (yes, "YMMV") and therefore not only does it lay beyond the scope of this post but also I don't feel like pursuing a Phyrric Victory.

Instead, I'll be posting a few words explaining my decision to publish it as a commercial tool in the near future -that is, provided the campaign at IndieGoGo succeeds.

Honestly, I haven't decided yet the price for a license but I intend to license the APE per seat per platform per major version. Yes, if you buy one license at launch, you will be able to use it for the whole v1.x! No annual subscriptions, no different versions for indies/pros, no complications to anyone.

Now, although the price is not yet decided, believe me when I say that it will be low and even lower for those of you who decide to contribute to the campaign at IndieGoGo. I'm an indie, so I know what it feels not being able to afford licenses from time to time. So during the campaign it'd be like going out with some folks to a movie theatre, say, on Friday's night.

So, why this decision?

First, open souce is difficult to keep alive in time. You need to coordinate efforts, check contributor's code, handle branches, even maybe, at some point and to some extent, include contributors into the decision-making process.

But that is not it, most of the people in the team would likely have daytime jobs, so development of updates to the tool would be done during the night provided the is some spare time left. Going to college? Does your job demand most of your productive time? Have a wife/husband? How about some kids? Then, you know the drill ...

It's not a surprise that many open source APIs and tools eventually follow the commercial route, or that their owners publish a letter indicating why the cannot continue working on it or that updates will slow down. It's completely understandable! There's lot of time, effort and even money put into it, and even though donations could be received, the latter eventually end up being not enough to even cover costs of production. Not to mention, costs of living.

So, instead of trying the open source route first to then follow the commercial one, I prefer to skip that part and commercialize licenses of the APE from square one. Succeeding in this task will assure the continuation of the tool since I will dedicate, not my spare time, but my production one to make it happen. And if I fail I'll continue to use it as is for inhouse projects. No hard feelings.

I have one more thing to add in this respect as an example: the guys behind the Mono Framework started the project as a non-profitable endeavour. But then, they realized that in order to continue offering the products they loved to develop, a change in course was imminent. For many, this could have been a change in principles but for me it was a wise decision. Today, they're successfully runnning Xamarin, they're growing strong and their products are a must have for every serious dev that want to port .NET-based apps/games to many platforms. And even MSFT recognizes it!

Btw, regarding XNA's Content Pipeline: it was freely available as long as you didn't want to develop games for the XBox 360 (and then, the Windows Phone). Otherwise, you had to pay an annual subscription for the Creators' Club and a registration fee for the Windows Phone (both now unified).

So to wrap up this third question, before using the word "disappointing" -given the fact that it won't be open source, please give the APE an opportunity to show off its key features and wait for the campaign at IndieGoGo. You won't be dissapointed!

Ok, this is it for this part of the series. Hope you all come back for the upcoming part 6 next week.

See ya next time,
~Pete

PS: btw, I recommend you to have a look at Xamarin's subsciption plans if you haven't yet!