ClanLib Tutorial – Part 1: Getting Started

Part 1 : Getting started

Welcome to the ClanLib Tutorial series, where the end goal is to build a persistent multiplayer architecture using C++. The first two parts will be about general ClanLib usage, while the later parts are more network, game and architecture oriented. You will learn a lot about ClanLib in all parts, since we’ll be using that as our framework throughout. We’ll try to move in small steps, with a focus on code, not on theory.

The network architecture will not end up being a highly scalable, super advanced architecture which could power a Massive Multiplayer Game, there is no room for that in a tutorial series. But it should be usable for small multiplayer games, and could be used as a foundation to build in more scalability and other advanced features later.

Since the code will be in C++, a prerequisites for this series would be familiarity with that language. You can use Linux or Windows as your platform of choice. In this first part we’ll set up the ClanLib environment, and make sure it works with a small example.

Installing ClanLib

All code will be using the ClanLib Game SDK, which is a cross platform C++ toolkit library. Essentially the library offers a series of different functionality under a streamlined API.

To get started, we need to make sure your environment is set up first. If you’re on Windows and use Visual Studio, download the precompiled libraries for ClanLib, and follow the installation procedures. If you are a Linux user, get the source packages and read the linux compilation guide or download binaries from your favorite Linux distribution. The examples will be using ClanLib 2.2.

If you have any problems during this phase, ask for help at the ClanLib Forum – they are a friendly bunch and help with problems pretty quickly. There is also an IRC channel at called #ClanLib. Connect there using your favorite irc client, or connect directly using a web client. You can also find also more ClanLib documentation with their Overview series, or check out the API reference documentation.

Project files for examples

You will need to create some sort of build system or project files for the examples. If you followed the Visual Studio guide above, it showed you how to create a Visual Studio solution. Likewise, the Linux compilation guide showed some simple Makefiles you could use. This tutorial won’t go into detail on how to do this, but a Visual Studio 2010 solution file and a simple Makefile will be provided for each part if you are unable to get this working yourself. If you are using Visual Studio 2008, I’m afraid I won’t be able to provide project files for that, and you will have to create them manually. (If you do, please send them to me, so I can incorporate them into the downloads.)

Creating a Hello World application

Lets start by create a very simple application that boots up a console window and displays a simple greeting to the world. This will be the test to see if your ClanLib installation is working.

#include <ClanLib/core.h>
#include <ClanLib/application.h>

class ConsoleProgram
   static int main(const std::vector<CL_String> &args)
       CL_SetupCore setup_core;
       CL_ConsoleWindow console_window("Console", 80, 200);

       CL_String now = CL_DateTime::get_current_local_time().to_short_datetime_string();

       CL_Console::write_line("At %1, we say Hello ClanLib!", now);

       return 0;

// Create global application object, you MUST include this line or
// the application start-up will fail to locate your application object.
CL_ClanApplication app(&ConsoleProgram::main);

First we include two ClanLib modules – Core and Application. Core contains a lot of common functionality needed in applications – memory handling, events, signals, threading, strings, XML, math, I/O, resources and more. This is the only required module in any ClanLib application.

The ClanApplication module and its corresponding CL_ClanApplication class is a convenience module in ClanLib that helps you with creating a cross-platform main. As all modules in ClanLib, it is not required and you can use a manual approach instead with void main() on Linux, and WinMain on Windows. For maximum portability, we’ll use it throughout this tutorial series.

The ClanLib include files will also make sure the correct library is linked in Visual Studio, so there is no need to specify which library you should link with manually. It will link with ClanLib debug libraries if you compile your application in debug, and release libraries in release mode. Under Linux you will need to manually add the correct linker libraries in your Makefile.

We have a class called ConsoleProgram with a single static function called main, and we create a global instance of CL_ClanApplication. This main function will be called at start up of the application, with any command line arguments in the args vector.

Every ClanLib module (except ClanApplication) requires a CL_SetupXXX object to be instantiated, which will initialize the module. In this example we only use ClanCore, so we initialize that. In the next part you’ll see more modules being initialized.

We create a CL_ConsoleWindow to display our output in. In Linux this will not do anything, as you already have a Console window there normally. But under Windows this will open a console window with the title “Console”, and a text width of 80 and a scroll lines history of 200. This will be handy for debugging and logging later in development.

Finally, we dump out a greeting to the world, and then wait for a key so the console window won’t close immediately after.

Download source code and project files for this part

Hopefully, you managed to get this to compile and run. If so, congratulations on setting up ClanLib! If not, spend the time figuring out the problems now, as we’ll move forward quite quickly from here on. The fun begins in the next part, where we’ll display some more interesting stuff on the screen.

In the next part, we’ll talk about drawing visuals on the screen – read Part 2.

About these ads
  1. #1 by | Manu (@Manu0Alejandro) on February 1, 2012 - 08:55

    Great introduction, especially the whole guide to set up the environment with Visual Studio 2010 is well written and easy to follow. I just made my “Hello World”-program and I can’t wait to go further =)

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


Get every new post delivered to your Inbox.

%d bloggers like this: