wb scenario and custom game

CopyRight © 2011 - All Rights Reserved

World Builder Scenario

and

Custom Game Tutorial

Version: 1.0

Status: Draft

Date: 14 July 2011

Author: William Howard


Contents Introduction ............................................................................................................................................ 5

Assumptions ........................................................................................................................................ 5

Compatibility ....................................................................................................................................... 5

Creating a World Builder Scenario Map ................................................................................................. 6

Create a Map ....................................................................................................................................... 6

Start World Builder ............................................................................................................................. 6

Add Civilizations .................................................................................................................................. 7

Set Starting Techs and Policies ........................................................................................................... 9

Add City States .................................................................................................................................. 10

Place Civilization Starting Cities ........................................................................................................ 10

Place Civilization Starting Units......................................................................................................... 12

Add Palaces to Capital Cities ............................................................................................................. 14

Place City States ................................................................................................................................ 15

Set Scenario Properties ..................................................................................................................... 16

Save World Builder Scenario Map .................................................................................................... 16

Playing a World Builder Scenario Map.................................................................................................. 16

Start Civilization ................................................................................................................................ 16

Navigate to Advanced Setup Menu .................................................................................................. 17

Select the WB Scenario Map ............................................................................................................. 18

Select the Civilization to Play ............................................................................................................ 19

Start the Scenario.............................................................................................................................. 20

Play the Scenario ............................................................................................................................... 20

Changing a WB Scenario Map into a WB Scenario Mod ....................................................................... 21

Create a New Mod ............................................................................................................................ 21

Add the WB Scenario Map ................................................................................................................ 22

Set the Mod Properties ..................................................................................................................... 24

Delete the Saved WB Scenario Map ................................................................................................. 25

Build the WB Scenario Mod .............................................................................................................. 25

Playing a World Builder Scenario Mod ................................................................................................. 26


Navigate to Mods Menu ................................................................................................................... 26

Enable the WB Scenario Mod ........................................................................................................... 27

Select the WB Scenario Map ............................................................................................................. 27


Start the Scenario.............................................................................................................................. 29

Uploading a World Builder Scenario Mod ............................................................................................ 30

Upload with ModBuddy .................................................................................................................... 30

Components of a Custom Game ........................................................................................................... 30

Custom Game Menu ......................................................................................................................... 31

Custom Game Menu Entry ................................................................................................................ 31

Configuration Screen ........................................................................................................................ 32

Victory Progress Panel ...................................................................................................................... 32

Changing a WB Scenario Mod into a WB Custom Game ...................................................................... 33

Download, Install and Enable the “Traders Scenario” ...................................................................... 33

Confirm Operation of the “Traders Scenario” .................................................................................. 33

Open WB Scenario Mod .................................................................................................................... 36

Import Files from Traders Scenario .................................................................................................. 37

Set VFS Imports ................................................................................................................................. 39

Add Required Properties ................................................................................................................... 39

Set Required Option .......................................................................................................................... 40

Add Required Actions ....................................................................................................................... 40

Add Required Content ...................................................................................................................... 40

Edit Scenario Text ............................................................................................................................. 41

Edit Scenario Parameters .................................................................................................................. 41

Edit Scenario Background Graphic .................................................................................................... 43

Edit Scenario Initialisation................................................................................................................. 43

Edit Scenario Victory Progress .......................................................................................................... 44

Files Not To Edit ................................................................................................................................ 45

Build & Test WB Custom Game Mod ................................................................................................ 45

Playing a WB Custom Game .................................................................................................................. 47


Enable the WB Custom Game Mod .................................................................................................. 47

Select the Custom Game ................................................................................................................... 48

Start the Custom Game..................................................................................................................... 50

Check the Victory Progress Display ................................................................................................... 50

Extending the Game – Difficulty Selection ........................................................................................... 51

Start ModBuddy ................................................................................................................................ 51

Add Difficulty Options ....................................................................................................................... 51


View Changes .................................................................................................................................... 51

Extending the Game – Adding a Map Script ......................................................................................... 52

Start ModBuddy ................................................................................................................................ 52

Add a Map Script ............................................................................................................................... 52

Add Additional Scenario Parameters ................................................................................................ 53

Add Additional Scenario Initialisation ............................................................................................... 53

Add Initial Civilization Technologies ................................................................................................. 53

View Changes .................................................................................................................................... 54

Extending the Game – AI Only Civilizations .......................................................................................... 55

Start ModBuddy ................................................................................................................................ 55

Define the Playable Civilization(s) ..................................................................................................... 56

Define the AI Civilization(s) ............................................................................................................... 56

View Changes .................................................................................................................................... 56

Conclusion ............................................................................................................................................. 57


Introduction The goal of this tutorial is to enable you to be able to create Custom Games from World Builder

maps and/or map scripts such that they can be played from the Custom Game menu.

The tutorial starts by showing you how to create (and play) a World Builder Map Scenario, with

simple to follow, step-by-step instructions.

The tutorial then proceeds to show you how to convert the scenario into a mod, such that it can be

shared with other players by means of the ModHub. Instructions on how to play the scenario as a

mod are also given.

The tutorial then shows you how to convert the scenario mod into a custom game mod (using pre-

built components) and instructions on how to start the custom game are also given.

Finally, the tutorial shows you how to use the pre-built components to enable and/or disable key

features of configuring a custom game – civilization, map and difficulty selection.

By the end of the tutorial you will have a fully working, configurable, custom game based on both a

World Builder created map and a standard map script.

Assumptions This tutorial assumes that you:

Understand the basics of XML, SQL and Lua

Know how to download, install and enable a mod from the in-game ModHub

Have the Civilization V SDK installed

Know how to use ModBuddy to create and deploy a simple mod

Have the debug logs enabled, know where they are and know how to look for errors in them

(specifically database.log, lua.log and xml.log)

Know how to use LiveTuner (FireTuner) to test and debug a mod

Know how to use World Builder to create a map

Know how to upload a mod to the ModHub

(Optional) Know how to create .dds format images

Compatibility This tutorial was written with Civilization V 1.0.1.332 and also tested with 1.0.1.348


Creating a World Builder Scenario Map In this section we will create a simple World Builder Scenario called “Island Raiders”. The aim of the

scenario is to conquer the other civilisations on the map.

Create a Map The first step is to create the map. This can either be done by saving a map from the main

Civilization game or by creating one in World Builder - either by running one of the standard scripts

or by hand-crafting all the land-masses and adding features and resources. The map should be

created at standard size (80x52) and feature lots of islands.

Start World Builder Start World Builder and either open your saved map or create the new map.

From the Description tab, change the map name to Island Raiders (Civ5Map)


and save the map as IslandRaiders.Civ5Map

Add Civilizations We now need to add some civilizations to select from to play as. Open the Scenario Editor from the

Scenario Editor tab.


Add three Players – English, Ottoman and Songhai – by clicking the + button on the Players tab and

then using the Civilization drop-down to select the required civilizations.


Set Starting Techs and Policies As this is an island based scenario, we are going to give each Civilization the Sailing technology to

start with. However, as this technology requires Pottery, we must also give each civilization this as

well.

Select the first player and click the Edit Techs button in the bottom right hand corner. In the pop-up

tech editor select Agriculture, Pottery and Sailing, then close the pop-up window. Repeat this for

the other two players.

To “jump-start” the game we are also going to give each player one starting Policy, a different one

for each player. Select the first player and click the Edit Policies button at the bottom centre of the

scenario editor dialog. Assign this player the Tradition policy, then close the pop-up window.

Give the second player the Liberty policy and the third the Honor policy.


Add City States We now need to add some city states. Click the City States tab and then click the + button twelve

times

Close the Scenario Editor dialog

Place Civilization Starting Cities We now need to place the capital for each major civilization. Select a good coastal location on the

map.


Click the Cities tab in the Map Editor Tools panel, ensure Create is selected and that Player 1 is

showing in the drop-down menu, then click the tile on the map where the capital is to be placed.

On a different island, locate another starting coastal plot, change the drop-down to Player 2 and

click on the tile


Finally locate the third starting coastal plot on another island, change the drop-down to Player 3 and

click on the tile

Place Civilization Starting Units We now need to place some initial units. Locate Player 1’s capital, click the Units tab, ensure Create

is selected, change the top drop-down to Warrior and the bottom drop-down to Player 1 and click

on a tile next to the capital to place a Warrior.


Change the top drop-down to Trireme and click on a coastal tile next to the capital to place a starting

ship.

Place a warrior and trireme for each of the other two players


Add Palaces to Capital Cities In a random map game, the first city founded is automatically created as the capital as the Palace is

added to it. We need to do the same for the capital cities we have just added. Click the Cities tab,

ensure that the Edit option is selected and then click on London. Click the Select Buildings button,

scroll the list of buildings down and select Palace.

Close the pop-up window and repeat for the other two capital cities.


Place City States We now need to place all the city states. Check the World View to see the full map, and click the

Cities tab. Ensure that Create is selected and change the drop-down to the first city state.

Locate a starting position on the map and click the tile to place the city state. Repeat for all twelve

city states, aiming for coastal locations well distributed across the map and available land-masses.


Set Scenario Properties We now need to set the scenario properties. Open the Scenario Editor again, set the Default Speed

to Standard, the start year to 4000BC, MaxTurns to 200, and check the Domination Victory Type.

Close the scenario editor dialog

Save World Builder Scenario Map Save the map and close World Builder.

Playing a World Builder Scenario Map This section gives step-by-step instructions on how to play the WB Scenario Map created in the

previous section.

Start Civilization Start Civilization and select Mods from the Main Menu


Navigate to Advanced Setup Menu Select Single Player

Then Setup Game and Advanced Setup


Select the WB Scenario Map From the Map Type drop-down menu select the Island Raiders (Civ5Map) entry

Ignore all other items and click the Back button (do NOT click the Start Game button!)


On the Setup Screen, check the Load Scenario button

Select the Civilization to Play Select a Civilization to play


Start the Scenario Select a difficulty and then click the Start Scenario button

Play the Scenario Finally play your scenario. You will need to “know” what the premise and victory conditions are.

(Note that the Sailing technology has already been completed.)


Changing a WB Scenario Map into a WB Scenario Mod Now you have a working WB Scenario Map - but it’s only available on your computer. So how do

you “publish” it? To do this you need to convert it to a Mod and upload it to the ModHub for other

players to download from there.

Create a New Mod Start ModBuddy and select “New Mod …”

Enter the name of the mod – in this case “IslandRaidersScenario” – and click the OK button.


Complete the required General Information and click the Finish button.

Add the WB Scenario Map From the Solution Explorer window at the top of the right-hand frame, right-click the scenario name


Select “Add” and then “New Folder”. Give the new folder a name of “MAPS” (it will be a lot easier to

follow the tutorial if you keep this in all capitals)

Right click on the MAPS folder, select “Add” and then “Existing Item …” Using the file browser dialog

that opens, navigate into your “…\My Documents\My Games\Sid Meier's Civilization 5\Maps” sub-

directory and select the IslandRaiders.Civ5Map file and click the Add button.

Now click on the IslandRaiders.Civ5Map file in the Solution Explorer window, and down at the

bottom change the “Import into VFS” drop-down to “True”


Set the Mod Properties We now need to add some properties to the mod, so right-click on the IslandRaidersScenario entry

in the Solution Explorer window and select “Properties” to open the mod’s properties screen.

Scroll to the bottom and uncheck the “Affects Saved Games” option.

Click on the Content tab (bottom of the left-hand tabs). Create a new row with a Type of “Map”, a

Name of “Island Raiders”, a description of “Island Raiders Scenario” and a FileName of

“MAPS/IslandRaiders.Civ5Map”.

Important!

1. Both Type and FileName are case sensitive – so “Map” not “map” or “MAP” and

“MAPS/IslandRaiders.Civ5Map” not “maps/islandraiders.civ5map” etc.

2. The type of the slash in the file name is critical – so “MAPS/IslandRaiders.Civ5Map” not

“MAPS\IslandRaiders.Civ5Map”


Delete the Saved WB Scenario Map With the map file loaded into the mod we need to delete it from the “…\My Documents\My

Games\Sid Meier's Civilization 5\Maps” sub-directory.

If we don’t delete the map file from here, Civilization will detect it both from the enabled mod and

from this location so there will be two entries on our map selection list (which will be confusing).

Build the WB Scenario Mod The final task is to build and deploy the mod. Make sure all files are saved, and then from the main

“Build” menu select “Build IslandRaidersScenario”. Confirm that the “Output” window (bottom

frame) reports success and that there are no errors on given in the “Error List” tab.

The build process also deployed the mod to your copy of Civilization.


Playing a World Builder Scenario Mod This section gives step-by-step instructions on how to play the WB Scenario Mod created in the

previous section.


Navigate to Mods Menu Select Browse Mods


Enable the WB Scenario Mod Locate the Island Raiders Scenario mod and enable it (check box will be highlighted in green), then

click the Back button

Select the WB Scenario Map Select Single Player


Then Setup Game and Advanced Setup

From the Map Type drop-down menu select the Island Raiders entry

Note 1: If you have an “Island Raiders (Civ5Map)” entry, you need to delete the map from your Maps

sub-directory (see above).

Note 2: If you have no “Island Raiders” entry you either forgot to set VFS to true, or have made a

mistake with the capitalisation of the file name and/or used the wrong slash in the path

Ignore all other items and click the Back button (do NOT click the Start Game button!)


Start the Scenario On the Setup Screen, check the Load Scenario button, select a civilization and a difficulty, and then

click the Start Scenario button

Finally play your scenario. You will need to "know" what the premise and victory conditions are.


Uploading a World Builder Scenario Mod With your World Builder Scenario map now converted into a mod, you can upload it to the ModHub

to share with other players.

Upload with ModBuddy Mods are uploaded with ModBuddy. The procedure is not covered in this tutorial as there are many

on-line forum posts giving details on how to do this.

For a step-by-step pictorial guide see

http://www.flickr.com/photos/whoward69/sets/72157626685088090/

Components of a Custom Game We have now seen how to create a World Builder Scenario as a Mod such that it can be uploaded to

the ModHub for other players to download and enjoy. While the mod contains information about

the premise and goals of the scenario, this information is not available to the user during setup or

while playing the scenario. Also, the standard setup process (select the map, click back, check the

load scenario button, etc) is not intuitive.

Compare that to the scenario that comes as part of the free Mongol down-loadable content (DLC).

Once the DLC is enabled, a Custom Game option is available on the Single Player menu. From there

you can see information about the scenario, easily choose set-up options and commence the

scenario.

Once in the scenario, your victory progress is displayed at the top of the screen and you can get the

scenario description back up at the click of the Briefing button.

The next section will show you how to add all these features to the Island Raiders Scenario, but first

we will take a look at the four key components of a Custom Game in detail.

http://www.flickr.com/photos/whoward69/sets/72157626685088090/


Custom Game Menu The first component of a Custom Game is to get the “Custom Game” option enabled on the Single

Player (Mods) menu

It turns out that the code that displays this option detects if a mod adds an item for the second

component of a custom game (see the following screen grab) and automatically enables/disables

this option. So we don’t need to do anything to make this work, provided our mod adds a valid entry

for the next screen.

Custom Game Menu Entry The second component of a custom game is to add an entry to the “Custom Game” selection screen

This is actually quite simple to achieve, it just requires the correct entries in the .modinfo file (added

via ModBuddy of course), but there are a few pitfalls to avoid and some corresponding “tricks” to

use.


Configuration Screen The third component of a custom game is a bespoke configuration screen

The definition of the layout of this dialog (an XML file) and the code that drives it is non-trivial.

Victory Progress Panel The last component of a custom game is the in-game victory panel

The definition of the layout of this dialog (an XML file) follows a standard template and is quite

simple. The complexity of code (an Lua file) that drives it is determined by the victory conditions of

the scenario.


Changing a WB Scenario Mod into a WB Custom Game This section will show you how to convert the Island Raiders World Builder Scenario Mod into a

Custom Game Mod.

We could do this by writing all the necessary XML, SQL and Lua files from scratch but that would be

error prone and not very re-usable. Fortunately, in good “Blue Peter” fashion, we can use one I have

prepared earlier just for this purpose!

Download, Install and Enable the “Traders Scenario” I have created a “Traders Scenario” custom game mod which can be used as a template for other

custom games. It is both modular and auto-adaptive, meaning that aspects of the set-up screen are

shown or hidden depending on what options are set.

Using the ModHub, locate, download and install the TradersScenario mod.

Confirm Operation of the “Traders Scenario” Before proceeding it is advisable to confirm that the vanilla Traders Scenario is working (because if it

isn’t there is no chance anything that follows in this tutorial will work!)

Start Civilisation, navigate into the Mods menu, select Browse Mods, enable the TradersScenario

mod and then click Back to return to the Mods menu. Select the Single Player option. If all is

installed correctly, you will now have a Custom Game option.

Select Custom Game


Select the Coastal Traders item (note how the description of the scenario – along with the

background image - changes in the right hand frame) and then click “Load Mod”

Select a leader, map type and difficulty and then click “Start Game”


The game will start and display a victory progress banner. The number of luxuries acquired will be

zero and the number required will depend on your chosen difficulty (Chieftain requires nine, while

Deity requires all fifteen)

Found your capital (if playing on a random map), build a Worker, pick the tech that will be needed to

develop your nearest luxury (Calendar in this case). Explore a bit. When the tech is researched and

the worker built, get the worker to improve the luxury tile. When the improvement is built (a

plantation in this case) confirm that the victory banner updates.


We could play the game to its conclusion, but that’s sufficient to show that the vanilla game is

working!

We now want to modify our Island Raiders scenario mod to include the custom game components.

Open WB Scenario Mod Start ModBuddy and open the Island Raiders Scenario mod

As we no longer want the World Builder map to be playable from the Advanced Setup menu, change

the VFS Import for the Islandraiders.Civ5Map file to false

and delete the Map entry on the Content tab


Import Files from Traders Scenario We now need to copy all the files from the Traders Scenario that we need - this isn’t all of them so

pay close attention!

Add an ART folder to the IslandRaidersScenario project and import the Scenario_Background.dds file

from the “…\My Documents\My Games\Sid Meier's Civilization 5\MODS\TradersScenario (v 1)\ART”

sub-directory. (This file is the image that is displayed behind the scenario briefing on the choose

Custom Game screen.)

Add an LUA folder to the IslandRaidersScenario project and import the three files

ScenarioUtilities.lua, ScenarioInitialisation.lua and ScenarioParameters.lua (the Add Existing Item file

selection dialog supports multiple select, so these can all be selected and added at the same time)


Add an SQL folder to the IslandRaidersScenario project and import the ScenarioText.sql file

Add a UI folder to the project and import the four files ScenarioLoadScreen.lua,

ScenarioLoadScreen.xml, ScenarioVictoryProgress.lua and ScenarioVictoryProgress.xml

Finally add an XML folder to the project and import the ScenarioParameters.xml and

ScenarioText.xml files


The final list of files should look like

Set VFS Imports We now need to set the “Import into VFS” option to true for required files. For the following files

(and only those files) set VFS to true, all others should remain at the default of false

ART/Scenario_Background.dds

LUA/ScenarioInitialisation.lua

LUA/ScenarioParameters.lua

LUA/ScenarioUtilities.lua

Add Required Properties We now need to set a custom property for the mod. Click the Custom Properties tab and enter

“Custom_Background_TXT_KEY_SCENARIO_TITLE” as the name and

“ART/Scenario_Background.dds” as the value (without the enclosing double quotes). Case and type

of slashes is significant!


Set Required Option Click the Mod Info tab, scroll to the bottom, and check the “Hide ‘Setup Game’” option.

Add Required Actions We now need to add actions to execute the sql and xml to update the database. The order of these

files is important, so add them in the following order. Again, case and type of slashes is significant!

XML/ScenarioText.xml

SQL/ScenarioText.sql

XML/ScenarioParameters.xml

Add Required Content We now need to add content to be loaded. The order of these files is not important, but once again

case and type of slashes is significant!

Custom UI/ScenarioLoadScreen.xml

InGameUIAddin LUA/ScenarioInitialisation.lua

InGameUIAddin UI/ScenarioVictoryProgress.xml

Important Note: The Name and Description fields for the Custom entry must be

“TXT_KEY_SCENARIO_TITLE” and “TXT_KEY_SCENARIO_DESC” respectively.

Why the TXT_KEY_ entries? The Name field of the Custom entry is prefixed by

“Custom_Background_” and used as the tag name to locate the background image. XML tags may

only contain a limited sub-set of characters and excludes most of the punctuation and also space.

This means a Name of “William’s Island Raiders Scenario” is not valid. However, by using a

TXT_KEY_ value for the name, we can conform to the requirements of XML while being able to use

any characters in the displayed name as the TXT_KEY_ entry is automatically translated via the game

database.

Note: If you don’t want the victory progress banner, simply omit the InGameUIAddin entry for it.


Edit Scenario Text While on the subject of the scenario name, open the “XML/ ScenarioText.xml” file and change the TXT_KEY_SCENARIO_TITLE, TXT_KEY_SCENARIO_DESC, TXT_KEY_SCENARIO_RANDOM_MAP, TXT_KEY_SCENARIO_FIXED_MAP and TXT_KEY_SCENARIO_BRIEFING_TEXT entries to match the goals of the scenario. (Do not change the name of the tags, just the text!)

Delete the Row entry with tag TXT_KEY_SCENARIO_VICTORY_PROGRESS as it is not needed by the Island Raiders custom game. Save the changes and close the file.

Edit Scenario Parameters Open the “LUA/ScenarioParameters.lua” file. This is the “brains” of the auto-adaptive template.

Adding or removing values in this file, determines which parts of the Custom Game setup dialog are

visible.

The most important piece of information required is the ModId. This value is different for every

mod, so the value you see in your ModBuddy will not be the value shown in these screen grabs! The

ModId is displayed at the top of the ModInfo tab and can be copied from here.

Copy the ModId and paste it into the ScenarioParameters.lua file


The next four entries relate to the maps used in the scenario, but only the first is relevant for a

World Builder Civ5Map file. Change the ScenarioFixedMap entry to refer to the

IslandRaiders.Civ5Map file and “comment out” (by prefixing the lines with --) the next three entries

(we will need these again later in the tutorial). As usual, case and the type of slashes is very

important.

The next block of lines refer to the civilizations we either defined in our World Builder Scenario Map

or wish to play on a random map. As we defined three civilizations when we created the World

Builder Scenario Map (all those pages ago), we need to delete the last entry and change the others

to reflect our chosen civilizations. (The correct values to use in this table can be found in the

CIV5Civilizations.xml core game file.)

If you wish, specify a default civilisation to play, otherwise leave the ScenarioDefaultCivilization set to nil to pick a random civilization to start with (this can be changed by the player from the Custom Game setup screen). The next block of lines refer to the difficulties the player can choose from. To illustrate the auto-adaptive dialog we are going to comment these out for the time being and force the difficulty to be King. We will later return and add these back in to see the effect of them on the Custom Game dialog. So, for the moment, comment these lines out.


The next block of lines refers to the possible victory types. As our scenario will be turn limited, we could just ignore these, but by picking appropriate ones here the AI stands a better chance of playing to win! For our scenario, we only need domination, so set that to true and all the others to false.

The next line relates to the game speed, pick an appropriate one. For the Island Raiders scenario either “GAMESPEED_QUICK” or “GAMESPEED_STANDARD” is suitable. The last line relates to the number of turns the scenario will run for. If there is no turn limit, leave this at zero, but for our Island Raiders scenario we need to change this to 200. (This should be the same as that set in the World Builder Scenario Dialog.)

Save the changes and close the file.

Edit Scenario Background Graphic The ART/Scenario_Background.dds file is displayed as the background to the scenario briefing in the

Custom Game selection menu. Either edit the ART/Scenario_Background.dds file or create a new

one and add it to the mod project. If you change the name, you will need to change the custom

property value added above. If you have the Viking/Denmark DLC you can use the background that

comes with that scenario.

Edit Scenario Initialisation Open the file LUA/ScenarioInitialisation.lua. This file controls what happens as the scenario starts

(initialises). For a World Builder Scenario Map based game, no initialisation is required (as all cities,

units, techs, policies, etc are allocated via the World Builder Scenario Editor.

We could delete everything in this file, but the framework is useful to keep, so we’ll just remove the

code we don’t need.


Locate the InitPlayer(pPlayer) function and delete the block of four lines in the middle (we’ll keep

the allocation of 50 gold to each player)


Edit Scenario Victory Progress Almost there! Just need to change the Victory Progress banner to match our winning conditions.

Open the file UI/ScenarioVictoryProgress.lua. This file controls what is displayed in the Victory

Progress banner and has the logic to decide if we have won or lost.

In the Island Raiders scenario we win if we are the last man standing and we lose if we run out of

turns. As “last man standing” is a common victory condition it is already handled. As “out of turns”

is a common lose condition it is also already handled. So all we need to do is remove the “luxury

based victory” code and change the displayed message.

Delete the block of code starting at the “-- Loop through all the Majors checking for a luxury based

victory” comment, delete the line immediately after the “-- Update the victory progress banner”

comment and uncomment the second line (the one that references

“TXT_KEY_SCENARIO_TURNS_AND_OPPONENTS_REMAINING”



Files Not To Edit The following files should not need editing under normal circumstances

UI/ScenarioLoadScreen.lua

UI/ScenarioLoadScreen.xml

UI/ScenarioVictoryProgress.xml

SQL/ScenarioText.sql

LUA/ScenarioUtilities.lua

XML/ ScenarioParameters.xml

Build & Test WB Custom Game Mod Make sure all files are saved and then from the main “Build” menu select “Build Solution” – this will

build and deploy the mod. Check for any errors listed on the Error List tab.

Check that the “…\My Documents\My Games\Sid Meier's Civilization 5\MODS\IslandRaidersScenario

(v 1)” folder has been created. Check that it contains the following files

IslandRaidersScenario (v 1).modinfo

ART\Scenario_Background.dds

LUA\ScenarioInitialisation.lua

LUA\ScenarioParameters.lua

LUA\ScenarioUtilities.lua

MAPS\IslandRaiders.Civ5Map

SQL\ScenarioText.sql

UI\ScenarioLoadScreen.lua

UI\ScenarioLoadScreen.xml

UI\ScenarioVictoryProgress.lua

UI\ScenarioVictoryProgress.xml

XML\ ScenarioParameters.xml

XML\ScenarioText.xml


Check that the .modinfo file looks like the following

<Mod id="…" version="1">

<Properties>

<Name>…</Name>

<Teaser>…</Teaser>

<Description>…</Description>

<HideSetupGame>0</HideSetupGame>

<AffectsSavedGames>0</AffectsSavedGames>

<SupportsSinglePlayer>1</SupportsSinglePlayer>

<SupportsMultiplayer>1</SupportsMultiplayer>

<SupportsMac>1</SupportsMac>

<ReloadLandmarkSystem>0</ReloadLandmarkSystem>

<ReloadStrategicViewSystem>0</ReloadStrategicViewSystem>

<ReloadUnitSystem>0</ReloadUnitSystem>

<Custom_Background_TXT_KEY_SCENARIO_TITLE>

ART/Scenario_Background.dds</Custom_Background_TXT_KEY_SCENARIO_TITLE>

</Properties>

<Files>

<File md5="…" import="1">ART/Scenario_Background.dds</File>

<File md5="…" import="1">LUA/ScenarioInitialisation.lua</File>

<File md5="…" import="1">LUA/ScenarioParameters.lua</File>

<File md5="…" import="1">LUA/ScenarioUtilities.lua</File>

<File md5="…" import="0">MAPS/IslandRaiders.Civ5Map</File>

<File md5="…" import="0">SQL/ScenarioText.sql</File>

<File md5="…" import="0">UI/ScenarioLoadScreen.lua</File>

<File md5="…" import="0">UI/ScenarioLoadScreen.xml</File>

<File md5="…" import="0">UI/ScenarioVictoryProgress.lua</File>

<File md5="…" import="0">UI/ScenarioVictoryProgress.xml</File>

<File md5="…" import="0">XML/ScenarioParameters.xml</File>

<File md5="…" import="0">XML/ScenarioText.xml</File>

</Files>

<Actions>

<OnModActivated>

<UpdateDatabase>XML/ScenarioText.xml</UpdateDatabase>

<UpdateDatabase>SQL/ScenarioText.sql</UpdateDatabase>

<UpdateDatabase>XML/ScenarioParameters.xml</UpdateDatabase>

</OnModActivated>

</Actions>

<EntryPoints>

<EntryPoint type="Custom" file="UI/ScenarioLoadScreen.xml">

<Name>TXT_KEY_SCENARIO_TITLE</Name>

<Description>TXT_KEY_SCENARIO_DESC</Description>

</EntryPoint>

<EntryPoint type="InGameUIAddin" file="LUA/ScenarioInitialisation.lua">

<Name>Scenario Initialisation</Name>

<Description>Scenario Initialisation</Description>

</EntryPoint>

<EntryPoint type="InGameUIAddin" file="UI/ScenarioVictoryProgress.xml">

<Name>Victory Progress</Name>

<Description>Victory Progress Display</Description>

</EntryPoint>

</EntryPoints>

</Mod>

GUIDs and MD5s have been replaced by … as they will differ, as have non-critical text strings. Some

standard tags have been removed from the listing for brevity. Pay particular attention to case of

filenames and use of the correct slash types, also the import attributes in the File tags and the values

in the Actions and EntryPoints sections.


Playing a WB Custom Game This section gives step-by-step instructions on how to play the WB Custom Game created in the

previous section.


Enable the WB Custom Game Mod If the Traders Scenario is enabled, disable it. Locate the Island Raiders Scenario and enable it, then

click the Back button


Select the Custom Game The Single Player menu will now have a Custom Game option, select it.

Note: If you can still see the “Set Up Game” option, you forget to check the “Hide ‘Setup Game’”

option on the Mod Info tab in ModBuddy.

Select the Island Raiders custom game, note how the scenario premise and victory conditions are

displayed. Click the Load Mod button.

If you have two identical entries in the custom game list, you forgot to disable the Traders scenario.

(The duplication is intentional, and serves as a warning that there are two conflicting mods enabled.)


Click on the Random Leader area to choose a civilisation

Select a civilization to play


Start the Custom Game Click the Start Game button

Check the Victory Progress Display Play a few turns and watch the turn counter decrease. To find out how to win, click the Briefing

button.


Extending the Game – Difficulty Selection This section will show you how to add a difficulty menu to the custom game configuration screen.

Start ModBuddy Start ModBuddy, open the Island Raiders Scenario project and open the ScenarioParameters.lua file

(in the LUA folder)

Add Difficulty Options Reinstate the commented out list of difficulties

Because the code that displays the custom game configuration screen is auto-adaptive that’s all we

need to do!

Save the changes, close the file and rebuild the mod.

View Changes Start Civilisation, navigate to the Mods menu and re-enable the IslandRaidersScenario mod. (This is

necessary as the rebuild process changes the date-time stamp on the .modinfo file and Civilization

therefore detects that the mod has changed and automatically disables the mod.)

Select Custom Game and the Island Raiders scenario and check that the scenario setup screen now

contains a difficulty selection menu and that King is the default selection.


Extending the Game – Adding a Map Script Assuming your mod ends up as more than just a simple World Builder based scenario (ie with

additional XML/SQL database changes and/or Lua based logic) you may want to use a map script to

generate a random map rather than using the same fixed one for every game.

This section will show you how to add a map script to the mod and enable it to be selected instead

of the fixed World Builder map from the custom game configuration screen. (To concentrate on the

process of enabling a map script in the custom game configuration screen we will add the standard

Tiny Islands script, rather than develop one of our own.)

Start ModBuddy Start ModBuddy and open the Island Raiders Scenario project

Add a Map Script Right-click on the MAPS folder, select “Add” and then “Existing Item …” Browse into the

“C:\Program Files\Steam\SteamApps\common\sid meier's civilization v\assets\Maps” sub-directory

and select the TinyIslands.lua file and click “Add”

Rename the TinyIslands.lua file to be “IslandRaidersScript.lua”


Add Additional Scenario Parameters Open the ScenarioParameters.lua file and uncomment (ie remove the initial – characters) the three

lines under the ScenarioFixedMap line (ie the ScenarioRandomMap, ScenarioMapSize and

ScenarioMinorCivs lines)

Change the ScenarioRandomMap to “MAPS/ IslandRaidersScript.lua”, leave the map size as

WORLDSIZE_STANDARD and change the number of minor civs to be 8


Add Additional Scenario Initialisation Our World Builder scenario has an additional Trireme unit, so we need to add code to add a Trireme

to every civilization. Unfortunately, due to a bug that causes the Trireme to appear on land, we

cannot do this via the Civilization_FreeUnits database table, so we will need to add the Trireme via

Lua code. Fortunately, the required code is quite simple.

Open the ScenarioInitialisation.lua file, scroll down to the InitPlayer(pPlayer) function and just after

the “local pStartPlot = GetPlayerStartingPlot()” line add the following lines

if (IsScenarioScriptMap()) then

local ship = pPlayer:InitUnit(GameInfoTypes["UNIT_TRIREME"], pStartPlot:GetX(),

pStartPlot:GetY(), UNITAI_EXPLORE_SEA, DirectionTypes.DIRECTION_WEST)

ship:JumpToNearestValidPlot()

end


Add Initial Civilization Technologies The World Builder scenario gives Pottery and Sailing as free techs to all civilisations (to support the

Trireme unit), so we need to add these for our map script generated scenario.

Right-click the SQL folder and select “Add” then “Existing Item …” and add the ScenarioTechs.sql file

from the Traders Scenario mod. The SQL in this file adds Pottery and Sailing to all civilizations, so it

will do for what we need.


On the Actions tab, add an entry to execute this file during mod activation.

Our World Builder scenario also granted an initial policy, but we won’t replicate that for the script

based scenario as it requires non-trivial Lua code to implement.

Save the changes and rebuild the mod.

View Changes Start Civilisation, navigate to the Mods menu and re-enable the IslandRaidersScenario mod. (This is

necessary as the rebuild process changes the date-time stamp on the .modinfo file and Civilization

therefore detects that the mod has changed and automatically disables the mod.)


contains a map selection menu.


Start the game with the random map and check that the Trireme unit is placed and that you start

with Pottery and Sailing.

Extending the Game – AI Only Civilizations In some circumstances we may only want the human player to be able to select from a limited range

of civilisations, while placing more on the map for them to oppose. For example, a New World

conquest scenario may limit the player to England, France or Spain, but need the AI to play as the

Incans, Aztecs and Iroquois.

In this section we will change the Island Raiders scenario such that the human player is always

England while the AI controls the other civilizations

Start ModBuddy Start ModBuddy, open the Island Raiders Scenario project and open the ScenarioParameters.lua file


Define the Playable Civilization(s) Cut the Arabia and Songhai lines out of the ScenarioCivilizations list …

Define the AI Civilization(s) … and paste them into the ScenarioAICivilizations list. Renumber them as 0 and 1

Because the code that displays the custom game configuration screen is auto-adaptive that’s all we

need to do!


View Changes Start Civilisation, navigate to the Mods menu and re-enable the IslandRaidersScenario mod.


defaults to England as the playable civilisation and that clicking on the civilization does not open the

selection menu.


Using LiveTuner, reveal the full map and check that the other Civilizations have been placed.

Conclusion The Custom Game configuration screen is fully programmable so there are an infinite number of

possibilities for custom game mods to take advantage of. However, defining the dialog layout in

XML and coding the responses to button clicks and menu selections in Lua is non-trivial, so may be

beyond the skill set of most modders who would like to convert their World Builder based scenarios

into custom games. Hopefully the TradersScenario sample mod and this Tutorial will enable more

modders to take advantage of the custom game screens.