Targeted audience:

Required reading:

Required knowledge:


STEP 1: Creating New Project

First, you need to make a new Developer Studio Project, to build a DLL where entity classes will be packaged. Create a new project of type 'Win32 Dynamic-Link Library' and name it 'Tutorial'. You can add it to an existing workspace or create a new workspace for it. It is up to you.

IMPORTANT: Make sure that you put it in the Sources directory, since the include path points there.

When the DLL wizard asks you what kind of DLL do you want, answer 'An empty DLL project'.

STEP 2: Adjusting Global Settings

Go to Project/Settings.

under 'Debug' tab

For 'Executable for debug session' type the path to SeriousEditor.exe in the Bin\ directory of the engine dir. For 'Win32 Release', use the release version of SeriousEditor.exe. For 'Win32 Debug', use the debug version of SeriousSam.exe located in the 'Bin\Debug\' directory.

[licencee programmers only]
You must put debug version of the Serious Engine executables to Bin\Debug\ directory to be able to run in debug mode. The debug build is distributed separately from the original installation, since the artists and level editors do not need it.
[/licencee programmers only]

[public programmers only]
If you do not have the debug build of Serious Engine, you will not be able to run the debug version of your entities. In that case, you can manually turn off optimizations in the release version while you are debugging. That way, you should be able to debug it normally (viewing the variables, etc). You just won't have extra safety checks made by the engine, like assertions and similar.
[/public programmers only]

under 'C/C++' tab

In 'Code Generation' category, for 'Use run-time library' select 'Debug Multithreaded DLL' for 'Win32 Debug', and 'Multithreaded DLL' for 'Win32 Release'. If all separate executables (entity packages, engine, game, editors, etc.) were linked to the static runtime library, loading several modules at the same time would consume too much memory. This way they all share one instance of the runtime DLL.

under 'Link' tab

In 'General' category, enable 'Generate debug info' and 'Generate map file', for 'All configurations'. This way, the debug info will be generated even in release version (it is stored separately from the executable, so it won't hinder it in any way and you will not distribute it). Also, map files allow you to later track crashes that might occur for your end-users or beta-testers using '.rpt' files that engine generates if the program crashes.

Change 'Output file name' for 'Win32 Debug' fom 'Debug/Tutorial.dll' to 'Debug/TutorialD.dll'. We name all the debug versions of the DLLs with an additional 'D', so that no filename clashes will ever appear regarding the fact that the 'Bin\' directory is in the executable path.

under 'Custom Build' tab

For 'Win32 Debug', set:
'Description' to:
Copying $(InputName) binaries to $(ENGINE_DIR)\Bin\Debug
'Commands' to:
copy Debug\$(InputName).dll "$(ENGINE_DIR)\Bin\Debug" >nul
copy Debug\$(InputName).map "$(ENGINE_DIR)\Bin\Debug" >nul
and 'Outputs' to:

For 'Win32 Release', set:
'Description' to:
Copying $(InputName) binaries to $(ENGINE_DIR)\Bin
'Commands' to:
copy Release\$(InputName).dll "$(ENGINE_DIR)\Bin" >nul
copy Release\$(InputName).map "$(ENGINE_DIR)\Bin" >nul
and 'Outputs' to:

This will copy the final '.dll' and its '.map' to the engine directory, after the dll was built.

STEP 3: Adding Precompiled Header Support

Serious Engine has a large number of header files, to gain on compiling speed and simplicity, all of the enigine headers are precompiled together in a single '.pch'. This enables you to just include one file ('StdH.h') in each entity source and you don't need to include any extra headers.

The precompiled header sources should be located in a directory named 'StdH\' in the projects root directory. Create that directory manually using Windows Explorer or similar. Now create files 'StdH.cpp' and 'StdH.h' in that directory and add them to the project.

'StdH.cpp' should contain only one line stating: '#include "StdH.h"'.

For a start, 'StdH.h' should look like this:

#include <Engine\Engine.h>
// include any global headers here
#define DECL_DLL _declspec(dllexport)
// include any local headers here

Later, you will add more headers to the marked places in it.

For example, the 'StdH.h' file for Serious Sam entities is exactly this:

#include <Engine\Engine.h>
#include <Game/SessionProperties.h>

#define DECL_DLL _declspec(dllexport)

#include "..\Global.h"
#include "..\Common\Common.h"
#include "..\Common\Particles.h"
#include "..\Common\GameInterface.h"

Go to Project/Settings again, select the entire project (the project itself, do not multiselect each folder individually!) and select 'C/C++' tab. In 'Precompiled Headers' category, for 'All configurations' select 'Use precompiled header file (.pch)' and type 'StdH.h' in the edit box. Then select just the file 'StdH.cpp' and change its options to 'Create precompiled header file (.pch)' and type 'StdH.h' again.

This way, pch using will be automatically set for all cpp files we will later add to the project, and 'StdH.cpp' will create the .pch file.

In each source file in the project, you will use '#include "StdH.h"'. This will work even if that source file is not in the same directory as the 'StdH.h' file. That enables files from different directories to be compiled with same .pch file.

STEP 4: Making Classes Folder

The entity source files are not .cpp files, they have .es extension and are compiled using Ecc.exe. You should create a new folder for them in the 'Tutorial' project. (In the Project Workspace window, Files tab, right click on the 'Tutorial files' and select 'New Folder'.) Name it 'Classes' and and type 'es' for 'File extensions'.