DreamBuilder – A command-line Dream builder

If you have tried to make Dreams in the past, you have been using DreamMaker. This application allows you to take a video file (or several of them in case of a trigger-based Dream) and "compile" it into a .Dream file. This Dream file also contains other information such as the name of the author, a website URL, copyright and permissions info, and a preview image.

MatrixTrails.xml - Notepad2One of the current limitations of DreamMaker is the lack of a save/load mechanism, requiring you to retype everything each time you want to create a new Dream (or update an existing one). While this might not be a big deal with video and trigger-based Dreams, it begins to be a real pain the moment you start creating dynamic Dreams (even more so when you have 8 or 10 of them in development/testing at the same time).

Enter DreamBuilder: a command line tool to build Dreams. It uses a simple XML configuration file to load the info needed to build a Dream file. No more re-typing ! Now you can have the Dream creation cleanly integrated into you build process.

DreamBuilder is using the DreamMaker.dll file (part of the DreamMaker distribution) under the hood to create the Dream file, so the Dream files created will be the same that DreamMaker would have created. Error messages that DreamMaker normally shows are redirected to the console.



DREAMBUILDER inputFile [/O<outputDirectory>] [/D<variable>=<value>]

    inputFile             Path the dream definition file
    /O<outputDirectory>   Path to the output directory
    /D<variable>=<value>  Defines a variable to be replaced in the XML configuration file.
                          Several such variables can be defined. 

By default, the Dream file will be created in the current directory, but you can specify an output directory (such as the default Dream directory in "My Documents/Stardock/Dreams")

Configuration file:

Here is the example configuration file (included in the distribution).

<?xml version="1.0" encoding="utf-8" ?>
    <!-- Dream name - max size: 100 characters -->
    <!-- Dream description - max size: 600 characters -->
    <!-- Author name - max size: 100 characters -->
    <!-- Author url - max size: 200 characters -->
    <!-- Dream copyright information (optional) - max size: unknown -->
    <!-- Dream permissions information (optional) - max size: unknown -->

    <!-- full/relative path to preview file - max size: 256x256 - BMP, JPG, JPEG or PNG only -->

    <!-- 3 possibilities: video / trigger / dynamic (if more than one is defined, the first one found is used, others are ignored) -->
        <!-- Video dream - full/relative path to video file - max size: 150MB - AVI, MPG, MPEG or WMV only -->
        <!-- Triggered video dream - type: only "time" is allowed at the moment-->
        <triggers type="time">
            <!-- Trigger definition - at least two different triggers need to be defined -->
                <!-- Time to trigger the video - in hh:mm:ss format  -->
                <!-- full/relative path to the file - max size: 150MB - AVI, MPG or WMV only -->
        <!-- Dynamic Dream -->
            <!-- Path to 32-bit dynamic dream dll -->
            <!-- Path to 64-bit dynamic dream dll -->
            <!-- Additional content (optional) - max number of files: 150 -->
                    <!-- full/relative path to the file -->
                    <!-- target path (relative to the root dream folder) -->

DreamBuilder is checking the XML configuration file against an XML Schema, so it will tell you if there is an error in your configuration (but the message might be a bit cryptic).

Visual Studio 2005 Command PromptDreamBuilder allows you to use relative paths when defining the files to use. By default, it will look for the files relative to the current directory.

This might be a problem if you are executing it from another folder that the one containing the files. This is why I introduced variable replacement: it provides a way to dynamically replace content in the configuration file. I use it for path handling, but you can also use it for other things such as adding a version number to the dream name.

The replacement step is happening before the file is parsed, so you can go crazy if you want, and generate the resource list at compile time for example.

You can have as many variables as you want (simply by adding another variable definition to the command line). To define a variable "name" with the value "Julien", you use the following define: "/Dname=Julien". You can then add a new variable to the XML configuration file: $name$. DreamBuilder will warn you if a variable exists without a substitution.


As an example, here is the config file I use for the MatrixTrails dynamic Dream:

<?xml version="1.0" encoding="utf-8" ?>
    <description>Matrix Trails Dream</description>    
    <author>Julien Templier</author>
    <copyright>Copyright (c) 2008, Julien Templier[...]</copyright>
    <permissions>This program is free software; you can redistribute it and/or [...]</permissions>



You can see all the files have a variable at the beginning of the path. Those will be replaced when the Dream is built.

In Visual Studio, I then added a post-build step calling DreamBuilder that takes care of defining the right variables:

DreamBuilder $(ProjectDir)/Resources/$(ProjectName).xml /O$(TargetDir) /Dresdir=$(ProjectDir)/Resources /Dbuilddir=$(TargetDir)

That way, each time a build succeeds, a Dream is generated that can be easily tested & distributed.


DreamBuilder is currently available as a zipped file (to be extracted to the directory of you choice). You might want to add it to your path to be able to call it from anywhere.


A MSI file is planned that will take care of adding the installation folder to the path.