Mapper Code Templates
From OPU Wiki
This page will tell you how to get started making your own code generation templates for the mapper.
| Table of contents |
What is a Template?
Code generation templates are used by the Mapper to transform the unit data in the editor into valid C++ code.
Templates are simply text files residing in the Mapper application dir with the extension .tpl.
The mapper comes with two templates: Default.tpl and Generic LoS.tpl.
The Default template simply generates a C++ file with a single procedure named SetupObjects. The code can be pasted above your InitProc and the codeSetupObjects();can be inserted into the InitProc to cause the game to generate the units from the mapper.
The Generic LoS template is more or less a complete LoS mission. It contains everything needed for an LoS setup except for disasters or initial units.
However, sometimes these templates might not be enough for your needs. This is where you need to create templates of your own.
How Templates Work
Templates are no more than C++ code files with some special placeholders inserted. These placeholders denote different sections of the file, and are used to substitute different variables into the generated code.
They work very similar to the C/C++ preprocessor but with one exception: they are substituted inside strings.
First of all, templates are split up into different sections of code.
Note: As you read the following, you may wish to open up Default.tpl in a text editor to follow along.
Syntax
Sections and remarks start with two dollar signs ($$) and must be on their own line, with no characters before them. Examples:
$$rem This is a remark! $$begin
Placeholder variables start with one dollar sign, and may be surrounded by other code. Examples:
char MapName[] = "$mapname"; TethysGame::CreateUnit(whatever, $mapid, ...);
Code Sections
The code generator uses different sections to decide what code to insert where. There are eight different possible types of sections in a template, listed below, and the equivalent placeholders in the file:
- Begin File (
$$begin) - Begin Player (
$$player) - Insert Unit (
$$unit) - Insert Beacon (
$$beacon) - Insert Tube/Wall (
$$wall) - Insert Wreck (
$$wreck) - End Player (
$$endplayer) - End File (
$$end)
The code generation system starts reading from the top of the file. At the start, the system is considered to be not in any section at all. Any data entered here is not inserted into the file. However, it is good practice to insert nothing other than remarks into this part, as this may not hold true in future version of the generator.
Descriptions of remarks, as well as each section type follow.
Remarks
Remarks that will not be inserted into generated code can be written using this syntax:
$$rem This is a remark! It won't go in the generated file.
Note: All section and remark lines begin with $$ characters. It is important that no characters appear before the $$ in the file, otherwise it will not be read as a section / remark.
Begin File
The begin file section is designated
$$begin
Code in the begin file section is placed in the generated file at the top (after the comment that the mapper automatically generates). Example uses of this code are to begin a procedure (in the case of Default.tpl), declare variables, etc.
The following placeholders are valid within this section:
-
$totalunits- number indicating the total number of unit/object records -
$playersused- number indicating the number of players 'in use' (players that have units placed for them on the map) -
$template- text indicating the template filename used. -
$mapname- text indicating the map filename used.
more to come later!
