Tutorial 01: First Steps

If you've been following the tutorial so far, you'll now have mortic installed and ready. I bet you're just itching to get something done with it! Sadly, your first mortic program won't be all that spectacular, but hopefully you'll understand every bit of it!

The Code

Alright, I'll get you right into the coding, and then explain it afterwards. First, make a directory inside the "mortic" one we got from the source package.

mkdir tut01
cd tut01

The rest of this tutorial assumes that you are working inside a directory called "tut01", right inside the main "mortic" folder.

Now, make a source file, "main.cpp", with the following code:

#include "mortic/mortic.h"

// A simple main function
int main()
{
        // Default and Override configuration...
        mortic::IConfigSet defaults;
        mortic::IConfigSet overrides;
        
        // Make sure that we open up in windowed mode
        defaults.setOption("VideoManager", "fullscreen", "0");
        
        // Make sure that we always log to /log.html
        overrides.setOption("LogManager", "file", "/log.html");
        
        // Finally, we start mortic
        mortic::IRoot* root = mortic::createRoot("settings.xml", &defaults, &overrides);
        
        // Run in a loop until we close the window.
        while (root->run());
        
        // Destroy our root and clean up.
        mortic::destroyRoot(root);
        
        return 0;
}

Compile it with the following command:

c++ -I../extern/irrlicht/include -lmortic main.cpp -o main

You have just compiled your first mortic program! w00t! Now, to run it:

./main

A Look at What you Made

A window should have popped up after you ran your freshly-compiled program. At first glance, not much. You can move it around... It printed a few messages to the console... Other than that, it seems pretty useless. Well, it is pretty useless. The program above is just a bare shell of a mortic program. It does nothing other than open a window and sit there. Still, it has some pretty interesting features.

The first thing you should look at is the mortic console. To get to it, press ESC in the window. A small blue window should pop down that says "Mortic Console". That's it! This thing is like an interactive Python interpreter, except it has access to all of mortic's internals. This thing is very useful for messing around with mortic.

The mortic root you made in the C++ code (more about roots later) is accessable by "root" from python.

Another thing you should look at is the log file. Close the window and open up the new file that was just made, "log.html". Although most loggers only write plain text, mortic's logger writes HTML files for added readability. When you have seen enough of your log file, close it and open "settings.xml" in a text editor.

This file is the configuration file for your program. In it, you can see all of the options available for you to mess with. An example file is given below:

<MorticConfig>
    <VideoManager>
        <fullscreen>0</fullscreen>
        <width>640</width>
        <height>480</height>
        <bits>16</bits>
        <vsync>0</vsync>
    </VideoManager>
    <LogManager>
        <file>/log.html</file>
        <level>notify</level>
    </LogManager>
</MorticConfig>

Let's tweak with this a bit and see if we can spot the changes. I'd change "<level>notify</level>" to "<level>debug</level>". Changing this option changes the amount of info that mortic logs! I'd also change the width from 640 to 800, and the height from 480 to 600. This gives us an 800x600 window instead of a 640x480 window. Let's take a look at our final "settings.xml":

<MorticConfig>
    <VideoManager>
        <fullscreen>0</fullscreen>
        <width>800</width>
        <height>600</height>
        <bits>16</bits>
        <vsync>0</vsync>
    </VideoManager>
    <LogManager>
        <file>/log.html</file>
        <level>debug</level>
    </LogManager>
</MorticConfig>

Sure enough, when you run your program again, it pops up a bigger window, and also spews out a lot more messages to "log.html". Try messing around with some other options and see what happens. If you get stuck in fullscreen mode, just pull down the mortic console and type "quit()" to quit the program.

Examining the Code

Now that you have seen what your program does when it runs, lets take a line-by-line look at how it works. First, we include the mortic header. This is needed whenever we want to use mortic, as it defines mortic's interface.

#include "mortic/mortic.h"

Now, we start a main function. This should look familiar:

int main()
{

Now comes the start of mortic-specific code. When we want to start the engine, we have to give it three things: the name of the configuration file, a list of default configuration options, and a list of override configuration options. The defaults are used when the options aren't found in the configuration file, and the overrides are used to make sure that some values can not be configured. These configuration lists are stored in the class "mortic::IConfigSet". Lets declare a few to hold our options:

        mortic::IConfigSet defaults;
        mortic::IConfigSet overrides;

Now, we set a few options. First, we want to make sure that the program starts up in windowed mode the first time. Otherwise, you would have been stuck in fullscreen without knowing how to get out!

        defaults.setOption("VideoManager", "fullscreen", "0");

Notice how this corresponds to the settings.xml we saw. Now, we also want to make sure that we always, always log to log.html:

        overrides.setOption("LogManager", "file", "/log.html");

Again, try to change this option in settings.xml. Notice that no matter what you change it to, it always changes back!

Now that we have all of our options set, we are ready to start mortic:

        mortic::IRoot* mortic::createRoot("settings.xml", &defaults, &overrides);

All of mortic is controlled through one class: the Root. Roots are always created with createRoot(), and are always destroyed with destroyRoot(). All of the individual managers can be accessed through the root, and every object ever made can be found, through ID number, from the root. This is a little complex, but always remember: the root is like the heart of mortic. It keeps everything running.

Now that we have our root, we start running it. Every time you call IRoot::run(), two things happen. First, it goes through one frame of running. You should call this every frame. Second, it checks to see if it should keep running. This function returns false if the window is closed, or something else happens that causes mortic to want to quit. Thus, this little while loop works fine! It calls run() as often as possible, but stops and quits as soon as it returns false!

        while (root->run());

After that bit, it's time to quit. We do this by destroying the root and returning from main():

        mortic::destroyRoot(root);
        return 0;
}

Unanswered Questions

Although the bulk of your program was explained above, there are a few things that I left out because you needed to understand everything else before I attempted to explain these.

Why does "/log.html" somehow write to "./log.html"?

This is because mortic uses a virtual file system, much like Linux itself. In this type of system, you mount areas of your hard drive on to areas of an imaginary filesystem. This lets you do a lot of neat things, too, like mounting a website onto a path in the VFS. In this case, the current directory, "./", is mounted onto the root of the VFS, "/". This means anything accessed from "/" will really be accessed from "./". This is a little confusing, and I do a better job of explaining in Tutorial 03 - Mortic's Virtual File System.

Why is everything prefixed with "mortic::"?

This is because everything in mortic is in the namespace "mortic". If you find that tiring, you can get rid of typing that by putting the line

using namespace mortic;

at the top of the file. This is here to prevent name collisions with other libraries you may want to use.

---