An Intermediate Guide to Scripting

[Epistolary Richard]

Myrddraal worked out all the technical stuff, I just do the talking sloooowly with hand gestures bit.

But yes! Let us have some advanced scripting tutorials about the scripting in EB!

[Malrubius]

I'm going to need some, to keep up with you, LorDBulA, and The_Mark!

[SigniferOne]

Question guys, which I feel is a little silly but here it is nonetheless: how do you test if a character has a certain trait, and what level of the trait? I tried the following and it doesn't work:

monitor_event CharacterTurnStart TrueCondition
   if FactionType empire_west
      if Trait AgeTraitLevel1 = 1
         ; do some stuff
      end_if
   end_if
end_monitor

[Malrubius]

monitor_event CharacterTurnStart FactionType empire_west
      and Trait AgeTraitLevel1 = 1
         ; do some stuff
     
end_monitor

[SigniferOne]

Hmm, that's weird, I thought both "FactionType" and "Trait" were conditions, and thus not usable in monitor_event, but only in monitor_conditions, or "if" clauses?

[Malrubius]

Hmm, we have syntax like that in our EBBS background script, and it seems to work.

[alpaca]

That is because monitor_event in fact requires an event AND a condition.
If you don't want one, you have to use monitor_event EVENT TrueCondition or else the game will crash.

[SigniferOne]

Right, but then what could be the reason why isolating the conditions into their own "if" statements, e.g in my code above, doesn't work?

[octavius vatco]

excues me? does this command exist here?

"I_settlement_besiege"??

[Squid]

You have now asked this question in three different locations, two here at the org, and one at twcenter. The answer doesn't change no matter how many times you ask, it is still no.

[Bardo]

Now that I'm finishing my work with the scripts for lotr-tw, I would like to thank to Epistolary Richard and Myrddraal for all their reseraching about scripts and for this awesome guide. And I would like to share some info that I missed in this guide and could have saved me a lot of time.
Most of the info is already known by most of the scripters, it is just my list of notes about scripting. I know it is a bit late, and few people still seems working with rtw scripts, but just in case...
Maybe this post encourage to someone with more knowledge to make a "complete guide to scripting", or at least that other scripters share their tips here.

IMPLEMENTING
-The most important when you implement a "monitor_event" is to check the "Trigger requirements:" of the condition you want to use (docudemon_conditions.txt),
and verify that it is included in the "Exports:" of the event used to trigger the monitor (docudemon_events.txt).
Conditions starting by "I_" do not need requeriments from the event and so they can be used with if and while statements.
-The condition RandomPercent can be used without any requeriments, like all conditions starting by I_
-WorldwideAncillaryExists does not need any Trigger requirements (even when the docudemon_conditions.txt says character_record). I use the next syntaxis and it works as expected (I'm sure):

monitor_event PreBattlePanelOpen WorldwideAncillaryExists one_ring true
   and not WorldwideAncillaryExists lost_ring true
   ;code here
end_monitor

-The condition that triggers a "monitor_conditions" can not be changed inside the monitor, so it needs the command "terminate_monitor" to avoid being executed for ever.
If you want the monitor to be triggered more than once you need to use a "monitor_event".

monitor_conditions I_CompareCounter no = 1
   ;code here executed up to one time until you reload the script
   terminate_monitor
end_monitor

-The condition SettlementName uses the Name showed in the strat map (look at ...\text\region and settlement names.txt), not the internal name of the settlement like other commands related to settlements.
Note it does work with CharacterTurnEnd but does not with CharacterTurnStart (the later does not export the settlement)
-The event GeneralCaptureSettlement is triggered no matter the type of character: general, named character or family.
-Moving characters:
1) move: it uses the standard movement points of the character to try to reach the destiny. So it has to be used during the turn of the character you want to move, and it will not work if the character is far from the target possition (it is equal to select the character and click the right button over the target coordinates). If the character is the commander of his army, all the army will be moved, if not, only the character will move.
This is the only command that allows you to move a character in and out of a settlement or an army.
2) console_command move_character: In this case the character is teleported to the target possition, no matter the movement points or the availability of a path, but it does nothing if the character is not the commander of his army, or if the character is inside a settlement.
If the character is moved over an occupied tile (or over a city), the armies do not merge (nor enter into the city). In stead the moved army stand over them, and then you have to select them using the character browser, because sometimes it is not possible to click them directly.
This command sometimes makes the moved character invisible. It seems random, but related to characters teleported when they are sieging or hidden in forests, or in a occupied tile. However, this effect dissapears after reload and it do not cause ctds (that I know).
3) reposition_character: the same than move_character, but it could cause ctds if the character does not exist, and probably in some other cases too, I do not use it.

SUGGESTIONS
-When you are at the console command interface, if you press up-arrow you can see all the commands that have been executed previously, in the order they have been launched.
By using this with a script, you can check if monitors containing a console_command are working, and when they are triggered.
-use console_command toggle_fow and toggle_perfect_spy to view all the info about armies and settlements in the strat map.

CTD CAUSES
People think that scripts causes a lot of ctds and they are sometimes afraid to use them, but in fact there are very few scripting commands that can cause ctds, and most of them are related to mistakes in other files related to advices, buildings, units, trais...
These are the only ctd causes that I have ever found in my scripts:

1- advance_advice_thread Advice_Thread: when the thread name is wrong
2- spawn_army or spawn_character: with a wrong character name or wrong unit name
3- console_command create_unit Settlement "unit name" 1
if there is something wrong with the unit
4- console_command create_building Settlement building_name
if there is something wrong whit the building
5- console_command give_ancillary Character ancillary
if there is something wrong whit the ancillary
6- console_command give_trait Character Trait 1
if there is something wrong whit the trait
7- move or reposition_character cause ctds if the character does not exist (or is died). Better use console_command move_character that can not cause ctds.
8- to spawn admirals (with ships) could cause ctds when other ships try to attack them, because they are created as if they where land units, in stead of naval units.

That I know, it does not matter if you use a name that does not exist with other commands like kill_character or move_character, or if the name of the faction is wrong using diplomatic_stance, control, or add_money or the settlement name is wrong when you use add_population, capture_settlement... Only the commands listed above seems to cause ctds when they are wrong.
However, there are many commands I have never used, so other known ctd causes will be welcome.

NOT WORKING
-Prebattle event is not implemented
-I have been unable to use the console command "event <event_type> <opt:position>", as well as all console commands starting by list_ or test_ (at least using AlexanderTW)

DESIGNING
Since counters are not stored when you save and reload the game, we need some workarround to save script's state upon reloads. There are several options, both with pros and cons:
1)Buildings/plugins: condition checked from an event that exports the settlement. They can be created but not destroyed by script. They can be permanent if hinterland_buildings.
(console_command set_building_health Settlement building -1 does not destroy it)
2)Traits: condition checked from an event that exports the character_record. They can be created and removed by script, but they are not permanent since the characters can die.
3)Ancillaries: can be checked from ANY event using WorldwideAncillaryExists (except from trait triggers). They can be created by script, but the only way to destroy them is to kill the character. As traits, non permanent.

In our mod, we use a hidden city in the top-right corner with a special character who we can use to save a lot of info about the scripts: using buildings with the city, traits and ancillaries with the character (since we know his name we can kill and respawn him), and even changing and checking his possition in the map.
Very useful, but only recomended for heavy scripted mods :P

-To detect the owner for a certain retinue: the retinue should affect one Attribute of the character not affected by any other aspect of the game,
usually "SenateStanding", "PopularStanding", "Electability" (without senate) or "NavalCommand".
-The console_command "diplomatic_stance faction1 faction2 allied" does not change the attitude of one faction against the other, just the alliance agreement, so it is a bit useless to avoid attacks from the ai factions.
-To check that a certain character is placed near a certain position, without using settlements: you can try to move the target character to the target possition in the map, then wait for the movement, and then to check if the character has arrived to the destination, by using "not I_CharacterTypeNearTile" before the movement, and "I_CharacterTypeNearTile" after the movement. If the character has not arrive in this time is because he was not near that tile.
-The commands "wait" or "campaign_wait" do not stop the campaign, just the scripts, and they should not be used inside a monitor, nor during AI turn.
Also, it seems that script's variables are not updated correctly while the "wait" is called from the inside of an "if" sentence.


Some examples from our scripts, that could be useful for someone else

;**********************************************
; FORCE OCCUPY
; Avoid the human player to exterminate/enslave while playing certain factions: seleucid, macedon and thrace in this case
;**********************************************

script

declare_counter player
set_counter player 1
declare_counter scroll
set_counter scroll 0

monitor_event FactionTurnStart FactionIsLocal
   set_counter player 1
end_monitor
monitor_event FactionTurnEnd FactionIsLocal
   set_counter player 0
end_monitor

monitor_event ScrollOpened ScrollOpened loot_settlement_scroll
   if I_LocalFaction seleucid
      set_counter scroll 1
   end_if
   if I_LocalFaction macedon
      set_counter scroll 1
   end_if
   if I_LocalFaction thrace
      set_counter scroll 1
   end_if
end_monitor

monitor_conditions I_CompareCounter player = 1
   and I_CompareCounter scroll = 1
   set_counter scroll 0
   select_ui_element loot_settlement_occupy_button
   simulate_mouse_click lclick_down
   simulate_mouse_click lclick_up
end_monitor

while TrueCondition
end_while

script

;**********************************************
; GARRISON SCRIPT
;**********************************************

script

declare_counter City1Besiged
set_counter City1Besiged 0
declare_counter City2Besiged
set_counter City2Besiged 0
;...per settlement

monitor_event FactionTurnEnd FactionType [faction1]
and I_LocalFaction [faction1]

   if I_CompareCounter City1Besiged = 0
      and not I_SettlementOwner [city1] = [faction1]
      if I_CharacterTypeNearTile [faction1] general,  2 x1,y1
         set_counter City1Besiged 1
      end_if
      if I_CharacterTypeNearTile [faction1] family,  2 x1,y1
         set_counter City1Besiged 1
      end_if
   end_if
   if I_CompareCounter City1Besiged = 2
      and not I_CharacterTypeNearTile [faction1] family, 2 x1,y1
      and not I_CharacterTypeNearTile [faction1] general, 2 x1,y1
      set_counter City1Besiged 0
   end_if

   if I_CompareCounter City2Besiged = 0
      and not I_SettlementOwner [city2] = [faction1]
      if I_CharacterTypeNearTile [faction1] general,  2 x2,y2
         set_counter City2Besiged 1
      end_if
      if I_CharacterTypeNearTile [faction1] family,  2 x2,y2
         set_counter City2Besiged 1
      end_if
   end_if
   if I_CompareCounter City2Besiged = 2
      and not I_CharacterTypeNearTile [faction1] family, 2 x2,y2
      and not I_CharacterTypeNearTile [faction1] general, 2 x2,y2
      set_counter City2Besiged 0
   end_if
   ;...per settlement

end_monitor
;...a monitor per possible local faction

monitor_event SettlementTurnEnd SettlementName [city1-mapname]
   and I_CompareCounter City1Besiged = 1
   and GarrisonSettlementRatio < 0.5
      if I_SettlementOwner [city1] = [faction1]
         console_command create_unit [city1] "unit name" 4
         console_command add_money -2000       
         console_command add_population City -1500
      end_if
      if I_SettlementOwner [city1] = [faction2]
         console_command create_unit [city1] "unit name" 4
         console_command add_money -2000       
         console_command add_population City -1500
      end_if
      set_counter City1Besiged 2
      ;...an if per faction
end_monitor

monitor_event SettlementTurnEnd SettlementName [city2-mapname]
   and I_CompareCounter City2Besiged = 1
   and GarrisonSettlementRatio < 0.5
      if I_SettlementOwner [city2] = [faction1]
         console_command create_unit [city1] "unit name" 4
         console_command add_money -2000       
         console_command add_population City -1500
      end_if
      if I_SettlementOwner [city2] = [faction2]
         console_command create_unit [city1] "unit name" 4
         console_command add_money -2000       
         console_command add_population City -1500
      end_if
      ;...an if per faction
      set_counter City2Besiged 2
end_monitor
;...a monitor per settlement


while TrueCondition
end_while

end_script

;**********************************************
; CHECK CHARACTER POSSITION
; show_me script
;**********************************************

;(This script does work:)
script 

declare_counter Character_moved
set_counter Character_moved 0

   if not I_CharacterTypeNearTile faction named_character, 0 116,154
      set_counter Character_moved 1
      move Character, 116,154
   end_if

   campaign_wait 5

   if I_CharacterTypeNearTile germans named_character, 0 116,154
      and I_CompareCounter Character_moved = 1
      console_command give_ancillary Character ancillary
   end_if

end_script


;(This script do the same, but does not work when the wait is placed inside the if... weird)
script

   if not I_CharacterTypeNearTile faction named_character, 0 116,154
      set_counter Character_moved 1
      move Character, 116,154

      campaign_wait 5

      if I_CharacterTypeNearTile germans named_character, 0 116,154
         console_command give_ancillary Character ancillary
      end_if
   end_if

end_script

You can find all my scripts into this patch, so people do not need the whole mod if just interested in the scripts:
http://www.mediafire.com/?uzzwg0nemmz

[Dol Guldur]

Brilliant addendum Bardo. Thank you for posting - so many discover little things or find the best way of doing things and never both to post their findings which results in much lost time for those who follow the same path.

Kudos!

I hope someone does write a "Complete Scripting" guide - though it certainly will not be me ;)

[Aradan]

Great addition, indeed. Thx Bardo for that compilation of info!

[Monkwarrior]

In our mod, we use a hidden city in the top-right corner with a special character who we can use to save a lot of info about the scripts: using buildings with the city, traits and ancillaries with the character (since we know his name we can kill and respawn him), and even changing and checking his possition in the map.
Very useful, but only recomended for heavy scripted mods :P

I use the same system, the hidden city in one corner, but I found some little problems when saving and reloading the saved game. I've solved them (I think so) by using a "tricky" method that requires a double building system.

I use mainly scripts to issue missions for human player. But in some cases missions are simultaneous, and hence some type of selective detection method had to be implemented.

The problem was the succession of facts:
- Event in the player turn: counter signal 1
- Creation of building in the hidden city: rebel turn, counter signal 2
- New player turn: message to player and counter signal 3
- Reloading: detection of the buildings present in hidden city and messaged issued to the player to remember him/her the present mission.

If game was saved in between those three facts, there were problems with reloaded games, as the player didn't get the reward, or the message for the new mission was missing, etc because in some turn changes the only mark was the counter (lost in saving).

I don't know if this subject is interesting enough to post the method. If so, I will look for it (I have not the files in this computer) and post it here.

[Bardo]

Since counters can not be saved (this is something very important I missed in my notes...), I try to use them only between events where the player can not save the game, like between FactionTurnStart-CharacterTurnStart, or CharacterTurnEnd-FactionTurnEnd.

In your case, why don't you create the building in the player's turn:
- Event in the player turn: counter signal 1 = Creation of building in the hidden city during player turn
- New player turn: message to player and counter signal 3

I guess there are some other reason that forces you to have 3 events, in this case I'm interesting in your solution, just paste the code here if you find it.

[Monkwarrior]

Ok, I will try to explain the question in my poor English.

My scripts are based in a succession of missions and rewards. But it is important that missions are accomplished in the right order.

An example of the first mission in the carthaginian campaign.

I have a counter named switch, that serves only to show the game in which moment we are.
It starts at 100 (turn 0 or when reloaded)

declare_counter switch
set_counter switch 100

but it will be changed in the next turn when the first mission is issued.

	if I_TurnNumber = 0

		wait 1
		advance_advice_thread Mision1_Cartago_Thread no_dismiss
				wait 1
				select_ui_element advisor_portrait_button
				simulate_mouse_click lclick_down
				simulate_mouse_click lclick_up
		set_counter switch 0
		settlement_flash_start Saguntum

	end_if

Then we have the conditions for mission success. A first fake building is created at the moment. Because of the overlapping of messages, the success message is issued to the player when the loot settlement scroll is closed.

	monitor_event GeneralCaptureSettlement FactionType carthage
		and SettlementName Saguntum

		settlement_flash_stop Saguntum
		console_command add_money 30000
 		console_command diplomatic_stance romans_julii carthage war
		console_command create_building Aquincum monument_victory_minor1
		set_counter switch 1

		terminate_monitor
	end_monitor

	monitor_event ScrollClosed loot_settlement_scroll
		and I_CompareCounter switch = 1

		advance_advice_thread Exito_Mision1_Cartago_Thread no_dismiss
			wait 1
			select_ui_element advisor_portrait_button
			simulate_mouse_click lclick_down
			simulate_mouse_click lclick_up
		set_counter switch 0

		terminate_monitor
	end_monitor

In this way it will be sure that we have a fixed point if player saves game in that moment.
If he follows playing, the script checks if this building exists to issue the message for the second mission.

	monitor_event SettlementTurnStart SettlementName Aquincum
		and SettlementBuildingExists = monument_victory_minor1
		and not SettlementBuildingExists = milestone1
		and not SettlementBuildingExists = monument_victory_minor2
		and not SettlementBuildingExists = monument_victory_minor3
		and not SettlementBuildingExists = monument_victory_minor4
		and not SettlementBuildingExists = monument_victory_major
		and I_CompareCounter switch = 0

		set_counter switch 11

		terminate_monitor
	end_monitor

	monitor_event FactionTurnStart FactionType carthage
		and I_CompareCounter switch = 11

		advance_advice_thread Mision2_Cartago_Thread no_dismiss
				wait 1
				select_ui_element advisor_portrait_button
				simulate_mouse_click lclick_down
				simulate_mouse_click lclick_up
		console_command create_building Aquincum milestone1
		set_counter switch 0

		terminate_monitor
	end_monitor

The second fake building prevents this messsage to be issued for a second time.

Let's see now what happens if the player loads a saved game. The switch counter will be at 100, and in the slave turn the presence of the fake buildings will be checked.

	monitor_event SettlementTurnStart SettlementName Aquincum
		and not SettlementBuildingExists = monument_victory_minor1
		and not SettlementBuildingExists = monument_victory_minor2
		and not SettlementBuildingExists = monument_victory_minor3
		and not SettlementBuildingExists = monument_victory_minor4
		and I_CompareCounter switch = 100
		and I_TurnNumber > 1

		set_counter switch 101

	end_monitor

	monitor_event FactionTurnStart FactionType carthage
		and I_CompareCounter switch = 101

		advance_advice_thread Recuerdo_Mision1_Cartago_Thread no_dismiss
				wait 1
				select_ui_element advisor_portrait_button
				simulate_mouse_click lclick_down
				simulate_mouse_click lclick_up
		settlement_flash_start Saguntum
		set_counter switch 0

	end_monitor

As no building is present, the script launches a message to remember the first mission to human player.

Perhaps there would be a simpler method to do it, but it was the only way I found to prevent missing messages to the human player.

[Bardo]

If there is an easier way, I don't know it. Afaik,The only way to prevent a message from being showed again is to remember it with a building/trait. The same for the mission success, so you need the 2 fake buildings.
Thank you for explain it, it is very useful to understand how to use buildings to save scripting information.