BATTLE FOR TROY
Map Editing Basics


This document is intended to server as a quick guide for starting your own 
"Battle for Troy" mission, and a checklist to use if things aren't 
working.  

We have provided you with four "base" maps inside the "tbd\CustomMaps" 
folder in your install directory.  You will begin by picking one of these 
maps to base yours off of.  Use Windows Explorer, or a command prompt, to 
find this directory on your computer before continuing.  

STEP ONE - Pick a base map to build yours from

The first thing you need to do is pick a setting where your mission will 
take place.  There are four settings available: 

baseCountryside - Sprawling hills and trees, with the occasional farm
baseRuins - Creepy area with old temples and dead 
baseForts - Two large fortresses and surrounding villages
baseTroy - The city of Troy

NOTE: Do NOT edit or delete the files in these folders.  You will make a 
copy of the one you want to use before you start editing.  

For this example, lets use "baseCountryside".  Make a copy of this folder 
and call it "MyMap".  

STEP TWO - Edit the background.kfc script and tell it to use your new 
folder 

Now, you need to enter the "tbd\CustomMaps\MyMap" directory and edit the 
file "Background.kfc".  You can use notepad or any other text editor you 
prefer.  

Inside "Background.kfc" there are a number of places where the original 
"baseCountryside" map folder is used.  You need to change all of these to 
"MyMap".  

So for example, the line:

LOADTBD         CustomMaps\baseCountryside\World.tbd

Should be changed to:

LOADTBD         CustomMaps\MyMap\World.tbd

Do this anywhere you see "baseCountryside", or use the search and replace 
function of your text editor.  

Now, lets build the map and make sure our new map is setup correctly.  

STEP THREE - Using TBDGEN to build your new map

At this point you need to open a Windows "Command Prompt" and enter the 
folder where your map exists.  Assuming you installed the game to the 
default location, you can do this by typing: 

cd "\Program Files\Battle for Troy\tbd\CustomMaps\MyMap"

Once there, type this command:

"\Program Files\Battle for Troy\tbdgen"

Yes, the quotes around it are required.  Remember, this assumes you're 
using the default install directory.  If you installed the game somewhere 
else, adjust accordingly.  

This should run the "tbdgen" program that came with "Battle for Troy".  
This program builds all of the KFC map scripts in the current folder into 
the TBD format that the game actually needs.  Dont worry, we'll go over 
each of these KFC files and what they do in a minute.  

STEP FOUR - Loading your new map

Now you should be able to launch "Battle for Troy" and load your map.  
Lets launch the game in editing mode.  In your command prompt window, 
type: 

"\Program Files\Battle for Troy\Trojan.exe" /h /d

(Alternatively you can launch the 'Battle for Troy - Editing Mode' 
shortcut from the start menu) 

At the main menu, go to "Custom Maps" and see if "MyMap" is listed.  Try 
loading it and see if it comes up.  

If it works, you are ready to move on to STEP FIVE.  If it didnt, go back 
and try steps ONE through FOUR again and see if you can find where you 
went wrong.  

STEP FIVE - Lets Start Editing!  Entering Zonos 'Haus of Editing'

So now we have a brand new map that is ready to be edited.  Always 
remember to run the game with the "/h" option in order to do editing.  

In your level, you'll see that there is one measly Swordsmen on an 
otherwise empty background.  

NOTE: Please keep in mind that there always has to be AT LEAST ONE thing 
on your map, otherwise the editor will not save the map properly.  

Press the 'H' key to enter 'Haus of Editing', Zonos in game editor.  

There are a lot of options in here to play with, but lets stay focused.  
You can come back and mess with all the goodies later.  

STEP SIX - Adding a Unit

Click on '3.  Add Design' (or just press 3).  This will enter the menu for 
adding 'Design' type objects to your map.  A very long list of objects 
will display.  You can mess with these later, but for the moment just drag 
down the slider until you see 'GUnitTrojanArcher'.  Click on it.  

Now the object list will disappear and your mouse cursor will have an 
arrow with the word 'create' under it.  

Anywhere you RIGHT-CLICK on the map now, a Trojan Archer will be created.  
Go ahead and add a single Trojan Archer to the map.  

Now, left click on the Archer to select him.  While hes selected, your 
cursor will have an arrow with the word 'move' under it.  Anywhere you 
RIGHT CLICK now, the Archer will be moved to that spot.  Go ahead and try 
it!  Also notice that you can just hold down the right mouse button and 
the Archer will constantly follow your mouse cursor around the map.  Also, 
try holding down the CONTROL key and moving your mouse left and right, 
notice that your Archer will be rotated around.  

STEP SEVEN - Editing a Unit

Every object within a map has a Player number.

When you add objects to a map, they always arrive the Player # that you 
are currently editing.  Since this was the first thing you did while 
editing this map, this Archer was laid out as 'Player 0', which we dont 
want.  

Units that the player can control should be Player 1, so lets go ahead and 
change this Archer to Player 1.  

With the Archer selected, press 'E' or click on 'Edit' on the Haus menu.

This will bring up a very large list of options that can be edited for the 
selected object.  I will warn you right now that MOST of these values 
should never be touched.  I dont want to discourage you from 
experimenting with them, but be aware that they are likely to have no 
effect on the actual game, or may actually cause your level not to load 
anymore.  For now, dont worry about all the stuff in here; the only thing 
we care about is the very top of the list, where it says 'Player'.  Next 
to it is the value '0'.  

Click in the box where the '0' is.  You may notice that something weird 
happens, like the 0 instantly changes to '03e' or some string of garbage 
characters.  This is a known bug.  Just press backspace to clear all of 
that out, and type in '1'.  

Once youve got the value '1' in there, click on 'Done' at the bottom of 
the screen, or press enter.  

Now our Archer is fighting as a player 1 unit! Good!

NOTE: Any unit you add to this map now will automatically be 'Player 1' 
until you change something to a different player number.  Because of this, 
you can make maps faster if you work on one side at a time.  

NOTE: The player controls Player 1 units.  Player 2 is for enemies.  Other 
player numbers are sometimes used for special things, but you shouldnt 
need to worry about that right now.  

STEP EIGHT - Save your map

Lets go ahead and save our layout with our newly added Archer.

Click on the 'Save Layout' button.

Now, exit the game entirely and go back to your command prompt window. 

Type this command again:

"\Program Files\Battle for Troy\tbdgen"

This should build your map.  Launch the game again, select MyMap from the 
Custom Maps menu, and verify that the Archer you added is there.  

If it isnt, go back a few steps and try to figure out what happened.

NOTE: Always remember to run 'tbdgen' before you run the game and load 
your map.  TBDGEN is what turns your script files into a map that the game 
can use.  If you dont run it, you wont see your changes!  

At this point you have the basic skills needed to start a new custom map 
and add units to it.  Feel free to experiment on your own, or continue 
reading for advanced information.  

ADVANCED EDITING INFORMATION

What you went through above is just the tip of the Iceberg.  Unfortunately 
theres a lot more to go through, and not a lot of time for this Author to 
write up detailed instructions.  

So, very briefly I will attempt to explain the gory details of more 
advanced editing information.  This should be enough to make you 
dangerous, but hopefully allow you to dive in and attempt to make your own 
fully customized missions.  

PART ONE - The Files

Before you get too far into editing, you should know what each file is 
inside a map folder and what it does.  

First of all, there are two main types of files, 'KFC' files, and 'TBD' files.

TBD files are the 'processed', machine code files that the game needs to 
load.  You cannot directly edit these.  They either are premade for you by 
Zono, or they are built from your KFC files with the program 'tbdgen'.  

KFC files are the raw scripts that you can edit, or the game can save via 
Haus of Editing.  These are plain text and I encourage you to load each 
and every one of them into your text editor and get familiar with them.  
ALL the customizations you make are stored in these files.  Lets go 
through each KFC file: 

DesignParams.kfc - This file contains all 'design' type objects that can 
be saved from Haus of Editing.  This includes Tents, Units, Gold, Relics, 
and most anything else the player can interact with directly.  These 
objects are listed on the 'Add Design' menu in Haus of Editing.  
Generally, you do not want to edit this file by hand.  This file is saved 
by Haus of Editing, so if you change it by hand, those changes may be lost 
the next time Haus saves the file.  

LayoutParams.kfc - This file contains all of the "Decor" objects, which 
means things like Trees, Rocks, Buildings, and the like.  Basically, stuff 
the player cant interact with goes in here.  These objects are listed on 
the 'Add Template' menu in Haus of Editing.  Generally, you do not want to 
edit this file by hand.  This file is saved by Haus of Editing, so if you 
change it by hand, those changes may be lost the next time Haus saves the 
file. 

NOTE: Due to the nature of the way "Battle for Troy" maps were created, 
most of the existing "Decor" type objects had their collision painted into 
the map.  This means that if you go in and delete Decor objects, or add 
new ones, it is likely that the game units wont interact with it properly, 
because the original collision will still be there.  Because of this, you 
should probably avoid adding any new Decor objects in places where Decor 
didnt already exist, or it will not work the way you expect.  

NOTE: You should avoid the "Add Layout" option in Haus of Editing.  Most 
of the stuff listed here cannot be added directly to a map, you've bene 
warned.  

HandLayout.kfc - This file is where the missions goals are setup, the 
camera is placed, and other mission specific things are done.  This is 
also the place to put things that you can only edit "by hand" (thus the 
name).  This file is NOT saved by Haus of Editing, it can only be changed 
manually, by you, with a text editor.  

Background.kfc - This file simply tells the game what stuff you want to 
load for this map.  Make sure you change the names of the directories to 
match what your map is called.  Try to use a good, descriptive name, but 
remember you cant have any spaces in the name, or other abnormal 
characters.  

Lighting.kfc - this file is saved by Haus of Editing, and contains any 
lights your map has.  Lighting is a fine art, and I wouldnt recommend 
playing with it unless you feel very daring.  Instead, try just using some 
of the additional lighting scripts provided by changing which file your 
"Background.kfc" loads.  Different lighting schemes are found in each 
'base' map directory.  

PART TWO - Setting up Goals

Other than actually laying out units in Haus, the second biggest aspect of 
creating your own mission is setting up the goals for it.  

Please read the document included with the game called 
TriggersAndActions.rtf for extensive details on all the triggers 
available.  

For this tutorial, well setup a basic 'Kill the Guy' mission - meaning 
the player wins if he kills a certain guy.  

Load up HANDLAYOUT.KFC into your editor, and move down to the end of the 
file.  

First we need to add the guy we want to kill.  Anytime you have a specific 
object that will be involved in a mission goal, you MUST have that object 
in HANDLAYOUT.KFC - so if you added the object with Haus of Editing, and 
thus it was saved in DESIGNPARAMS.KFC, you should load up that file, find 
the object, and cut-n-paste it over here.  

For the time being, well just add an enemy by hand.  Add this to your 
HANDLAYOUT.KFC: 

// This is the enemy Hero that must be killed to win.
// Note that lines of text that start with // are considered comments

LayoutParams BadGuy GunitGreekHero	       // name of the target
{
	Player = 2;			       // what player he is
	float Locator.Position.X = 25.0;       // where he is (x)
	float Locator.Position.Y = 25.0;       // where he is (y)
        char * pName = "The Big Bad Guy";      // text for display
}

What weve done here is added a guy named 'BadGuy' of type 
'GUnitGreekHero' to the map.  He is player 2, and hes located at map 
position 25x25.  Map positions are considered to be starting from the top 
left corner (0,0), and going over (X) and down (Y) to a max of 320x320.  
You can move him wherever you want later, but remember it has to be done 
by HAND.  

NOTE: The actual name of the object, in this case 'BadGuy', MUST be 
unique.  If you try to add another object called 'BadGuy', the level will 
not build, or the game will crash when it loads it.  Be careful about how 
you name things, and be sure to be descriptive.  

So now we have the target for our mission.  What we need now is a trigger, 
and an action.  

A TRIGGER is something that watches the game and looks for something to 
happen.  An ACTION is something that will happen when a TRIGGER 'goes 
off'.  

So in this case, we want a Trigger that watches for our target to die, and 
an Action that lets the player know they won!  

Heres our trigger (explanations of all the other trigger types are in the 
other doc): 

// Trigger to look for death of Badguy - part of the WIN goal
LayoutParams TriggerKillBadGuy GTriggerDeath
{
	CPresetFillData *pOwner = BadGuy;	  // name we gave our target
	char *pTextTriggerOn = "BadGuy is dead!"; // text to display
	CCRC32 ParentList[0] = GoalKillBadGuy;	  // action to result
}

Ok, so first off we just named our trigger, again it has to be a unique 
name.  The type of trigger is 'GTriggerDeath', which is explained in 
greater detail in the other doc.  All you need to know for now is that 
this trigger looks specifically for the death of a unique object within 
the level.  

So within the trigger, the first thing we did is tell it who the target 
is.  Next, we wrote some text that will display within the mission.  This 
is nice for the player to see, but it's also handy for us to be able to 
test our triggers.  

Lastly, we told the Trigger which ACTION is it's parent, specifically 
"GoalKillBadGuy".  This MUST be what the ACTION is named, so lets set that 
up now: 

// Goal that is attached to TriggerKillBadGuy
LayoutParams GoalKillBadGuy GGoalAction
{
        int bStartActive = 1;	           // Active at mission start
        char *pPauseText = "Your goal is to kill the Bad Guy.";
        char *pTextTriggerOn = "The goal is achieved!";	
        CPresetFillData *pLinkGoal = NULL; // there is no 'next goal'		
        CCRC32 ParentList[0] = IWin;       // end mission after this	    
}   

Ok, so there's a lot of stuff here, lets go over it. 

First, we named our ACTION 'GoalKillBadGuy', which must match the goal 
listed in the Trigger.  This is a simple "GGoalAction", which doesnt 
really do anything except watch for the Trigger to go off, display some 
text, and then call the "IWin" action to end the mission.  

Within the action itself, we have a few settings.  First and maybe most 
important is "int bStartActive = 1;" - this means that this action is the 
ACTIVE goal of the mission when the level starts.  At least one Goal must 
be active when the level starts, and if you have multiple goals chained 
together, you'll want to make sure the other goals are not active.  In 
this case, we only have one goal, so we dont need to worry about this, but 
remember that you'll want to set this on the FIRST goal the player needs 
to accomplish.  

The "char *pPauseText = " line is some text that gets displayed in the 
'Objectives' screen the player will see if they hit escacpe.  Typically 
you want to put a nice summary of the mission in here.  You can write 
anything you want, so be creative.  

Next is another TextTriggerOn like we had in our Trigger, and it works the 
same way.  You can put an additional in-game message here, and remember 
it's useful to put something here just so you can test your goal and make 
sure it's actually going off.  

After this, is something odd looking called "CPresetFillData *pLinkGoal = 
NULL;" - what the heck?  Well, this is basically where you would LINK the 
next ACTION if your mission had more than one thing to accomplish.  In 
this case, we're not actually doing anything else after this so we're 
setting this to NULL.  

Lastly, we have another ParentList entry, just like our Trigger, because 
in this case the fact that this ACTION was achieved means we want to 
trigger the end of the mission, which will be with another goal we'll 
setup called "IWin".  

Lets do that now:

// VICTORY
LayoutParams    IWin     GActionWin
{
	int bStartActive = 1;
}

Ok, this is pretty simple.  This is a "GActionWin", and you can pretty 
much bet that every mission you make will have one.  A mission is no fun 
if you cant win!  So all this says is that this Action is active from the 
start of the mission, and thats it.  It basically just causes the mission 
to end in victory.  

Save that out and run "tbdgen" in your map folder and try it out!  

Want a couple of exercises?  Change this mission so that you have kill 
someone else after TheBadGuy is dead, and then you can win.  

Another exercise?  Add a Hero for player 1, called "TheGoodGuy", and make 
it so the player will lose if he dies.  A lose action looks like this: 

LayoutParams ILose GActionLose
{
	int bStartActive		= 1;
}

So now you know how to layout objects in a mission, and setup the goals 
for it.  You're ready to dive in and make your own full blown missions.  
Experiment, have fun, and remember to make backup copies of your files 
often, in case you mess up!  

A FEW PARTING TIPS

Just a few quick nuggets of wisdom to help you out:

1.  Keep it simple!  Dont try to get too complicated too quickly. 

2.  Be able to win and lose, then play the game!  What I mean is, setup 
your goals first, and make sure they work.  Everything after that is just 
making the mission more fun and challenging.  Dont spend a lot of time 
messing around with complicated enemy layouts and waypoint routes until 
you can at least win and lose!  

3.  Keep it simple!  I said that already, but its important so I'm saying 
it again.  If your level is complicated to work on, it's probably 
complicated to play too.  

4.  Comment your scripts.  Use the // tag to add comments all over your 
scripts, in a sense keeping a journal for yourself of just what the heck 
you are doing or trying to do.  Without comments, your scripts will be 
really hard to come back to later and change or finish.  

Have Fun!

-Zono Design Team

