Campaign Cartographer 3+ is a a very configurable and extensible program. In addition to the core program, users can purchase official add-ons, providing not just new artwork, but also new tools. Users can easily add new artwork such as symbols and fills, and many users with an artistic talent create such resources themselves and import into CC3+ for use with their maps. It is also easy for users to create their own drawing tools and organize symbols into symbol catalogs. For the more advanced users, it is possible to customize the menus and toolbars, and write macro commands which can be used to add additional functionality or automate tasks.
But, the most powerful option is the possibility of writing your own add-ons, or XP’s. While you can do a lot with macros, you are still limited to the commands actually provided by CC3+. Clever combinations of these commands can yield interesting results, but sooner or later you will run into things you can’t do. And this is where XP development comes in. By writing your own add-ons for CC3+, you get direct access to the building blocks of your drawing, and can write your own commands for CC3+ to do all kinds of stuff.
In this series of articles I will teach you how to write these add-ons yourself. A word of warning here; these articles will teach you about XP development, but I’ll have to assume you actually know something about programming, and in particular, C++. If you don’t know that, I recommend you find yourself a free C++ tutorial on the internet and start there before coming back, as you will have problems following the tutorials otherwise.

In this first tutorial we’ll look at how to set up your programming environment, as well as making our first code.

Note that you can easily find all the articles published in this series so far by using this link.

About XP Development

The technical term for a CC3+ add-on is an XP (eXtended Procedures). This is a set of new CC3+ command compiled into a library file (.dll) that is copied into the CC3+ installation directory. CC3+ automatically includes these library files on startup, and makes all the commands in them available to the program. For example, City Designer 3 comes with the cd2.dll file which contains all the extra commands from this add-on. Remove this file and commands like the random street command stop existing.
Note that an XP is technically different from an Add-On. An add-on comes with not just new commands, but new artwork, templates, drawing tools and so on. An XP only covers the new commands. So, technically an add-on don’t need to contain an XP at all (like SS1 which is basically only artwork). Likewise, you can make an XP that just adds a few more commands to CC3+, it doesn’t have to come with everything else you see in a fully fledged add-on.

CC3+ is built on the codebase of FastCAD by Evolution Computing, and to some degree, CC3+ itself is actually an XP for this program. So, this way of adding functionality by coding XP’s is inherited from FastCAD, which is something you will encounter in the XP documentation. Note that CC3+ has introduced significant changes in the codebase, and any XP written for CC3+ is unlikely to work with FastCAD, but the core and way of doing things remain the same. Note that XP’s can be written in assembler, C or C++, but I’ll stick to C/C++.

The codebase is directly dependent on the Windows SDK, so some familiarity with this is also helpful.

Setting up your Environment

To develop XP’s for CC3+ you need two pieces of software, the Visual Studio IDE and the XP toolkit. You’ll obviously also need a copy of CC3+ to test your XP. For this tutorial I’ll be using Visual Studio IDE 2022 Community Edition. The community edition is the free version of Visual Studio IDE, and contains everything we need, but if you prefer, you can develop XP’s with any version and edition of visual studio, so if you already have a version installed and feel comfortable with using that, you can safely continue using that. From now on, I’ll just refer to the program as Visual Studio, but all my instructions and screenshots are from the selected 2022 Community version.

Installing Visual Studio

You can download Visual Studio here.

When installing Visual Studio, you will be met by a screen with a lot of different options for what to install. The most important option here is the Desktop development with C++ workload. Along with this, I also recommend the optional feature MSVC v142 – VS 2019 C++ x64/x86 build tools which become available in the list to the right once you select the Desktop development with C++ workload. Make sure the component in my list in the screenshot here matches your installation. Feel free to install additional components, but this should be the minimum.

The MSVC v1.42 optional feature is not strictly required, but it let us build XP’s with the same dependencies that CC3+ already has, ensuring users of your XP doesn’t need to install additional dependencies beyond what’s provided with CC3+ itself. It is also needed if you wish to use my custom CC3+ XP template (see below), which I recommend.

Note that Visual Studio do require quite some space to install, so plan both for a disk use of ~10GB as well as internet bandwidth use for the same size to download the program. Visual Studio don’t come with a full installer you can download somewhere else, it will download the components after you select the desired options in the installer.

Note that when it comes to Visual Studio, I’ll explain in details the required steps to successfully create and build an XP project, but giving a detailed explanation of how everything works in Visual Studio is far beyond the scope of this tutorial. I’ll assume you know your way around Visual Studio, and know how to create an application in it.

Installing the CC3+ XP Template

The CC3+ XP Template is a pre-configured project type for Visual Studio for making XP’s for CC3+. All you have to do is to download the file and then double click on the downloaded vsix (Visual Studio Extension) file. This will bring up a simple installation wizard that will allow you to install the template into Visual Studio 2022. Note that Visual Studio needs to be shut down while installing this, as long as it is running, the installer will just hang on a screen saying it is waiting for tasks to end. Once done, the end screen should clearly say it was successfully installed.

Installing the XP toolkit

You can download the XP toolkit here.

Please unzip this file to the root of your C:-drive, so that you end up with a folder called FCWXP (C:\FCWXP) at the root level, and immediately within it, the Doc, Examples and xpdev folders (see screenshot to the right). While this toolkit technically can live anywhere, the CC3+ XP template is configured to find it here. I highly recommend you keep it at this location to make things easier for yourself, at least for now.

Note that the documentation and examples accompanying this toolkit is very old, but don’t let that discourage you. The actual files needed for creation of XP’s are fully up to date.

Preparing a CC3+ development installation

There are several reasons you should have a dedicated development version of CC3+ set up. First of all, this prevents you from messing up your regular install. Secondly, you need write access to the CC3+ installation directory when working with XP’s. However, Windows allies special protection to everything inside the program files folders, which makes working with that location troublesome. So, we’ll set up a development copy.

This is done very simply by just making a copy of the c:\Program Files(x86)\ProFantasy\CC3Plus directory (I assume you already have CC3+ installed on the computer) and placing the copy at the root of your C:-drive (C:\CC3Plus) (See folder screenshot above). As with the toolkit, this location is coded into the template, so to make it easy for you, please stick to this location for now. Notice that this installation folder is extremely small, so even if you have a tiny C-drive, you’re not going to notice any difference by having the toolkit and CC3+ directory copy here.

There are a few things to remember about your new development installation:

• You can just double click the fcw32.exe file in c:\CC3Plus to start your development installation
• CC3+ has a relationship to the last version you used. So if the last version you used was your development install, then double clicking .fcw (map) files will open in that version, add-ons and updates will install to that version, and so on. To make your regular version  the current one, just manually run it using the shortcut on your desktop or start menu.
• Remember that these installations are separate, they need to be updated separately, and add-ons needs to be installed separately. (I recommend just maintaining the regular version, then just copying it again, overwriting the development version, if you update it or add any add-ons)
• It will share the data directory with your regular install, so no need for a separate copy of that.
• This works only when copying to another location on the same computer CC3+ is installed on. You can’t just copy this directory to another computer, we are taking advantage of the fact that our development install can share resources and settings with a proper CC3+ install here.

Setting up a Project

With all the software ready, we can start by creating a Visual Studio project for our XP. For this tutorial, I’ll be relying on my custom XP template, but there will be a section at the bottom of this article explaining how to set up a project manually and what settings need to be set. You can use this if you don’t want to use my template, or wish to change some of the paths from what I have set up above.

Start by creating a new project in Visual Studio. The easiest way to find my custom XP template is yo just search for CC3 in the search box of the new project dialog

Just select the CC3+ XP project type and hit next. The next screen will ask for a project name and location. Give the project the name “My First XP”, and leave the location as it is, this is the location of the code for the project, not the final XP, so it should NOT go into the CC3+ directory or anything like that.

Once the project have been created and you are into visual studio, the environment may look a bit empty because no files were opened by default. But the project does come with a main.cpp and main.h files that you need, which you can find in the solution explorer (you will need to expand the Source files and Header files nodes). Double click on these to open them into the editor window.

Before we do anything, let us just test our setup. The XP from the template is ready to run, and will work without you writing any code. Just hit the button to start debugging, and Visual Studio should compile your project, copy the .dll it built into the CC3+ development directory, and start that installation for you.

Now, inside CC3+, type XPCFG on the command line (followed by enter). This will bring up the list of installed XP’s. Scroll down until you find your XP in the list (“My First XP”), select it and hit about. You should get this dialog box, indicating that your setup is working and ready to go.

When you close CC3+, the debugging session should automatically stop in Visual Studio as well. It also goes the other way around, if you hit the stop debugging button inside Visual Studio, the running CC3+instance will be closed down.

What if things didn’t work?

Now, it is entirely possible that you didn’t get to the dialog box for one or more reasons. It’s difficult to think of every scenario up up front, but here are are couple of things that might have gone wrong. If these tips don’t help you, please visit the forums and we’ll try to help you out.

• Check your Visual Studio install – It is very important that you have installed AT LEAST the components I show in my screenshot from the installer. You can just re-start the installer to check or add additional components.
• Check the paths for your CC3+ development installation and XP toolkit. The template is set up with the paths described above (C:\FCWXP and C:\CC3Plus), and things will only work correctly if you used those paths.

Our First Command

So, let us make our very first command, just to try things out. We’re just going to make a very simple command that can display that about box directly, instead of going through the XPCFG dialog we did above.

In main.cpp, find these two lines:

char CList[] = "\0";
PCMDPROC PList[] = { About };

and replace them with:

char CList[] = "DEMO\0\0";
PCMDPROC PList[] = { About, About };

Now, start debugging again, and when CC3+ starts up, try to type DEMO (followed by enter) on the CC3+ command line. The about box should show. Now we are ready to go somewhere.

Dissecting the Code

Let us break down the code from the template (main.h and main.cpp) and discuss the important parts of it. Note that this is C++ and I do assume that you have an understanding of this, otherwise you may not fully understand the explanations. I am not going to explain standard C++ concepts here, like how to use header files.

main.h:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

#pragma once

// This gives us access to the Windows API.
#include <windows.h>

// Gives access to custom CC3+ entities. This must be loaded before XP.H
#include <XT_Entities.h>

// Includes the main XP toolkit. This is required when we build an XP
#include "XP.H"

// All XP's have an ID. This is mainly used to identify which XP is responsible for 
// which tools/commands, and isn't terribly important for you. You can pick a random
// number between 0xF000 and 0xFFFF for your XP. The rest of the numbers are reserved
// for registered XP's, don't use those. Note that a conflict with the ID numbers 
// don't have any important consequences UNLESS you are making custom entities, in which
// case it is vitally important that they are unique.
// (Custom entities will be covered later, this is not something you'll create 
// accidentally so don't worry about it for now)
#define XPID 0xF000

// Standard C++ declaration of the About function. Notice XPCALL (which is a macro that
// expands to __stdcall) which is the calling convention for XP functions being used for
// CC3+ commands
void XPCALL About(void);

// Just telling the compiler about our variables.
extern char CList[];
extern PCMDPROC PList[];
extern XP MyXP;

main.cpp:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

#include "Main.h"


// This string defines all the commands this XP provided to CC3+. Each command name
// is null-terminated, and there are also an extra null character at the end of the
// string. Convention dictates we write these in upper case, but when typed inside 
// CC3+ they are not case sensitive.
char CList[] = "DEMO\0\0";

// This array contains function pointers to the functions to use for each command. 
// The functions here are mapped to the commands from the line above. Note that the
// first command here is always the About command for the XP, and this does not have
// an entry in the command list. So technically, the second entry here maps to the
// first entry in the command list, the third to the second in the command list, and
// so on. In this particular example, About appears twice in this example because
// the first entry is the default required about entry, and the second entry is to
// connect the About function to the DEMO command just so we would have a command to
// test. (The default template out of the box doesn't have the second About)
PCMDPROC PList[] = { About, About };

// Instantiates a struct with important values for the XP. You'll notice it references
// the various variables from the lines above. This is a boilerplate line, and will
// always look like this.
XP MyXP = { 0, CList, PList, 0, 0, 0, XPID, 0, 620, 0, 0, 620 };


// This function is boilerplate code that handles the registration and unregistration
// of the dll. These lines will always look exactly like this, and are required.
BOOL WINAPI DllMain(const HINSTANCE hDLL, const DWORD dwReason, LPVOID lpReserved) {
	UNREFERENCED_PARAMETER(lpReserved);

	switch (dwReason)
	{
	case DLL_PROCESS_ATTACH:
		MyXP.ModHdl = hDLL;
		_XPRegCmd(&MyXP);
		break;
	case DLL_PROCESS_DETACH:
		_XPUnregCmd(&MyXP);
		break;
	default:
		break;
	}
	return TRUE;
}


// This is the About function for this XP. It is required for every XP to have an About
// function, and generally, it will always look like this, just with a bit different 
// text. FormSt is simply short for Format String and is the system CC3+ uses to provide
// messages to the user. We'll discuss this in a later article, for now, let us just
// accept it. Note that if you change the text here, do NOT put in an exclamation mark 
// ("!"), as this has special meaning to the FormSt command. CmdEnd() tells CC3+ that 
// the command ends here. This is required, otherwise you will get errors when you start
// the next command.
void XPCALL About() {

	FORMST(MyAPkt, "CC3+ XP Template 2022\n\n"
		"About box for CC3+ XP Template 2022"
	)

	FormSt(&MyAPkt, RSC(FD_MsgBox));
	CmdEnd();
}

Let’s Create

Now that we have discussed how XP’s work, set up the default environment, looked at the template code and built a working XP, let us actually do something ourselves before we end this tutorial.

When adding the code below, I strongly recommend you take the time to type in the code yourself rather than just copy and paste it. Typing it yourself is the best way to notice all the small nuances of how the code is built up.

I won’t explain all the code below in detail, it contain concepts we will be discussing in a later article, but I will provide a few words to help you understand what is going on.

First, at the bottom of your main.cpp file, add this code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

char name[50];

void XPCALL SayHello(const int Result, int Result2, int Result3)
{
	if (Result != X_OK) { CmdEnd(); return; }
	UNREFERENCED_PARAMETER(Result2);
	UNREFERENCED_PARAMETER(Result3);

	FORMSTPKT(MyFPkt, "Hi !01\nHave a Nice Day\0", 1)
		ITEMFMT(name, FT_Stg, FJ_Var, 0, 0)
	FORMSTEND

	FormSt(&MyFPkt, RSC(FD_MsgBox));
	CmdEnd();
}

void XPCALL Demo() {
	FORMST(lpszPrompt, "Your Name:\0")

	RDATA NameReq =
	{ sizeof(RDATA), RD_TxWord, NULL, RDF_C, (DWORD*)& name,
	(DWORD*)& lpszPrompt,RDC_ARROW, SayHello, NULL, NULL, 0, NULL, 0 };

	ReqData(&NameReq);

}

Then, in main.h, find

void XPCALL About(void);

and add this below it

void XPCALL Demo(void);

Finally, in the PList array, replace the second About with Demo, so it looks like this

PCMDPROC PList[] = { About, Demo };

This final change made it so the DEMO command when used in CC3+ now calls our Demo function instead of About. We don’t really need a command to call the about function, but if we wanted to keep it, we could have added the Demo entry after the last About instead of replacing it, as well as adding another command to the CList array above to match it.
Try running the project now, and type DEMO on the CC3+ command line.

The command line will now ask for your name, so type it in (single word only) and hit enter.

Explaining the Code

So, what do the code lines we just wrote mean? I’ll get into some more details in a later article, but lets us give a short overview

line 1: Declare a variable to hold some text. This will be used to carry data between our functions below. We set it up to hold 50 characters. Note that because the way this variable is accessed later, it is easy to put more than 50 characters in it which could cause buffer overrun problems, so always make sure you provide a big enough buffer for the expected input.

line 17-26: This is the function that gets called by our DEMO command

line 18: This prepares a string which contains the prompt we wish CC3+ to give

line 20-22: RDATA is a struct that tells CC3+ how to ask for data, what to ask for and what to do with it. You can see it contains the value RD_TxWord which tells CC3+ the input should be a single word; a reference to our variable name from line 1, this is where it will put the data; a reference to lpszPrompt, the prompt variable we defined on line 18, and SayHello, the function starting on line 3. In short, what will happen here is that it will ask the user to input a text string on the command line, using the prompt text we defined, and when the user provides input, it will be stored in the name variable, and then the function SayHello will be called.

line 24: This is the request data call, and this is what actually tells CC3+ to ask the user for input, using the setup we defined in lines 20-22.

line 3-15: This function will be called to handle the input the user just provided

line 5: Here we check that the appropriate input was received (depending on what we expected), if we didn’t (for example, the user hit esc to terminate the command, or typed text when a number was requested) we terminate the command here. It is important to remember to call CmdEnd() before exiting

line 9-11: Here we set up a text that will be shown in a text box. The interesting part here is the !01 in the text, which says that the first parameter should be inserted here. The parameter itself (the name variable) is defined on line 10, where we also tells CC3+ that this is a string (FT_Stg) (The !01 syntax is why we can’t simply have an exclamation mark in the text)

line 13: Here we use the text output service in CC3+ to display a message box with the text we just set up.

line 14: And finally we tell CC3+ that our command is at an end.

You can download my solution. Note that this assumes default paths.

Manually Configuring Visual Studio

Instead of using my pre-made template, you can also set up Visual Studio yourself. Even if you are using my template, reading through this sections is helpful to understand what my template does.

We need to first create a new library project in Visual Studio, and then manually make some changes to the project settings as well as inserting some basic code required for an XP to function.

Creating the Project

Start Visual Studio, and in the startup dialog, hit the Create a new project button to the right (If you are already inside the IDE, you could click File -> New -> Project instead). This brings up the Create a new project dialog.

We want to start a project using the Windows Desktop Wizard template, using C++ code. You can scroll down in the list, or you can use the search box and filter options on the top to find it. Select it, and hit Next.

On the next screen, give your project a meaningful name, such as My Manual XP. You can also change the location if you prefer.

Finally, the Windows Desktop Project dialog shows. Make sure to select Dynamic Link Library (.dll) as the application type, and also check Empty Project, then leave the rest of the checkboxes empty.

Creating the First Code File

Before we can access all the configuration options, we need our first source code file. In the Solution Explorer pane to the right, right click the Project name (NOT the Solution name) and select Add -> New Item from the context menu. In the dialog that shows, pick C++ File (.cpp) and give it a decent name, such as Main.cpp before hitting the Add button.

This will create a new blank code file. We’ll add code to it shortly.

Configuring the Project

First of all, make sure the dropdown on the top toolbar is set to x86 and not x64. CC3+ itself is a 32-bit application, and our XP’s need to be too. if this is set to x64, you’re going to get all kinds of errors as we proceed.

Before we can start creating our XP, we need to tell Visual Studio where the files for the XP toolkit is. We’ll also need to change a few other options to make Visual Studio understand which kind of C++ code we are writing. C++ is a very powerful language, but with that comes a cost, it is possible to do things that other programing languages won’t allow you to do for safety reasons. Modern C++ tries to prevent developers from using some of these features, because if you don’t know what you are doing, you can quickly run into serious issues. However, the FastCAD engine do use a lot of these features, because it also allows for faster and more efficient code. As a result, we must tell Visual Studio that we are writing code that depends on these features and we need to be allowed to do so.

Right click the project name in the Solution Explorer and choose Properties. In the Property dialog that shows, make sure to first set the Configuration dropdown in the top left to All Configurations, and also make sure Platform is Active(Win32) (or just Win32). Visual Studio allows us to set different options for Debug builds and Release builds of our application, but the options we set now should apply to both.

These are the options you need to set

Template Code

Finally, we can put in the template code. Paste this into the empty code file (Main.cpp) you made earlier.

#include <windows.h>
#include "XP.H"

#define XPID 0xF000

void XPCALL About(void);

char CList[] = "DEMO\0\0";
PCMDPROC PList[] = { About, About };

XP MyXP = { 0, CList, PList, 0, 0, 0, XPID, 0, 620, 0, 0, 620 };

/////////////  DllMain - XP initialization & Unload code //////////////
BOOL WINAPI DllMain(const HINSTANCE hDLL, const DWORD dwReason, LPVOID lpReserved) {
	UNREFERENCED_PARAMETER(lpReserved);

	switch (dwReason)
	{
	case DLL_PROCESS_ATTACH:
		MyXP.ModHdl = hDLL;
		_XPRegCmd(&MyXP);
		break;
	case DLL_PROCESS_DETACH:
		_XPUnregCmd(&MyXP);
		break;
	default:
		break;
	}
	return TRUE;
}

void XPCALL About() {

	FORMST(MyAPkt, "My XP\n\n"
		"This is my XP. You should make your own"
	)

		FormSt(&MyAPkt, RSC(FD_MsgBox));
	CmdEnd();
}

Testing

Our XP project should now be configured properly, and we can build our first XP. It won’t do much yet, but it will work.

It is important that we build our new XP as a 32-bit library, so make sure the dropdown on the toolbar is set to x86 and not x64 before you proceed.

In Visual Studio, select Build Solution from the Build menu. Assuming the build succeeds (If not, check the project setup details we just went through) you now have a working .dll file for your XP.

Copy this .dll file (you’ll find it in the solution directory, easiest way to go there is to right click the solution in the solution explorer window, and select Open Folder in File Explorer. The .dll should have the same name as your project, and should be in the Debug directory at that location) to your CC3+ installation directory (C:\CC3Plus if you followed the instructions earlier).

Now start CC3+ and type DEMO at the command line. You should get a dialog box showing with the text from line 34-35 in the code above. Assuming this worked, you have just built a functional XP. It doesn’t do much yet, but it works!
Remember that you must start CC3+ AFTER copying in the library file. CC3+ won’t pick up on files being copied into the directory while running.

You can also check that CC3+ loaded your XP by typing XPCFG on the command line and look at the list of XP’s. Theoretically you should be able to choose your .dll in the list and hit About to see the result of the about function for that particular XP, but a small bug have resulted in the button calling the wrong XP. You should normally be able to get the about response from your XP by trying to select the XP a few positions above however.

Easier Testing and Debugging

You may remember from above that my custom template automatically copied the file to the CC3+ directory, and started CC3+ when you started debuggin. This is a lot faster than copying the file yourself each time, so let us set this up as well.

In the project properties under Build Events -> Post-Build Event, set Command line to
copy "$(OutDir)$(TargetName)$(TargetExt)" c:\cc3plus\

This will cause Visual Studio to copy the .dll it built to the CC3plus directory, assuming the build was successful.

Then, on the debugging category, set the Command option to your CC3+ executable (C:\cc3plus\fcw32.exe if you followed my example). Once you have done this, hitting the start debug button will build the .dll, then copy it automatically into the CC3+ installation directory, and CC3+ will start, ready to test your commands. Now you can easily use breakpoints, memory profiling and all the other tools of Visual Studio with your XP for a proper debugging experience.

Help and Discussions

The ProFantasy Community Forum has a dedicated category for Macros and XPs. I recommend you post any questions you may have over here. Comments on this blog entry is not a good place to get help, in part because I don’t get alerted when new comments are posted, and I don’t go around checking old posts for comments.