The Protectors Mod

The Protectors mod

-NIS files explained-

1.Basics

Nis files are scripts that control a dialog scene event in a scenario. To make a nis file act at a certain time, go to the events section in the game’s editor and add a ‘Scene event’ event or a ‘Scene + show hidden’ event.

In the appropriate ‘Effects’ tab, simply type in the name of your nis file. DO NOT FORGET TO PUT THE SUFFIX OF THE FILE (.NIS) or the game will not read it. Note that your nis file will be detected only if it is in the Scenario folder of your game.

Next I will explain the contents of the nis file. They can be edited using any text editor, but make sure you save it with the ‘.nis’ suffix (and not ‘.txt’ or ‘.doc’). Here are the basic rules and observations:

Everything in the file is CaSe SeNsItIvE. Refer to the picture provided at the end of this document to see a sample/template.
All nis files must have the <NIS> tag at the beginning of the file, and closed at the end of it ( </NIS>).
If it is a dialog (and not a monolog of your hero), then we first must define the characters that participate in the discussion using the ‘Character’ tag. All attributes are obligatory.
All unit detecting tags (Move, Patrol, Message, Owner, etc.) have these optional attributes: id, owner, ishero. Some also have the charname attribute (as seen in picture at the end of the document). Also keep in mind that side one is owner=”0”, side two is owner=”1”, side three is owner=”2” and so on. Neutral is owner=”6”.
Tags which also require targets (Attack & Guard) have these optional attributes: targetid, targetowner, targetishero.
Attack and move tags have the additional attributes “speed” and “d”. The first one sets the speed of the ordered unit (defaulted if not mentioned), the second says that the unit should ignore everything else that is happening and accomplish its mission at all cost (direct/desperate)
Conditions can be placed on any tags except the Character and NIS ones. Conditions are the same as wbc3 original (evil, knight) plus the newly implemented ones from the choice tag (no1, no2, no3, no4), the flag ones (flag1on, flag2off), the ‘local and global variable greater than’ ones (var6gt2, varl1gt2). All of them can be interconnected with the ‘not’, ‘and’, ‘or’ operators.

There are some extra campaign only conditions (i.e. dialogues that happen on the world map). The ‘crowns greater than or equal to’ ones (crowns20), the ‘optional variable greater than’ ones (opt1gt2), the ‘optional variable greater than another optional variable’ ones (opt5gtopt1).

See the template below for more information.

The x,y coordinates can be found by placing a event on a map and look at its Condition Position. When using the Terrain tag, it is sufficient to choose a spot on the tile you wish to modify; it is not necessary to aim at the top left corner of the tile.
Units and buildings names are found in the System.xcr file. An example would be the Iceguard (case sensitive and always singular). If detecting the unit/building is not based on its name (ishero for instance) then type in ‘ANY’. DO NOT LEAVE the spot empty or the game will crash.
Terrain, PFX and Features codes are numbers that indicate their position in the editor’s list. For example, Blank Area terrain tile is ‘0’.
Location codes can be found in any Campaign.xcr file.
Portrait numbers can be found in the Heroes.xcr file.
Weather intensity numbers are as follows: 0-Dayfine; 1-Dayrain; 2-Nightfine; 3-Nightrain; 4-Dayheavyrain; 5- Nightheavyrain
Videos’ resolution MUST be 640x480 and .bik format. Use the RAD video tools (freeware) to do the conversion.
Putting the apostrophe symbol in a dialog is done by typing ‘'’. Other symbols are > (greater than or ‘>’) < &qt;(quotes) &name; (hero name) &day; (current day) and &year; (current year). Placing the actual symbols in the nis file and not their code might result in a crash.
Flags are set on by defaultwhen using the <Flag> command. To turn it off use the attribute off.
When adding units or buildings of owners that do not exist (have left the game or never joined) the defaulted side will be used (neutral).
Any action may have an optional attribute called “stage”. This is used by the Stage command to recognize the place where it needs to jump.
Attitude list is as follows: 0 – coward, 1 – stand ground, 2 – defensive, 3 – aggressive, 4 – rampant, 5 – scout. The guard attitudes can be replaced with the Guard command.
The <Perk> command always adds a value to the hero’s existing perk. Total negative values are the left side effects, positive the right side.

2.Actions

Below is a template of a nis file with all the commands or actions. Everything in RED is mandatory, green is optional.

WARNING! Do not copy-paste as the ”symbol differs from one text-editing application to another and the command will be simply be ignored by the game. I recommend using Notepad.

NIS
<Character id="1" portrait="6">Ellador</Character>
<Messagestage=”the beginning”character="1"owner=”0” ishero id=”123”Choose a number, ye' douche.</Message>
<Choice character="0"
a>One </a>
<b>I choose two.</b>
<c condition=”evil” hidden>I appear as an option only if you are evil.</c>
<d>Lucky four!</d>
eBonus five. </e>
f condition=”crowns500”You need 500 crowns to select me. </f>
</Choice>
<Choice2character="0"
a>yes </a>
<b>no.</b>
</Choice2
<Message character="1"condition="no1 and no11">You have chosen number one and said yes.</Message>
<Message character="1"condition="no1 and no12">You have chosen number one and said no.</Message>
<Message character="1"condition="no1 and evil">You have chosen number one, your evilness.</Message>
<Message character="1"condition="no1 and not evil">You have chosen number one.</Message>
<Message character="1"condition="no2">You have chosen number two.</Message>
<Message character="1"condition="no3 and bonus2">You have chosen number three and have bonus 2.</Message>
<Message character="1"condition="no4">You have chosen number four.</Message>
<Message character="1"condition="not no6">You did not choose number six by the way.</Message>
<Move x="123" y="123"owner=”0” ishero id=”123” speed=”4” dName or ANY</Move>
<Attack target="VictimName or ANY"owner=”0” ishero id=”123” targetowner=”0” targetishero targetid=”123”speed=”4” dMurdererName or ANY</Attack>
<Killowner=”0” ishero id=”123” Name or ANY</Kill>
<Screen x="123" y="123"</Screen>
<Video>videoname.bik</Video>
<Owner towner="0"to="1" id=”123”Name or ANY</Owner>
<Pause/
<AddFeature x="123" y="123">numbercode</AddFeature>
<RemoveFeature x="123" y="123"</RemoveFeature>
<AddPFX x="123" y="123">numbercode</AddPFX>
<RemovePFX x="123" y="123"</RemovePFX>
<PlayWAV>Bing.WAV</PlayWAV>
<MusicExtraGorgon.mp3</Music>
<Terrain x="123" y="123">terraincode</Terrain>
<Patrol x="123" y="123"owner=”0” ishero id=”123” Name or ANY</Patrol>
<Guard target="bossName or ANY"owner=”0” ishero id=”123” targetowner=”0” targetishero targetid=”123”guardianName or ANY</Guard>
<RemoveUnitowner=”0” ishero id=”123” Name or ANY</RemoveUnit>
<Screentoowner=”0” ishero id=”123” Name or ANY</Screento>
<AddUnit x="123" y="123" charname="charactername" xp="123" owner=”0” ishero id=”123”number="10"name</AddUnit>
<AddBuilding x="123" y="123" charname="charactername" owner=”0” ishero id=”123”name</AddBuilding>
<Weather>Intensitynumber</Weather>
<Stage>the beginning<Stage>
<Setvarglobal=”1” name=”variablename”4</Setvar>
<Addvarglobal=”1” name=”variablename “4</Addvar>
<Setoptindex=”1”showno=”Variable 1:” abs21</Setopt>
<Addoptindex=”1”showno=”Variable 1:” 7</Addopt>
<Setdopt index1=”1”index2=”3” showno=”Variable row1col3 :” shownoline=”1” 1</Setdopt>
<Adddopt index1=”1”index2=”3” showno=”Variable row1col3 :”shownoline=”1” 7</Adddopt>
<AddCompanionxp=”123” code=”AUAX”CharacterName</AddCompanion>
<RemoveCompanion>CharacterName</RemoveCompanion>
<Crowns>300</Crowns>
<Item>itemnumber</Item>
<Diplomacy side="13" modification="10"max="25" min=”-25”/>
<Journalimportant video=”intro.bik” Today I have learned how to use a NIS file.</Journal>
<Bonus>bonusnumber</Bonus>
<CrossVarid="0"1</CrossVar>
<PassTimenumberofdays</PassTime>
<Flag id="0"offcondition=”flag12on and flag2off”/>
RelocateLOC_BARTONIA</Relocate>
Attitude owner=”0” ishero id=”123attitude=”2”Name or ANY</Attitude
ProduceHeroSidenumber</ProduceHero>
<Setcon type="opt" index="1"isopt valueisopt3</Setcon>// if opt 1 equals 3 then setcon condition will be true
<Message character="1"condition="setcon">Optional variable 1 is indeed 3. Hurray!</Message>
<Message character="1"condition="not setcon">Opt variablae 1 is not 3. Booo.</Message>// works like an ‘else’
<Showdopt xstart="6" ystart="7" xend="8" yend="10"yendisopt xendisopt ystartisopt xstartisopt/>
<ResetGame/>
<GameSpeed>1</GameSpeed>
<Perk id="perknumber" owner=”0”numbervalue</Perk
<SetStartLocation x=”123” y=”123” owner=”0” /
<Damage x=”123” y=”123” radius=”5”owner=”0”damageammount</Damage>
<Actactindex</Act// act file must be in the current location
<UncoverHiddenMap x=”123” y=”123” radius=”5” />
</NIS

3.Conditions

Below is a list of conditions. All of them can be applied within any action tag and can be related to each other with and, or, not. Conditions marked with black are applicable to any .nis file, the ones with blue are for campaign only (when dialogue happens on the world map) and the ones with green for scenarios only (when dialogue happens on the battle map).

RACE (knight, dwarf, undead, barbarian, minotaur, orc, highelf, woodelf, darkelf, fey, darkdwarf, daemon, empire, ssrathi, swarm, plaguelord)
CLASS (warrior, chieftain, ranger, deathknight, dragonslayer, daemonslayer, thief, assassin, bard, merchant, priest, tinker, paladin, healer, druid, runemaster, shaman, elementalist, defiler, archmage, necromancer, pyromancer, summoner, alchemist, illusionist, icemage, lichelord, sage)
FLAG (flag0on, flag0off, flag1on, flag1off, …, flag15on, flag15off)
MISC (evil, good, mortal, immortal, wizard, warrior, priest, thief, rogue)
CHOICE (no1, no2, no3, no4, no5, no6, no11, no12, no13, no14. no15, no16)
CROWNS (crowns0, crowns10, crowns20, crowns30, crowns40, …, crowns190, crowns200, crowns250, crowns300, crowns400, crowns500, …, crowns900, crowns1000)
CROWNSDNO (crownsdno5, crownsdno10, crownsdno20, crownsdno30, crownsdno40, …, crownsdno190, crownsdno200, crownsdno250, crownsdno300, crownsdno400, crownsdno500, …, crownsdno900, crownsdno1000)
COMPANION (Robert, Setroth, Elana, Kaari, Gront, Kheldon, Paridian, Minos, Aelfwhine)
GLOBAL VARIABLE GREATER THAN OR EQUAL TO (var0gt0, var0gt1, …, var0gt10, var1gt0, var1gt1, …, var9gt10)
LOCAL VARIABLE GREATER THAN OR EQUAL TO (varl0gt0, varl0gt1, …, varl0gt10, varl1gt0, varl1gt1, …, varl9gt10)
GLOBAL VARIABLE EQUAL TO (var0eq0, var0eq1, …, var0eq10, var1eq0, var1eq1, …, var9eq10)
LOCAL VARIABLE EQUAL TO (varl0eq0, varl0eq1, …, varl0eq10, varl1eq0, varl1eq1, …, varl9eq10)
OPTIONAL VARIABLE GREATHER THAN OR EQUAL TO (opt0gt0, opt0gt1, …, opt0gt10, opt1gt0, opt1gt1, …, opt9gt10)
OPTIONAL VARIABLE EQUAL TO (opt0eq0, opt0eq1, …, opt0eq10, opt1eq0, opt1eq1, …, opt9eq10)
OPTIONAL VARIABLE GREATER THAN OR EQUAL TO OPTIONAL VARIABLE (opt0gtopt0, opt0gtopt1, …, opt9gtopt10)
DOUBLE OPTIONAL VARIABLE EQUAL TO (dopti0i0eq0, opti0i1eq1, …, opti0i1eq10, opti1i0eq0, opti1i0eq1, …, opti9i4eq10)
SETCONDITION (setcon)
BONUS (bonus0, bonus1, … , bonus19)
SPECIAL (melvincleggpayed, melvincleggignored,…)

4.Variables

Variables are a quantity that during a calculation is assumed to vary or be capable of varying in value. There are four types of variables in The Protectors:

-Global variables: these are applied on the whole world map and defined in the Global.var files of any campaign.xcr

-Local variables: these are applied only on the current location of your hero on the world map and are defined in locationname.loc files of any campaign.xcr

-Optional variables: these are applied and defined only within the current dialogue file -once the conversation is over, the variables are deleted.

5.Modifiers

Modifiers are portions of code that can be introduced at any time during a phrase to represent a previously calculated value. There are four types of modifiers in The Protectors:

-Global Variables: displays the current global variable value

Eg. <Message> I have advanced this much in the campaign: VAR0</Message>

-Optional Variables: displays the current optional variable value

Eg. <Message> Since we started talking, we know each other OPT0 per cent better.</Message>

-Random: displays a random number from the range defined with “min” and “max” attributes

Eg. <Message min=”1” max=”6”>My dice shows RAND</Message>

-Time: display current time in days (considering there are always 365 days in a year)

Eg. <Message>The elves began recording history TIME days ago.</Message>

You can also access current year and current day of the year with DAY and YEAR modifiers.

Eg. <Message>Today it is the year &year; and we are in day number &day;.</Message>

-Difficulty Number: display a number affected by campaign difficulty (considering the entered value available on easy)

Eg. <Message>I will take from you DNO-0500 crowns and will give you back only DNO00500 crowns back.</Message>

Notice that the number must always contain 5 digits/ minus symbol. A negative number would be increased, but a positive number would be decreased.

All of them can have the minus symbol to represent its negative (-TIME, -VAR2 etc.). Other than text display, they also work with the following commands: Setopt, Addopt, PassTime, Crowns.

6.Questions

If you have any more questions, please contact the modders via

Happy scenario-making!