A Guide to Events and NIS Script (part 1) tutorial – The Protectors of Etheria

And has the following effect:

Note that flags are universal across all sides in a scenario, so changing the side owner for flag activation does nothing.

The event where the hero kills an enemy ghoul will have this condition:

And this effect:

And the event which spawns the unit will have this condition, with two flags required to be on:

And this effect:

See that both flags 0 and 1 are set to “On”, meaning that both have to be on for this event to activate (no other flags are needed, and are left as they were, which say “Any”).

And finally, the effect looks like this:

Why two flags? Well, we could do this in two different ways, but they have slightly different results. The way the example portrays makes it so that, at any point during the game, if side 1’s hero has visited the pool and killed a Ghoul, the event triggers. We could instead have just one flag event and the spawn event, and set the spawn event condition to be side 1’s hero going to the pool and requires flag 0 to be “On”, activated by killing the ghoul. This is a bit different, as it would mean that the pool must be visited after the Ghoul is killed, and not at any time, in order to trigger the unit spawn event.

To change the condition of an event, click on the title (for example, Move a unit(s) to a square(s)). This will scroll-through the list of available conditions. These are:

• Move a unit(s) to a square(s) – condition is triggered when a number of the selected type of units, belonging to the specified side, move into the radius (in total).
• Move a hero to a square(s) – condition is triggered when a hero, belonging to the specified side, moves into the radius.
• Build a building(s) – condition is triggered when a number of the selected type of buildings are constructed over the course of the game, by the specified side.
• Produce a unit(s) – condition is triggered when a number of the selected type of units are produced over the course of the game, by the specified side.
• Kill a unit(s) – condition is triggered when a specified side kills a number of the selected type of units over the course of the game.
• Kill someone’s unit(s) – condition is triggered when a specified side kills a number of another, selected side’s units over the course of the game.
• Obtain an item – condition is triggered when a hero of a specified side picks up a selected item(s).
• Raze a building(s) – condition is triggered when a specified side destroys a number of the selected type of building over the course of the game.
• Raze someone’s building(s) – condition is triggered when a specified side destroys a number of another, selected side’s buildings over the course of the game.
• Defeat by Loss Of Character – condition is triggered when a specified side is defeated from losing a character, whose name is written in the box below.
• Select Units – condition is triggered when a specified side selects a number of the selected type of unit(s).
• Select Building – condition is triggered when a specified side selects a number of the selected type of building(s).
• Conversion Started – condition is triggered when a specified side begins conversion of a number selected type of building(s).
• Building Converted – condition is triggered when a specified side converts a number of the selected type of building(s) over the course of the game.
• Research Completed – condition is triggered when a specified side completes the selected type of research.
• Resources – condition is triggered when a specified side accrues a specified amount of the selected type of resource.
• Move Character – condition is triggered when a character of a specified side, whose name is written below, moves into the radius.
• Button Press – condition is triggered when a specified side presses the selected button.
• Side Defeated – condition is triggered for a specified side when the selected side is defeated.
• Counter >= – condition is triggered when a specified side has an equal or greater counter value than a selected side.
• Dead Hero – condition is triggered for a specified side when the selected side’s hero dies.
• Kill Hero – condition is triggered when a specified side kills the selected side’s hero, the specified number of times over the course of the game.
• Quest Received – condition is triggered when a specified side receives a quest.
• Kill armies with hero – condition is triggered when a specified side’s hero kills a number of the selected type of unit over the course of the game.
• Dead character – condition is triggered for a specified side when a character of the selected side, whose name is written below, dies.
• Hero hp below % – condition is triggered for a specified side when a hero of the selected side, has less than a specified percentage of HP left.
• Character hp below % – condition is triggered for a specified side when a character of the selected side, whose name is written below, has less than a specified percentage of HP left.
• Search Army/Building – condition is triggered when a specified side searches a selected character unit or building, the specified number of times over the course of the game.
• Item equipped – condition is triggered when a specified side’s hero equips the selected item.
• Spot character – condition is triggered when a specified side has vision of one of the selected side’s characters. This vision can derive from: any source, a hero source or character source.
• Spot side – condition is triggered when a specified side has vision of the selected side. This vision can derive from: any source, a hero source or character source.
• Spot unit – condition is triggered when a specified side has vision of the selected unit. This vision can derive from: any source, a hero source or character source.
• Spot buildings – condition is triggered when a specified side has vision of the selected building. This vision can derive from: any source, a hero source or character source.
• Spot hero – condition is triggered when a specified side has vision of the selected side’s hero. This vision can derive from: any source, a hero source or character source.
• Cast a spell – condition is triggered when a specified side casts the selected spell.
• No remaining assets – condition is triggered for a specified side when the selected side has no units, buildings or heroes left. This can be re-triggered multiple times via loop count, if the selected side were to regain any units buildings or heroes (via events of NIS script, and only if the selected side can’t be defeated).
• No Condition (timer) – condition is triggered for a specified side when a certain amount of time has passed. This time can be set in the Events menu panel when selecting this event (and the time is in seconds).

Event Effects

Events can have up to four independent effects. Each effect will share the condition set by the event. To change the number of effects that an event has, check the box next to that effect. The order of effects is top-left to bottom-right, so check boxes going from the top-left to bottom-right to add more effects, and uncheck boxes going from bottom-right to top-left to decrease the amount of effects (to a minimum of 1 effect). Click on any available effect number to edit that effect.

NIS Scripts

NIS scripts are files with xml syntax and the “.nis” file extension. They are very powerful, and can perform just about any interaction you can imagine (such as complex multi-choice events, full RPG dialogue trees complete with stat checks, asset additions or removals, complex counting events and unit/building searching). They work in a similar way to any xml formatted file, such as the various campaign files. NIS can be used for campaigns as well as scenarios, though certain parameters won’ function if they’re designed for a specific environment. Inside, there can be a number of parameters, all enclosed within the main parameter. See The Structure of NIS Script section for more information.

Activating NIS Scripts

In a campaign, the way of activating NIS script is with a patnis type Action. See the Campaign Guide for more information regarding campaign NIS script. Within scenarios, there is a single event effect which activates NIS scripts. This is the “Scene Event” effect. When browsing through event effects in the add/remove Events panel, you’ll see both “Scene + Show Hidden” and “Scene Event”. Both are identical, except that Scene + Show Hidden also adds three “Uncover Hidden Map” effects. A Scene Event effect looks like this:

The NIS script file to be referenced is written in the text box at the bottom of the panel (including the file extension), and the owner of the effect changes which side the script applies to. This is very important. If for example, the referenced NIS script is a dialogue event, changing the owner changes who engages with that dialogue. At this time, only players can activate NIS script. If an AI player activates a NIS script, the file is ignored and nothing happens. Likewise, if in multiplayer, then only the host can activate the script. This will be updated in time, so that player-context-sensitive NIS script can become a reality, meaning any player can potentially interact with scripts. The referenced NIS script must be in the same folder as the map it is associated with. It is a good idea to make the first part of the NIS script the same name as the associated map, and change the second part to anything suitable as you like. This will help you to identify which NIS script belongs to which map, and also identify what it does. For example, if your map name is WBC2_Selentia.SCN, your NIS script file name may be WBC2_Selentia_meetBarbarians.nis.

The Structure of NIS Script

NIS scripts are similar to campaign files, in that although they are all xml format, they can have a variety of different functions. Depending on those functions, different parameters may be required. NIS scripts must have and obey these structural rules:

• Don’t copy the ” symbol as the text character differs from one text editing program to another (especially from word or office programs). Notepad, Notepad++, Visual Studio Code and other programs are recommended for editing NIS script.
• All NIS files must have the “” parameter at the beginning of the file, and closed at the end of it “”. This tells the game that this is a NIS script file. The NIS parameter can’t have any conditions.
• Just like all xml files, NIS scripts are case sensitive. This means that a capital letter is different to a lower case letter of the same type (T=/=t, for example). Care must be taken to ensure that all xml files use the correct capitalization for the parameters and any of their definitions (and file name references must be the same as the file name).
• If the NIS script is a message-type script (as in, it has dialogue messages), then the characters which partake in the dialogue must be defined. Characters are defined with the “” parameter, which looks like this: <Character id=“1” portrait=“9999”>NarratorCharacter>. The “ID” attribute is a way of identifying the character, and begins at 1, and the “portrait” is the numerical ID of the portrait to display for the character (9999 is the narrator portrait). These can be found in: Warlords Battlecry The Protectors of Etheria\Assets\Heroes\Portraits.xcr. The text which this element takes is the character name, which is displayed whenever the character talks. In the above example, this would be “Narrator”. Character parameters can’t have any conditions.
• Like any xml document, the apostrophe symbol, among others, can’t be input into text directly and must use a code which represents them. The list of text codes are:

  • ‘ – is translated as “’”

  • > – is translated as “>”

  • < – is translated as“<”

  • &qt; – is translated as “””

  • &name; – inputs the name of the side’s hero.

  • &day; – inputs the current day of the year

  • &year; – inputs the current year

Placing the actual symbols of the first four points on this list in the description text of a NIS file will result in the file not being read by the game. For example, if you type:

Instead of:
I see you are a &qt;minotaur!&qt;
The game will not read the file and It won’t work.

• Developer comments can be input into the file. These are strings of text which are not read by the game and hence exist to help clarify or explain parts of a script. These can be entered using the command. Anything inside (in this particular case, “comment”), will be free from any xml syntax and is not read.

With the structure of NIS scripts out of the way, let’s take a look at all the various parameters and their attributes.

NIS Parameters

NIS parameters are identical in the way they are written, as xml ones (which includes campaign parameters). They have a starting tag and ending tag, such as and , and can include other parameters or be further defined with attributes. Some parameters are take no data (but may take attribute definitions), such as . These will be outlined in the NIS parameter list. Some attributes are mandatory, and other are optional for certain parameters. These will be underlined and italicized in the below list.

NIS parameters and their attributes can be arranged according to the following categories:

Sources

Many of the various NIS parameters and their attributes refer to one or more pieces of information, such as numerical or 4-character IDs which are not observable within any one single document. Instead, this information can be found in various game files according to whatever it is that you’re looking for:

• Unit/Hero Avatar IDs – These numerical or 4-character IDs can be found in: Warlords Battlecry The Protectors of Etheria\Assets\Data\System.xcr\army.cfg. 4-character unit IDs can also be found in: Warlords Battlecry The Protectors of Etheria\English\HelpArmy.cfg

• Hero Voice IDs – These 4-character IDs can be found in: Warlords Battlecry The Protectors of Etheria\Assets\Sides\HeroesVoicesEN.xcr

• Hero Portrait IDs – These numerical IDs can be found in: Warlords Battlecry The Protectors of Etheria\Assets\Heroes\Portraits.xcr

• Race IDs – These numerical IDs can be found in: Warlords Battlecry The Protectors of Etheria\English\CreateHeroLore.xml

• Faction IDs – These numerical IDs can be found in: Warlords Battlecry The Protectors of Etheria\English\CreateHeroLore.xml

• Hero Class IDs – These numerical IDs can be found in: Warlords Battlecry The Protectors of Etheria\English\CreateHeroLore.xml

• Spell/Ability IDs – These numerical IDs can be found in: Warlords Battlecry The Protectors of Etheria\English\spells.txt

• Building IDs – These numerical or 4-character IDs can be found in: Warlords Battlecry The Protectors of Etheria\Assets\Data\System.xcr\building.cfg. 4-character building IDs can also be found in: Warlords Battlecry The Protectors of Etheria\English\HelpBuilding.cfg

• Research IDs – These 4-character IDs can be found in: Warlords Battlecry The Protectors of Etheria\English\HelpPowerup.cfg

Shared Attributes

Attributes are extra pieces of data or definitions which modify the function of parameters or provide necessary values for a parameter to function. These are included with parameters, such as the aforementioned AddPotion parameter which has the two attributes “healing” and “mana”. Attributes come in many forms in that they can sometimes accept numerical data, text data or a mix, and are case sensitive, just like parameters. Many NIS parameters, like some campaign parameters, have shared attributes. Below is a list of shared attributes. If there are any which differ in function from parameter to parameter, these differences will be mentioned with that respective parameter.

• “id” – This attribute refers to the ID of the related entity. For a Message parameter, it refers to the numerical ID of the speaking character (which must start at 1). For a unit or building, it refers to that entity’s numerical ID.

• “idisbav” – This attribute can be used to insert the stored battle value into the ID. Only one value can be stored at a time, and this resets at the end of a scenario.

• “owner” – This attribute changes the side owner of the related entity, such as a Message parameter, or it specifies the side owner of the asset to modify, such as Move or Patrol (neutral is 0, the first side in a scenario is 1, the second is 2 etc).

• “ishero” – This attribute changes the target of the parameter to a side’s hero. If it’s a Message parameter, it ensures that their selection disc will flash while the message is displayed. No additional data is required for this attribute.

• “x” and “y” – This pair of attributes set the x and y coordinates of the related parameter.

• “xisopt” and “yisopt” – This pair of attributes change the x and y values of the related parameter to the variables recorded in the same NIS script (they are stored for the duration of the NIS script only).

• “xisbav” and “yisbav” – This pair of attributes change the x and y values of the related parameter to the stored scenario value (these values are stored for the duration of a battle).

• “xiscoordx” and “yiscoordy” – This pair of attributes change the x and y values of the related parameter to the values stored using the GetCoords parameter, which is a parameter that gets an asset’s coordinates (also stored for the duration of a battle).

• “radius” – This attribute determines the radius (area of effect, in cells) of the related parameter.

• “showno” – This attribute is used by most of the parameters which deal with variables. It displays the value of the variable associated with the index number on-screen with the specified text (such as showno=”Variable 1:”).

Dialogue Parameters

• Character – id portrait color side conqueror negotiator – This is a mandatory parameter if your NIS script also features any Message parameters. “id” refers to the numerical ID of the defined character (first one must be 1), “portrait” refers to the numerical ID of the portrait. Color is a numerical ID that changes the colour of the displayed character’s name. “Side” is a numerical ID that changes the color of the character’s text box to that side colour in a scenario. “conqueror” sets the character as the conqueror of a region in a conquest campaign, and “negotiator” the character that is entering negotiation with the conqueror.

• Message – stage character owner ishero id idisbav name – Message displays a piece of dialogue in a box, spoken by a specified character (it must have a character associated with it). “stage” takes any number of text characters, and is a useful way of linking choices and other actions with dialogue messages. This is the primary way of redirecting a choice to a specific dialogue tree. “name” overwrites the displayed name specified in “character”.

• Choice – character – Gives the player a set of dialogue or other choices. The Choice parameter must have a “character” attribute, much like the Message parameter, which defines which character is receiving the choice (from a narrative perspective). Choice parameters offer choices using a set of sub-parameters a, b, c, d, e, f etc, which all contain the text for the choice. In order for the choice to function, after the definition of the Choice parameter, parameters such as Message or anything else, must have “condition” attributes, and these attributes line up with the alphabetical choice parameters. However, these “condition” attributes are “no1”, “no2”, “no3”, “no4”, “no5”, “no6” etc, so they use “no” as well as a number which refers to the choices (a = no1, b = no2 etc. “and” and “and not” also works here, so you can write “no1 and evil” or “no2 and not good” etc). As the Choice parameter has very limited reference capabilities, it is highly recommended that Stage parameters with condition attributes are used to redirect to the effects of the various choices.

• Choice2 – character random – Almost identical to the Choice parameter, except that it can assign a secondary choice made to memory (referred to as “no11”, “no12”, “no13” etc). With the advent of the Stage parameter, Choice2 is no longer needed.

• PlayWAV – This parameter has no attributes, and accepts a sound filename, including its extension. The sound being played must be in wav format, and must be in the Data folder if this NIS is in a campaign, or in the Scenario folder if not. PlayWav can be used for any sound, including spell effects and voicelines.

Asset Parameters

• Move – x y owner ishero id idisbay speed – The Move parameter moves a unit to a destination of x and y. The text which must be included with the Move parameter, refers to either a specific character name, or to anything which matches the attributes, in which case “ANY” must be written. The “speed” attribute can change the speed of the unit for the duration of this movement.

• Patrol – x y owner ishero id idisbav xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The Patrol parameter makes a unit patrol between its current location and the target destination of x and y. To make the unit patrol between multiple points, add a new set of x & y coordinates with number on the end (so like “x1” “y1”, “x2” “y2” etc). Similar with Move, Patrol takes a name text string which either must specify a character name or if it’s not a character unit, then “ANY”.

• Attack – target owner ishero id idisbav targetowner targetishero targetid targetidisbav speed – The Attack parameter makes a unit attack another unit or a building. It must have a target, which has to be the target’s character name or “ANY” if not one, can define if the attacker is a hero, its ID, and all similar values of the target, which all have the word “target” in front. The Attack parameter takes the attacking unit’s character name or if not one, then “ANY”.

• Guard – target owner ishero idisbav targetowner targetishero targetid targetidisbav – The Guard parameter makes a unit guard another unit or building. It must have a target, which has to be the target’s character name or “ANY” if not one, can define if the attacker is a hero, its ID, and all similar values of the target, which all have the word “target” in front. The Guard parameter takes the guarding unit’s character name or if not one, then “ANY”.

• Kill – owner ishero id idisbav – The Kill parameter kills a unit or destroys a building. The Kill parameter takes the character name of the asset to be killed, or if not one, then “ANY”.

• Damage – x y radius owner ishero xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The Damage parameter deals an amount of damage to units within a specified radius of the target location. If no owner is set, the damage is dealt as if the source was the neutral side (and therefore hits every defined scenario side). The Damage parameter takes a numerical value, which is the amount of damage that will be dealt. This is pure damage, and is not subject to a damage type (and hence it can’t be resisted and nothing can be vulnerable to it).

• AddUnit – x y charname xp owner ishero id idisbav number numberisopt xpisopt xpisvar xpisvarl xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The AddUnit parameter adds a unit, which must be the standard unit name or 4-character ID, specified by the parameter itself, to the designated location. If no location is designated, the unit is spawned at coords 0, 0. If no owner is specified, the unit spawns neutral. “charname” specifies the name of the unit(s). “xp” specifies the amount of XP the unit has, “xpisopt” changes the amount of XP it has to the variable recorded in the same NIS script. “xpisvar” changes the amount of XP it has to the value recorded in global variables. “ishero” spawns the unit at the “owner” side’s hero’s coordinates. “number” determines the number of units to spawn. “xpvarl” changes the amount of XP it has to the local variable defined in XP.

• RemoveUnit – owner ishero id idisbav – The RemoveUnit parameter removes a unit, which must be the unit’s character name, specified by the parameter itself, or if not a character, then “ANY”. If no owner is specified, the removed unit will belong to the neutral side if available.

• TeleportUnit – x y charname owner ishero id idisbav xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The TeleportUnit parameter teleports a unit, which must be the unit’s character name, specified by the parameter itself, or if not a character, then “ANY”. If no coordinates are specified, then the unit will be teleported to the coordinates 0, 0. If no owner is specified, the teleported unit will belong to the neutral side if available.

• ProduceHero – owner generate race faction class level relativelevel portrait avatar voice – The ProduceHero parameter spawns a hero with a name specified by the parameter itself, or if generated, then “ANY”, at that side’s starting location. “generate” randomly generates the hero, including their name. “race”, “faction” and “class” are numerical values which refer to the hero’s race, faction and class. “level” is the level of the generated hero and “relativelevel” is a numerical value which if used, makes the hero level higher or lower than the player’s hero by the specified value (to a minimum hero level of 1). “portrait” is a numerical value which determines what portrait the hero will have. “avatar” refers to the 4-character ID of the model used by the hero. “voice” refers to the 4-character ID of the voiceset to be used by the hero.

• Attitude – owner ishero id idisbav attitude – The Attitude parameter changes the attitude of the specified unit’s character name or if not a character, than “ANY”. “id” refers to the unit’s numerical ID.

• SetSearchable – owner id idisbav ishero searchable – The SetSearchable parameter activates the ‘searchable’ tag for a unit or building. The searchable tag, when active, makes that unit or building searchable by a hero in the same way a quest building is. Use an event (Scene Event), with the condition of searching that unit or building, to launch a NIS script. If there is no owner, then the unit or building to be made searchable will be on the neutral side. “searchable” is the value that sets the unit or building to be searchable. 1 = searchable, 0 = not searchable (using this parameter, you can turn a unit’s ‘searchability’ on and off). The SetSearchable parameter itself takes a character name, and if the target isn’t a character, then “ANY”.

• SetMana – owner TargetIDCode Max IncludeBuildings FlagsAND FlagsNOT characterID radius x y – The SetMana parameter gives an amount of mana to a target or targets within an area of effect of units and/or buildings. “TargetIDCode” is the 4-character ID of the unit or building. “Max” overwrites the SetMana parameter and sets the target assets’ mana to maximum. “IncludeBuildings” is necessary if the target includes or is specifically just buildings. “characterID” specifies the character name of any target unit or building to give the mana to. “x” and “y”, if used, determine the exact coordinates to give the mana, or the coordinates of the radius. The SetMana parameter itself takes a numerical value which is the amount of mana to give (or take away).

• SetInvincible – owner ishero id idisbav invincibility – The SetInvincible parameter makes a unit or building invincible indefinitely. “invincibility” sets whether the unit or building is invincible or not. 1 = invincible, 0 = not invincible. The parameter itself takes a character name, and if the target isn’t a character, then “ANY”.

• SetAffliction – owner ishero id idisbav type – The SetAffliction parameter gives a specified affliction to a target unit or building. If the target can’t receive that affliction (such as giving a unit the Haunted affliction or a building the Poison affliction), nothing happens. The parameter itself takes a character name, and if the target isn’t a character, then “ANY”.

• SetQName – unit – The SetQName parameter sets the name of a quester while a quest or search is being undertaken. The “unit” attribute, if used, specifies that the quester is not a hero or character and is a standard unit. The parameter itself takes a character name or a unit’s standard name.

• Owner – towner to id idisbav – The Owner parameter changes the ownership of a unit or building from one side to another. “towner” specifies the side owner of the target unit(s) or building(s). “to” specifies the side to give those assets to. The parameter itself takes a character name, and if the target isn’t a character, then “ANY”.

• ChangeID – to id idisbav – The ChangeID parameter switches a unit or building of a specific ID to another unit or building of another ID. “to” specifies the numerical ID of the unit or building to change that target unit or building to. The parameter itself takes a character name, and if the target isn’t a character, then “ANY”.

• ChangeChar – id portrait color side – The ChangeChar parameter changes a character’s numerical unit ID (thereby transforming it) and changes the portrait that they use. “id” is the numerical ID of the unit type to change the character to. “portrait” is a numerical value which determines what portrait the character will have. “side” specifies what side the character is on (useful if there are characters with the same name on more than one side). “color” is a deprecated attribute which changed the side colour of the character, though now characters have unique effects post 0.8.9+, this function is no longer needed. The parameter itself takes a character name.

• AddXP – xp owner ishero id idisbav xpisvar xpisvarl xpisopt – The AddXP parameter gives the specified amount of XP to a target unit(s). “xp” specifies the amount of XP the unit is given, “xpisopt” changes the amount of XP it is given to the variable recorded in the same NIS script. “xpisvar” changes the amount of XP it is given to the value recorded in global variables. The parameter itself takes a character name, and if the target isn’t a character, then “ANY”. “xpvarl” changes the amount of XP it has to the local variable defined in XP.

• AddBuilding – x y charname owner ishero id idisbav xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The AddBuilding parameter adds a building, which must be the standard building name or 4-character ID, specified by the parameter itself, to the designated location. If no owner is specified, the building spawns neutral. “charname” specifies the name of the building. “ishero” spawns the building next to the side owner’s hero.

• AddFeature – x y xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The AddFeature parameter adds a feature to the specified coordinates. The parameter itself takes the name of the feature to be added.

• RemoveFeature – x y xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The RemoveFeature parameter removes a feature which is located at the specified coordinates.

• AddPFX – x y xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The AddPFX parameter adds a PFX of a specific numerical ID, taken by the parameter itself, to the specified coordinates.

• RemovePFX – x y xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The RemovePFX parameter removes a PFX which is located at the specified coordinates.

• Terrain – x y xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The Terrain parameter changes the terrain tile located at the target coordinates to the one specified by the parameter itself, which must be a 4-character ID. After changing terrain, don’t forget to use the ResetMovePath parameter afterwards – and if merging land masses, also the RemapIslandData parameter.

• GetCoords – owner ishero id idisbav – The GetCoords parameter gets the coordinates of the specified unit or building, and stores those values with respect to any “xcoordx” or “ycoordy” attributes. The parameter itself takes a character name, and if the target isn’t a character, then “ANY”.

Scenario & Side Parameters

• Screen – x y xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The Screen parameter slowly scrolls the screen to the specified coordinates. This parameter will always leave the centre of the screen, regardless of resolution, at the target coordinates.

• Screento – owner ishero id idisbav – The Screento parameter slowly scrolls the screen to the character name (or “ANY”, if not a character), specified by the parameter itself. The attributes can be used to further define what to screen to if the target isn’t a character. Like Screen, this parameter will always leave the centre of the screen, regardless of resolution, at the target.

• Weather – The Weather parameter changes the weather to the type specified by the parameter itself. 0 = day fine, 1 = day rain, 2 = night fine, 3 = night rain, 4 = day storm, 5 = night storm.

• Music – The Music parameter stops any previous music track and plays a new music track, specified by the parameter itself, from beginning to end (if not interrrupted). The music track must be located in Warlords Battlecry The Protectors of Etheria\Music, or in a subfolder of that folder.

• Flag – id off condition – The Flag parameter turns the specified flag on for that scenario (this does nothing outside of a scenario). “off” instead turns the specified flag off. “condition” specifies any flag conditions that must be met in order to turn the specified flag on or off. The condition could be: “flag12on and flag2off” for example.

• ReviveSide – The ReviveSide parameter (re)spawns a side, specified by the parameter itself, if that side is currently not in play (either because it didn’t exist, or because it was defeated).

• Team – owner – The Team parameter changes a side, specified by “owner”, to the team number specified by the parameter itself.

• ShareVision – owner1 owner2 negotiator1 negotiator2 – The ShareVision parameter shares vision between a specified side “owner1”, and another specified side “owner2”. Note that this shares the first side’s vision with the second side and not the second side’s vision with the first, so it’s possible to have one side see another without them being able to see back. To have both sides see each other’s vision, two parameters must be used. The parameter itself is a boolean value that takes a 1 or 0, to turn shared vision between the sides on, or off respectively. “negotiatior1” and “negotiator2” set the first side reference and second side reference respectively as two negotiators in a conquest campaign.

• ShareTeams – owner1 owner2 negotiator1 negotiator2 – The ShareTeams parameter shares teams between a specified side “owner1”, and another specified side “owner2”. Note that this shares the first side’s team status with the second side and not the second side’s team status with the first, so it’s possible to have one side be allied with another and them being enemies back. To have both sides team up with each other, two parameters must be used. The parameter itself takes a 2, 1 or 0, to set the shared teams as ‘neutral’ (allied but will become enemies if attacked), turn shared teams on between the sides, or off respectively. “negotiatior1” and “negotiator2” set the first side reference and second side reference respectively as two negotiators in a conquest campaign.

• ChangeAI – owner saveprevious loadprevious – The ChangeAI parameter changes a specified “owner” side, if an AI side, to the AI specified by the parameter itself. “saveprevious” saves the AI of that side and “loadprevious” loads the last saved AI for that side. The parameter takes a numerical ID which relates to an AI type: 0 = passive, 1 = baron, 2 = count, 3 = duke, 4 = prince, 5 = king, 6 = emperor, 7 = demigod, 8 = rampant.

• SetHate – owner1 owner2 – The SetHate parameter gives an AI side “owner1” a specified amount of hate against the side “owner2”. Hate is a numerical value which increases the chance that an AI side will prioritise attacks against a hated side.

• SetUnfixedAlliance – owner – The SetUnfixedAlliance parameter changes a side so that it is now subject to the unfixed alliance mechanic, which allows that side to change its team in the scenario (if attempting to ally with another team, that team must accept the request for the alliance to be enacted). The parameter itself is a boolean value 1 or 0, which turns the mechanic on or off for the specified side.

• RemapIslandData – StartX StartY EndX EndY – The RemapIslandData parameter checks an area from the starting coordinates “StartX” and “StartY” to the ending coordinates “EndX” and “EndY”, and reads any ‘islands’ within that area (islands in this case are areas which are inaccessible via foot). This data is then used by the AI, so it can ‘see’ those islands and operate properly. The RemapIslandData parameter must be used if any new islands are created or removed by the use of modifiying terrain via the Terrain parameter or modifiying features via the Add/RemoveFeature parameters (only if adding or removing features would create or remove new areas which were previously inaccessible). Set all four coordinates to “-1”, to cover the entire map.

• ResetMovePath – This parameter doesn’t take any data or have any attributes. When processed, this parameter resets unit pathfinding for a scenario, which is recommended to be done after changing terrain or adding/removing features.

• VictoryCondition – This parameter changes the victory condition of the scenario. The parameter itself takes the numerical ID of the victory condition to change the current one to. 0 =Standard Victory, 1 = Raze All Buildings, 2 = Kill All Units, 3 = Assassination, 4 = Raze Fest, 5 = Slug Fest, 6 = Fortress, 7 = King of the Castle, 8 = Prospectors, 9 = Against the Horde, 10 = Battle of Titans, 11 = Pitched Battle, 12 = Capture the Flag, 13 = Triggered, 14 = King of the Hill, 15 = Conquest.

• ResetGame – The ResetGame parameter restarts the scenario being played. It has no attributes and takes no data.

• GameSpeed – The GameSpeed parameter sets the game speed to the speed indicated by the numerical ID, specified by the parameter itself.

• SetStartLocation – x y owner xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The SetStartLocation parameter changes the specified side’s start location to the specified coordinates.

• UncoverHiddenMap – x y radius xisopt yisopt xisbav yisbav xiscoordx yiscoordy – The UncoverHiddenMap parameter uncovers a certain amount of hidden map as specified by the “radius” attribute, at the specified coordinates. The side which receives this vision is the side owner of the associated event.

• Research – owner – The Research parameter gives a specified side a research, which is automatically completed. The parameter itself takes the 4-character ID of the research to be given.

• AddProduction – owner producer requirement1 reqirement2 priority dependflags – The AddProduction parameter adds a unit or research to a specified building’s production menu. “producer” is the 4-character ID of the building that this production will be added to. “owner” is a numerical value which specifies the owner of the building that will receive the production (0=first player’s side, 1= second etc). “requirement1” and “requirement2” specify 4-character IDs of units, buildings or researches that are required to produce the added unit or research (use requirement1 first and then 2 if you want to set a requirement or two requirements). “priority” determines what AI levels can use this production. See Warlords Battlecry The Protectors of Etheria\Assets\Data\System.xcr\Building.cfg for more details. This is defaulted to 0 if not present, which means all AI levels can use it.
  “dependflags” determines what code flags the production is associated with. Currently there’s only one usable code flag (1 – which determines whether this powerup can be in Plunder Crates or not). Since Plunder Crates are created at the start of the game, this attribute won’t do anything at this time. The parameter itself takes the 4-character ID of the unit or research to add.

• AddConstruction – owner quantity cost summon neutral – AddConstruction adds a building (which can be constructed) to a specified side’s build menu. “quantity” determines the number of times that construction can be built/summoned before being taken off the menu (if not specified, then it’s indefinite). If “cost” is set to 1, then the building has a resource cost (if not specified, then it’s free). “summon” makes it so the building is summoned at a target location, and hence has no construction time. “neutral” specifies that the building is constructed on the neutral side instead of the menu owner’s side. The parameter itself takes the 4-character ID of the building to add.

• CreateEvent – ctype cowner flags cx cy radius cnumber ctarget cname effect ownertype ownerdata x y number numberisopt type location time shots loopcount xiscoordx yiscoordy xisopt yisopt xisbav yisbav cxiscoordx cyiscoordy cxisopt cyisopt cxisbav cyisbav timeisopt timeisbav effect3name – The CreateEvent parameter creates a new scenario event with the values specified in its attributes. The parameter itself takes a unit name, which must be the same name as the unit the event is related to. “ctype” is the numerical ID of the event condition. “cowner” is the side owner of the event condition.

• CastSpell – owner ishero id idisbav level locationx locationy – The CastSpell parameter casts a spell which is owned by the side “owner”, is cast at a spell “level”, at a specified set of coordinates “locationx” and “locationy”. If “ishero” is used, then the spell is cast by the hero of the specified side. The parameter itself takes a numerical spell ID.

• Resources – owner gold metal stone crystal – The Resources parameter gives an amount of resources, specified by the parameter itself, of the specified type, to a specified side.

• SetObjective – id ctype cowner flags cx cy radius cnumber ctarget cname effect ownertype ownerdata x y number numberisopt type location time shots loopcount xiscoordx yiscoordy xisopt yisopt xisbav yisbav cxiscoordx cyiscoordy cxisopt cyisopt cxisbav cyisbav timeisopt timeisbav effect3name font – The SetObjective parameter sets a text-based objective, displayed at the side of the screen. Anything with a ‘c’ in front refers to the condition, much like CreateEvent. “font” changes the colour of the text (0 = normal, 1 = green (completed), 2 = red (failed)).

• ClearObjective – id – The ClearObjective parameter deletes an objective with the specified numerical ID.

• ModifyObjective – id font addtext – The ModifyObjective parameter changes an existing objective with the specified numerical ID and adds text to it (such as addtext=”Done!”).

• SideMessage – owner type colour time – The SideMessage parameter displays quick pop-up text in the upper centre of the screen for the side “owner” of the parameter. “type” refers to the way the message is displayed. A type of 0 means that the message is disaplyed in the middle of the screen (like a completed research) and a type of 1 means that the message is displayed to the left-hand side of the screen (such as when researching a spell). “colour” is a numerical ID which changes the colour of the pop-up text (if not specified, then it’s white. 0 is red). “time” specifies the time, in seconds, that the text is displayed. The parameter itself takes the text to be displayed.

• Find – owner ishero id idisbav number – The Find parameter searches the map for a character or standard unit, and if found alive, then the condition “found” becomes 1 (see NIS Conditions for more information). The parameter itself takes the name of the character to find, or “ANY” if not a character.

Campaign & Hero Parameters

• Setvar – global name iscompanionxp visible objective – The Setvar parameter sets a specific variable to the value specified by the parameter itself. “global” is a boolean value which must be either 1 or 0, 1 specifies that the variable to change is a global campaign one, and 0 specifies that it’s a location-specific variable. “name” refers to the text name of the variable to change. “iscompanionxp” specifies that the parameter is being used to change the XP of a certain campaign companion, defined by “name”. “objective” specifies that it’s an objective-specific variable (the objective to change is defined by “name”). “visible”, when used, displays the specified objective on the world map.

• Addvar – global name iscompanionxp visible objective – The AddVar parameter adds a new global variable or location-specific variable depending on whether “global” is set to 1 or 0 respectively. “name” gives the variable a name (which may be referred to in some other parameters, instead of its numerical ID). “iscompanionxp” tags the variable as being the XP level of a companion. “objective” tags the variable as an objective-specific variable. The parameter itself takes the numerical value of the variable to be added. “visible”, when used, displays the specified objective on the world map.

• AddCompanion – xp code cantrefuse xpisvar xpisvarl xpisopt – The AddCompanion parameter adds a campaign companion with the specified XP level and with the unit type specified by “code”, which takes a 4-character ID. “cantrefuse” makes it so that no option is presented to the player and hence the companion cannot be refused. “xpisvar” changes the amount of XP it has to the value recorded in global variables. “xpisopt” changes the amount of XP it has to the variable recorded in the same NIS script. The parameter itself takes the name of the companion. “xpvarl” changes the amount of XP it has to the local variable defined in XP.

• RemoveCompanion – The RemoveCompanion parameter removes a companion from the hero’s roster. The parameter has no attributes, and takes the name of the companion to be removed.

• Crowns – owner – The Crowns parameter gives or takes away a side owner’s crowns. The parameter itself takes the amount of crowns to give or take away (say 100 to give 100 crowns, or -50 to take away 50 crowns).

• Item – curse helmets shields weapons rings boots necklaces belts race raceloc – The Item parameter gives an item of a numerical ID specified by the parameter itself to the owner of the NIS event. If the numerical ID is 0, then it is randomly generated. The attributes are all boolean values (take 1 or 0, true or false), which include categories of item for its generation. For example, if “helmets” and “weapons” are set to 1 and everything else is 0, then the item that is generated will be a helmet or weapon. “race” is a numerical ID that makes the item that is spawned related to that specific race in the item’s lore (so a dwarven axe for example, won’t spawn if race is set to 2, undead). “raceloc” takes the race of the location that the player is currently at.

• AddItem – x y xisopt yisopt xisbav yisbav type index – The AddItem parameter works similarly to the Item parameter except that the item’s numerical ID is specified by “index”, and the item is spawned on the ground in a scenario at the specified coordinates. The parameter itself takes optional text to display when adding the item.

• AddPotion – healing mana – The AddPotion parameter takes no data and has two attributes which give the specified number of healing potions and the specified number of mana potions to the owner of the NIS script.

• RemoveItem – index slot owner – The RemoveItem parameter removes an item of a specified numerical ID from the “owner” side’s hero. If a slot is specified (and no index), then any item from that slot is removed. The item slot IDs are 0 = helmet, 1 = shield/off-hand, 2 = body armour/cloak, 3 = weapon, 4 = ring/misc, 5 = boots, 6 = necklace, 7 = belt.

• SetCurse – slot item owner – The SetCurse parameter sets the curse of the numerical ID, specified by the parameter itself, to the specified item slot or to a specified item with a numerical ID defined by “item”. This item curse is given to the hero specified by “owner”.

• Perk – id owner – The Perk parameter gives a perk to an “owner” side’s hero for the duration of a battle. It can also be used to give the hero a trait, such as good or evil. The amount of that trait or perk to give is specified by the parameter itself. As perks have a single unlock, they are either 0 or 1, off or on. Traits are different in that they range from -5 to +5, as they are a scale. Traits are utilised for RPG dialogue purposes.

• Diplomacy – side modification faction sideloc factionloc max min – The Diplomacy parameter changes the diplomatic relations for the NIS script owner towards a racial “side” & “faction”. “modification” is the amount of positive or negative relations to give to that faction, and “max” and “min” specify the maximum and minimum total relations this parameter can reach (for example, if a hero has 5 relations towards Siria and the parameter gives them +15 relations, but the max is 10, then the hero will be given 5 relations for a total of 10 relations towards Siria). “sideloc” and “factionloc” overwrite the race “side” and “faction “ attributes with the owner of the location’s race and faction.

• Journal – important video – The Journal parameter adds a journal entry to the player’s campaign journal. The parameter itself takes the text for the journal message. “important” is a boolean value (1 = true, 0 = false) which tags the journal entry as being important with regards to the campaign and its story progression (this makes it stand out in the journal). “video” specifies whether or not there’s a video to be associated with the entry. The video must be in .bik format and must be located in the campaign/chapter’s Video folder. See the Campaign guide for more information.

• Bonus – The Bonus parameter awards the player a campaign bonus with the specific numerical ID specified by the parameter itself.

• PassTime – The PassTime parameter advances the campaign’s calender by a number of days specified by the parameter itself.

• SetTime – year – The SetTime parameter sets the campaign’s calender to a specific year and to a specific day in that year, as specified by the parameter itself.

• SetMonthOfThe – The SetMonthOfThe parameter sets the campaign ‘month of the x’ feature to a specific unit (so it becomes the month of that specific unit). The numerical ID of the unit is specified by the parameter itself.

• Relocate – The Relocate parameter changes the location of the player in the campaign to another location, as specified by the parameter itself. The name of the location to relocate the player to must be exact (e.g LOC_BARTONIA).

• LocOwner – id faction description paragraph1 paragraph2 seen – The LocOwner parameter changes the race and faction owner of a specific location. “id” is the name of the location, which must be exact (e.g LOC_SUNDEREDISLE). “faction” specifies which faction to turn the owner of the specified location to. “description”, if used, tells the game that the description of that location is to be changed. “paragraph1” and “paragraph2” specify the first and second paragraphs of text for the location’s new description. “seen” is a boolean value which can be 0 or 1, which sets whether or not that location is hidden or has been discovered (0 = hidden, 1 = discovered. Normally locations are only discoverable by travelling to a connected location, but this attribute allows you to reveal a location which is disconnected from any of the visited locations).

• TechResearch – side faction sideloc factionloc tier – The TechResearch parameter increases the campaign tech research level of a specified racial side and faction, by a percentage specified by the parameter itself. “sideloc” and “factionloc” overwrite the racial side and faction with the location’s own. “tier” overwrites the % and instead gives campaign tech level up to the specified keep tier level.

• RetinueTask – completion completionisopt location – The RetinueTask parameter initiates a retinue task of a numerical ID specified by the parameter itself. “completion” specifies the number of days the retinue task will take before being completed. “completionisopt” overwrites the number of days with the value stored in the same NIS script. “location” specifies where the task will be performed (this must be the location’s exact name, such as LOC_BARTONIA). If no location is specified, then the location will be where the player’s hero currently is.

• RetinueAct – cost costisopt level levelisopt name nameset race heading description – The RetinueAct parameter issues a prompt which asks the player whether or not they want to accept a specified unit/character into their retinue. “cost” if used, specifies a numerical cost in crowns that the unit will cost to hire. “costisopt” overwrites cost and instead uses the value stored in the same NIS script. “level” specifies the level of the unit and “levelisopt” overwrites that with the value stored in the same NIS script. “name” specifies the name of the unit and “nameset” overwrites that with a randomly generated one according to the nameset which belongs to that unit. “heading” is the text for the title of the offer window (which could be “An offer” for example). “description” is the text for the offer window (such as “someone offers to join your retinue”). The parameter itself takes the name of the unit or its 4-character ID.

• ActivateConquest – The ActivateConquest parameter marks the current campaign as a conquest one (such as the Warlords Battlecry 2 campaign). This parameter can be used to turn a classic campaign into a conquest one part way through. The parameter has no attributes, but it takes a boolean value (1 = on, 0 = off).

• LocConquering – id – The LocConquering parameter marks the battle as a conquest-deciding one, such as in the Warlords Battlecry 2 campaign. “id” is the name of the location to be conquered, such as “LOC_SUNDEREDISLE”. The parameter itself takes the player number associated with the campaign side that is conquering this location.

Functional Parameters

• Stage – The Stage parameter jumps to another parameter in the same NIS script which has the same stage condition as the parameter which called it. For example, the Stage parameter could specify “minotaursuccess”, which could be a condition for a message parameter (like

• Pause – The Pause parameter pauses the game. This is not typically needed in NIS script since the initiation of certain parameters like Message, automatically pause the game. However, as some parameters, such as Character, don’t pause the game, it is highly recommended to include the Pause parameter just afterwards to ensure that there is no time between the initiation of the NIS script and any Message parameters or other parameters that naturally pause the game.

• Video – The Video parameter plays a video of a filename specified by the parameter itself (such as videoname.bik). The video must be in .bik format and must be in the Video folder of the campaign/chapter. See the Campaign guide for more information.

• Act – The Act parameter initiates a campaign Action file, as specified by the parameter itself. The Action file must be in the same folder as the NIS script, and the name specified must be exact, but with no file extension.

• Playlist – The Playlist parameter begins playing music from a playlist specified by the parameter itself, including file extension. The playlist ini file must be located in the Music folder.

• Setopt – index showno abs – The Setopt parameter changes a NIS variable of a specific numerical “index” to a value specified by the parameter itself (NIS variables last for as long as that specific instance of NIS script does). “abs” gives the absolute value (which switches all negative values to positive ones, so -45 turns to 45).

• Addopt – index showno – The Addopt parameter adds the value specified by the parameter itself to the NIS variable of the associated “index”.

• Multiplyopt – index showno – The Multiplyopt parameter multiplies the NIS variable of a specific numerical “index” by a value specified by the parameter itself.

• Divideopt – index showno – The Divideopt parameter divides the NIS variable of a specific numerical “index” by a value specified by the parameter itself.

• Setbav – index showno abs – The Setbav parameter changes a scenario variable of a specific numerical “index” to a value specified by the parameter itself (scenario variables last for as long as the scenario being played). “abs” gives the absolute value (which switches all negative values to positive ones, so -45 turns to 45).

• Addbav – index showno – The Addbav parameter adds the value specified by the parameter itself to the scenario variable of the associated “index”.

• Multiplybav – index showno – The Multiplybav parameter multiplies the scenario variable of a specific numerical “index” by a value specified by the parameter itself.

• Dividebav – index showno – The Dividebav parameter divides the scenario variable of a specific numerical “index” by a value specified by the parameter itself.

• Setdopt – index1 index2 showno shownoline – The Setdopt parameter changes a double NIS variable of two different indexes to a value specified by the parameter itself.

• Adddopt – index1 index2 showno shownoline – The Adddopt parameter adds the value specified by the parameter itself to the double NIS variables of the associated indexes.

• Multiplydopt – index1 index2 showno shownoline – The Multiplydopt parameter multiplies the double NIS variables of the specified numerical indexes by a value specified by the parameter itself.

• Dividedopt – index1 index2 showno shownoline – The Dividedopt parameter divides the double NIS variables of specified numerical indexes by a value specified by the parameter itself.

• CrossVar – id – The CrossVar parameter sets a special chapter variable of the associated “id” to the value specified by the parameter itself. CrossVar values are special variables that carry-over between chapters.

• Setcon – type index isopt valueisopt – The Setcon parameter appraises a complex condition of a “type” of variable, such as opt or bav, of a certain “index” to make the “setcon” condition return true if that variable matches the value specified by the parameter itself. For instance, if there is an “opt” of “index” 1, and if the parameter is 3, then the “setcon” condition will return true if opt index 1 is equal to 3. “valueisopt” changes the setcon condition number specified by the parameter itself to the stored NIS variable.

• Showdopt – xstart ystart xend yend yendisopt xendisopt ystartisopt xstartisopt – The Showdopt parameter displays a grid of dopt values with which the player can interact with and play a mini-game.

For an example of how these parameters look when in use, take a look at the NIS files explained document in Warlords Battlecry The Protectors of Etheria\Manual\NIS files explained.pdf. This covers not only the basics, but also highlights how each parameter can be used, and how conditions work, among other useful pieces of information. Also, see these NIS files for an idea of what RPG dialogue and interactons look like:

Click here for part 2 of the Events and NIS script guide.

• Joe the Bartender (The Protectors Modding Team).
  Special thanks to Patrick for the helpful NIS files explained guide provided in the Manual folder of the release.