Introduction - 'Hello World'

From C4 Engine Wiki

This tutorial will show you how to set up Visual Studio 10 for creating a new project and then create a new Dynamic Link Library (DLL) Hello World game file. This DLL is required by C4 in order run the Hello World game example. Make sure you are able to compile the projects that come with C4 before doing anything further. If you are unsure of how to do this, see Getting Started and Building the C4 Engine for details.

What is a C4 Engine Game DLL?

The C4 Engine Game DLL is a DLL that contains all of your game code. By telling the C4 Engine which game DLL to load, you can change the game code that is being run. It's very similar to a plug-in system, with the exception that you only need one game DLL. When you create a new DLL project, you will also need to change which DLL you want C4 Engine to load on startup. First let's set up the IDE.

Part 1 - Creating a New Project

We will first create a new project by choosing File > New > Project.

Select Win32 Console Application.

Enter HelloWorld in the Name text box for the name of the project. It should automatically change the solution name as well.

Click OK.

After clicking OK you should see a second dialog titled, "Win32 Application Wizard - HelloWorld".

Click Next to advance to the Application Settings panel.

Select DLL for the Application Type option.

Check the Empty project option under Additional options.

Click Finish to create the project.

Part 2 - Hello World in C4

Creating the Game class

We will start off by creating two new files, Game.h and Game.cpp—these will contain our new class respectively named Game.

To do this, right click HelloWorld in the Solution Explorer.

Select Add > Class.

Select C++ Class.

Click Add.

Enter Game under Class Name. The .h and .cpp name fields should automatically change as well.

Click Finish.

You now should have the Game.h file listed under Header Files and the Game.cpp file listed under Source Files.

Replace the auto generated code in Game.h, with the following:

#ifndef GAME_H
#define GAME_H
 
#include "C4Application.h"
#include "C4Interface.h"
 
extern "C"
{
	C4MODULEEXPORT C4::Application* ConstructApplication();
}
 
using namespace C4;
 
namespace HW
{
	class Game : public Singleton<Game>, public Application
	{
	public:
		Game();
		~Game();
	};
 
	extern Game* game;
}
 
#endif // GAME_H

The code above simply includes a few C4 Engine header files and then creates our class declaration. Notice how our class inherits from two sources:

• Singleton is a template that ensures that only one instance of our class is ever created.
• Application is the key object that is used to get our game started. It handles initialization, destruction, and many other important events for our game.

Also notice an extern declaration. Every application/game module needs to declare the function called ConstructApplication(). The engine looks for this function in the DLL and calls it to construct an instance of our Game class. C4Interface.h is needed for our “Hello World” text to display.

Now let's enter the following code for Game.cpp

#include "Game.h"
 
using namespace C4;
using namespace HW;
 
Game* HW::game = 0;
 
C4::Application* ConstructApplication()
{
	return (new Game);
}
 
Game::Game() : Singleton<Game>(game)
{	
	// Creates message without using tags
	TextWidget *pText = new TextWidget(Vector2D(80.0F, 16.0F), "Hello World!");
	pText->SetFont("font/Bold");
	pText->SetWidgetColor(ColorRGBA(0.0f, 0.0f, 1.0f));
	pText->SetWidgetPosition(Point3D(50, 50, 0));
 
	// Adds widget to the screen
	TheInterfaceMgr->AddWidget(pText);
 
	// Report a message to the log file
	Engine::Report("<br /><div>Hello World!</div>", kReportLog);
}
 
Game::~Game()
{
}

We first include the Game class header. After that we declare using namespace C4. Everything declared in C4 is contained in the C4 namespace. This statement just makes it easier for us to code without having to have C4:: in front of everything. Under that is our global pointer to our game object allowing us to access it from anywhere in our code.

Next is the function that will create our Game instance. This function is an external function meaning that it can be accessed from outside our DLL by the main C4 executable. C4 will use this function to tell us that our DLL has been successfully loaded. We take this chance to create and return our own subclass of the Application class called Game.

After that we declare our class's constructor. Notice the Singleton<MyGame>(TheGame) after the declaration. This sets our class's instance as the single instance allowed in our game DLL. Within the function we create our “Hello World” text. First, we create a widget to store our text. We pass in the string to display and a vector containing the width and height of the widget. Think of it has a clipping plane. If the size isn't large enough, not all the text will display. Next we call some of the widget's methods to change it's properties a bit. The font, color, and position is adjusted.

We then display the text by passing the textWidget into the interface manager through its global pointer TheInterfaceMgr. Once passed in, the widget is automatically displayed on the screen. Our destructor does nothing in this tutorial but it will normally be used for tidying up once our game is closed down.

Finally, we write a quick excerpt to the message log which is created everytime C4 executes. To learn where this log file is written, check out File Locations.

Part 3 - Setting up the IDE

We now need to set up our include directories and path settings so that the compiler can find all the correct source and library files.

Right click the HelloWorld project file within Solution Explorer.

Select Properties.

With the HelloWorld Property Pages open, we can begin setting the required paths for compilation.

Select the C/C++ section.

Under Additional Include Directories we need to add the following entry:

YourC4Directory\Engine Code

Now we need to add some preprocessor definitions to our current definitions list. This can be done under the C/C++ > Preprocessor subtree. Look for the Preprocessor Definitions line and add the following values to what is already contained in the box:

C4WINDOWS
C4DEBUG

If you are using the Basic Edition of C4, then you will also need to add C4BASIC to the list of preprocessor definitions.

Now we need to set up the libraries that the project uses. Go to the Linker tree section. Under Additional Library Directories add the following value:

YourC4Directory\VisualStudio\C4\Engine\Debug

Now change to the Linker > Input sub tree. Add the following library file to the Additional Dependencies section:

C4.lib

Now we can setup our output directory so that our newly compiled DLL is written to the same directory that the C4.exe file is stored. You can do this in the Configuration Properties > General tree. Replace what's in the Output Directory with:

YourC4Directory\

Now we can setup the IDE to execute C4.exe when running from the Debug menu. Select Configuration Properties > Debugging tree. Change the Working Directory to be the same directory as used in the previous step. Then update Command with:

YourC4Directory\C4.exe

Click the OK button to apply the changes to the project properties.

And now that your compiler settings are done, all we need to do is tell C4 to use our new game DLL.

To do this you need to open the configuration file located here:

YourC4Directory\Data\Game\game.cfg

In this file you should see an entry for $gameModuleName. You need to set it equal to the name of your DLL excluding the .dll at the end. Since your project is named HelloWorld, the entry should look like:

$gameModuleName = "HelloWorld";

Save the file.

You are now ready to run the application. Simply compile the project and start up C4. You should now see “Hello World” shown in the top left corner:

Well that's it for this tutorial. It's nothing massively exciting but it should give you a good starting point for using C4 Engine.