Adding Custom Events

Events are the pop-up windows that occur during the campaign. There are different types that can be used to different effect. The events themselves are XML objects, but they are activated via a LUA event manager. This document will only cover the creation of the XML event objects; for LUA setup, please refer to the LUA modding documentation.

Event Types

There are multiple types of events, each with its own GUI look and setup.

Hard Choice

Hard choice events present a situation to the player and ask him to pick one of two options. This event type allows you to set up the question, the choices and two sets of rewards or penalties.

Headline

Headline events are set up to present historical references in the form of a newspaper. Headlines relay information only and do not have any active portion or rewards.

Historical

Historical events present the player with information. They can grant awards or penalties, but have no other interaction.

Objective

Objective events present the player with a specific task. You can set up what that task is, how long the player has to complete it, and what the reward is for completion.

Choose the Event Type

The first step is to determine what you want your event to do. If you are just presenting information, a Headline or Historical event is probably best. If you want the player to interact, an Objective or Hard Choice may work. Each of these types have a dedicated XML file you can use to see examples of setup:

• Events_Headlines.xml
• Events_Headlines.xml
• Events_Objective.xml
• Events_Hard_Choice.xml

The data setup for events is roughly the same except for some key points. The first are the GUIEventStartPaneType and GUIEventCompletePaneType tags. It is suggested that you do not change the tags from GUIEventStartPaneType down to the CanBeFailed tag. These are specific to the event type, and in most cases shouldn’t be changed. Instead, find an event of the type you want, copy that, then change the data in your new object. This way you can be sure that the format is correct. The remaining tags in the upper section can be changed to your needs:

DisplayFromUnreadQueue – If this is set to true, the event will not immediately pop up in the player’s face; instead it will be added to the event queue and the player can manually look at it later. For the most part this will be true for all events except hard choice.

TrackWithCompletedEvents – If this is set to true, the event will be tracked in the event queue and saved as “completed” for the player. If set to false, once the event ends it will not be kept in the completed list.

DurationTurns – If set to zero, the event will end as soon as the player closes the window. If set to any number, the event will last that number of turns before expiring (this is used for objective events only). If set to -1, the event will stay open until the player completes the interaction (this is used for hard choice events only).

FactionRewardAllFactions – If set to true, the rewards listed will ALL be granted to both factions. If set to false, the rewards will be granted only to the player. You can use this to have the player gain one reward and the AI gain (or lose) something at the same time. This is usually reserved for historical events.

Hard Choice Specific Setup

Hard choice events have a more complex reward and text setup than the others. You must set up rewards for both choices, and each choice can grant rewards or penalties to either or both factions.

Hard Choice Rewards

Instead of using the “FactionRewards” data tag, hard choice events use FactionChoiceRewards01 and FactionChoiceRewards02. These sets will correspond to the choice the player picks when presented with the event. Inside this entry you can have Rewards listed for either or both factions. It is suggested (though not required) that the hard choice questions be faction-specific, such that you have reward sets for only one faction and the event only activates for that faction.

The specific data setup for rewards will be covered below.

Hard Choice Text Setup

As with all text, the EncyclopediaComponent is where you will find the required text tags for the events. For hard choice you will have the following tags:

• ObjectNameTextID – This is the title that appears at the top of the event box.
• ObjectDescriptionTextID – A description of the event that sets up the situation.
• Choice01TitleTextID – A one or two word title for the first choice.
• Choice01DescriptionTextID – A short description of the first choice and why you should choose it.
• Choice01ButtonTextID – This just says “CHOICE 1”; you can leave it as-is.
• Choice01ResultTextID – A short description of the results of your choice; what happened because of it.

The same must be done for the second choice, using the same setup:

• Choice02TitleTextID
• Choice02DescriptionTextID
• Choice02ButtonTextID
• Choice02ResultTextID

Note that you do not need to set up text for the rewards – this is done automatically.

Headlines Specific Setup

Headlines are relatively simple to set up; you can leave the base data block at the top alone. All you need to set up is the text.

• ObjectNameTextID – The “headline” title of the event box.
• ObjectDescriptionTextID – The newspaper article or body of text; information you want to relay.
• EventDateTextID – If left blank, the date will match the month/year of the campaign turn. Otherwise, you can put a text tag for a date here.
• HeadlineNewspaperTextID – The name of the newspaper.

Historical Specific Setup

Historical events use the same basic text as headlines without the newspaper title:

• ObjectNameTextID – The “headline” title of the event box.
• ObjectDescriptionTextID – The historical or noteworthy information you want to relay.

Historical events can also have rewards (see below for setup rules).

Objective Specific Setup

Objectives require text, an objective (or objectives) to complete, and a reward.

Text Setup for Objectives

• ObjectNameTextID – The title of the event box.
• ObjectDescriptionTextID – The setup and “story” context for the objective you want the player to perform.
• Objective01TextID – The first objective for the player to achieve
• Objective02TextID – The second objective for the player to achieve (optional)
• ResultCompleteTextID – Text given to the player congratulating them on completing the objective.

Note that while there are text tags for “failure”, the game does not show failure event panes, they just time out as “incomplete”.

Objective Setup

Objectives are the actions you want the player to perform to complete the event. Objective events can have up to two objectives in a single event, though the second is optional. The basic setup here is ObjectiveType, which lists the general type of objective, and the details data, which will depend on the type you chose. The following objectives are supported. Note that in many cases, leaving a detail tag blank will mean that anything will do.

Example

You can set up an event that asks the player to build a level 1 airfield in Paris. If you leave the region data blank, then building an airfield 1 anywhere will complete the objective. If you keep Paris in place but leave the structure data blank, then building any structure in Paris will complete the objective. Note that this doesn’t work in all cases, so use common sense.

BuildObjectStrategic Build a region structure on the world map. You can specify a specific region and a specific structure.

CaptureRegionStrategic Take full control of a region on the world map. You can specify the region; leaving it blank will complete on any region capture.

DecreaseEnemyNationalWillStrategic The player must reduce the enemy national will by the stated amount.

DefendRegionStrategic The player must successfully win a battle where the AI attacks on its turn.

IncreaseNationalWillStrategic The player must increase his own national will by the stated amount.

MoveCorpsStrategic The player must move a corps on the world map. You can state the starting and ending destination (region names) as well as the specific corps type to move.

PurchaseCarePackageStrategic or PurchaseCarePackageTierXStrategic Purchase a care package on the world map; the first entry means any type, or specify a specific level (replace the X with 1,2 or 3).

PurchaseNationalWillLuxuriesStrategic Purchase a luxury package on the world map.

PurchaseSpecialCorpsStrategic Purchase a tank, aircraft or siege corps on the world map of the specified type and number.

PurchaseSupplyStrategic Purchase the stated amount of supply on the world map.

ResearchTechNodeStrategic The player must research (purchase with tech points) the specifically state tech node.

StartEspionageMissionStrategic Start the specified espionage mission type on the world map. Can specify a specific region or leave it blank for any region. The mission data type can be found in GameConstants.XML in the MissionType tag.

BuildObjectTactical The player must build the specified object in a battle.

CaptureObjectTactical The player must capture the specified object in battle. Limited to control points or the enemy command trench.

DestroyObjectTactical The player must destroy the stated objects in a battle in the stated numbers (example: defeat 10 German Infantry Companies)

DoSiegeBombardmentTactical The player must perform pre-battle siege bombardment with the specified number of days.

All objectives are set in the Objectives data block. Each entry in this block is a unique objective, and you can have a max of two objectives per event. For example, you can have an objective to research a tech node and then build the object that node unlocks.

A Note on Destruction Objectives

If you are creating a destruction objective, you can list more than one object type to satisfy the objective. For example, if you have an objective to defeat 10 British infantry, you may want to include both standard and elite infantry in the objective so that your players don’t get confused. You can list both in the same objective like so:

<Objectives>
  <Entry>
    <ObjectiveType>DestroyObjectTactical</ObjectiveType>
    <RegionLocation></RegionLocation>
    <ObjectTypes>
      <entry> COMPANY_Infantry_British </entry>
      <entry> COMPANY_Infantry_British_Elite </entry>
    </ObjectTypes>
    <ObjectAmount>10</ObjectAmount>
  </Entry>
</Objectives>

In the above example, defeating either type of British infantry will be accepted as part of the 10 required. You can do this with any group of objects.

Event Reward Setup

Events can have up to two rewards per faction per choice (if choices are present). There is no need to add text for rewards – this is handled and displayed by the system based on the data setup.

The reward hierarchy is:

• Choice Number
• Faction
• Reward Number
• Reward Data

If you are creating a reward for any event type other than hard choice, you will be filling in data for the FactionRewards tag. If you are setting up a hard choice event, then you will be using FactionChoiceRewards01 (and 02). You cannot use both of these in the same event.

Reward Types

The following can be granted to the player as a reward:

• Gold Reserves (called “Resources” in the data)
• Unit Corps
• Tech Points
• Supply (added to the supply bank)
• National Will
• Object State

In most cases, any numeric value for the reward can be positive or negative. For example, you can set up a reward that grants gold but reduces national will.

Object states are a special case. This is generally used as a method to unlock something, usually for the voters (prerequisite) system or for scripting. For example, the historical event “America Enters the War” uses an object state that unlocks American units for purchase.

Reward Format

<FactionRewardAllFactions> true </FactionRewardAllFactions>
<FactionRewards>
  <Entry>
    <Faction>Faction1_Strategic</Faction>
    <Rewards>
      <Entry>
        <RewardType>Currency</RewardType>
        <CurrencyType>Resources</CurrencyType>
        <ObjectType> </ObjectType>
        <Amount>1000</Amount>
      </Entry>
    </Rewards>
  </Entry>
  <Entry>
    <Faction>Faction2_Strategic</Faction>
    <Rewards>
      <Entry>
        <RewardType> Object </RewardType>
        <ObjectType> CORPS_German_Base </ObjectType>
        <Amount> 2 </Amount>
      </Entry>
    </Rewards>
  </Entry>
</FactionRewards>

In the example above, we have a situation where both factions receive a reward from the event completion (likely from a historical event). That first tag shows that both factions will receive the reward regardless of which faction the player is playing at the time. If that flag were changed to false, the reward would only be granted to the player’s faction.

The first block shows the reward for Faction 1 (the Allies). The currency reward type is used for National Will, Supply, Tech Points and Gold Reserves. The next tag specifies the currency type, Gold Reserves in this case. Since this is not an object, the type can be left blank (or just left out). The amount is the amount of the currency type awarded (so 1,000 Gold Reserves).

The second block is the reward for Faction 2 (Central Powers). In this case, the reward is an object, specifically a German infantry corps. The amount shows as two, so the Germans will get 2 infantry corps for their troubles.

For hard choice events, you would create one of these blocks for each choice, using the FactionChoiceRewards01 and 02 blocks instead. Otherwise the data setup remains the same.

Finalizing your Events

Once you have the event type, text, objectives (if any) and rewards (if any) set up, give your event object a unique name and either add it to an existing event XML file or add your own. Once the object is complete, you can reference it via LUA to activate it in game.