How-to: Add a background script to your mod
First, a bit of terminology:
campaign script - A script called at the end of the descr_strat.txt file. This script only runs once, when a new campaign is first started. Saving/loading the game is disabled while this type of script runs, so it's a good idea to keep this type of script short, only using it for basic initialization and to kick off a background script. This is the type of script used for the Sons of Mars tutorial campaign in vanilla RTW.
background script - This type of script is started via an advice thread and, just like the name suggests, runs in the background. The 2 biggest advantages offered by background scripts are: 1) Being able to save/load the game while the script is running, and 2) Being able to restart the script after loading a saved game. This type of script is often also referred to as 'show me' scripts, due to the old method of starting such script, which required clicking the advisor 'Show me how' button. This type of script is used to add features like 4-turns-per-year and opens the way to a multitude of other possibilities, including scripted missions, spawning armies, and much more. A background script keeps running until you exit the game (or shut it down manually - more on that in the example below).
on-demand script - This type of script is used to run a small, self-contained piece of code. Once the code has been run, the script terminates. For example, some mods include a script that you can run before making a diplomatic offer that will force the AI to accept it. This type of script is also started via an advice thread and is usually triggered by pressing one of the less-frequently used buttons in the UI. For example, the '?' button in the Help scroll.
Adding a background script
This will guide you through all the steps of adding a background script.
You must complete at least the instructions in sections I & III before it will work. Section II is optional, but is usually good to include to reduce the amount of clicking the player has to do. Section IV is just additional information to help you get started with scripting.
Section I: Setting up an advice thread
1. Add a new thread to export_descr_advice.txt:
The On_display line creates an association between this advice thread and a script specified on it. The script will run automatically as soon as the adviser text box opens. If adviser is set to voice-only, the script will run automatically when the advice thread is triggered/advanced.Code:;------------------------------------------ AdviceThread BackgroundScriptThread GameArea Campaign Item BackgroundScriptItem1 Uninhibitable Verbosity 0 Threshold 1 MaxRepeats 0 RepeatInterval 1 Attitude Normal Presentation Default Title BackgroundScriptTitle1 On_display scripts\show_me\background_script.txt Text BackgroundScriptText1
2. At the end of the export_descr_advice.txt file, add the following triggers for the above advice thread.
These triggers will be used to restart the script after loading a saved game. When you load a saved game, the first time any of these are triggered, the advisor portrait will come up. Click on it once to restart the script.Code:Trigger background_script_trigger_1 WhenToTest ButtonPressed Condition ButtonPressed faction_button AdviceThread BackgroundScriptThread 1 ;------------------------------------------ Trigger background_script_trigger_2 WhenToTest ButtonPressed Condition ButtonPressed construction_button AdviceThread BackgroundScriptThread 1 ;------------------------------------------ Trigger background_script_trigger_3 WhenToTest ButtonPressed Condition ButtonPressed recruitment_button AdviceThread BackgroundScriptThread 1 ;------------------------------------------ Trigger background_script_trigger_4 WhenToTest SettlementSelected AdviceThread BackgroundScriptThread 1
3. Add the following lines at the end of the text\export_advice.txt file:
Section II: Running the background script automatically when a new campaign startsCode:{BackgroundScriptTitle1}Background Script {BackgroundScriptText1}Script started.
1. Add the following at the very end of descr_strat.txt:
This uses a campaign script to fire off the background script.Code:script campaign_script.txt
2. In the same folder with the descr_strat.txt file for your mod, create a new file called campaign_script.txt (our campaign script) and put these lines into it:
Section III: Creating the script - What every script should haveCode:script wait 1 advance_advice_thread BackgroundScriptThread wait 1 select_ui_element advisor_portrait_button simulate_mouse_click lclick_up end_script
1. In the scripts\show_me folder, create a new file called background_script.txt <-- This is the file referenced by the On_display line in the advice thread in Section I. Traditionally, everyone puts their scripts into scripts\show_me, but you can put it anywhere you like and call it anything you want, as long as you update the On_display line to point to it.
2. What to put into the script file:
Section IV: Learning Scripting - Where to go from hereCode:script ; Anything following a semicolon is a comment. ; Remove the adviser portrait from screen. select_ui_element advisor_dismiss_button simulate_mouse_click lclick_up ; Wait for it to go away. while I_AdvisorVisible end_while suspend_unscripted_advice true ; Open the adviser message bubble automatically whenever advance_advice_thread is called. ; I recommend using this method instead of the select_ui_element + simulate_mouse_click approach. ; Do NOT mix both methods, though, or the advisor will show and then immediately close before ; you get a chance to read the text. declare_show_me ; Very useful for debugging - uncomment to use ;console_command toggle_perfect_spy ;;; ;;; --- Forced shutdown --- ;;; ;;; Press 'Esc' on the campaign map, then click on the '?' button in the ;;; menu scroll to terminate the script. ;;; ;;; When would this be useful? -- When you are already in a game and ;;; exit back to the main menu to restart the campaign, or reload a saved ;;; game, RTW does not automatically terminate the script, so you have ;;; to do it yourself. If you leave the old script running, you'll have all ;;; sorts of weird problems with the script in the new game. ;;; monitor_event ScrollAdviceRequested ScrollAdviceRequested end_game_scroll terminate_script end_monitor ; Handle saved game reloads monitor_event GameReloaded TrueCondition terminate_script end_monitor ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; This is where to put your own code ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; For example, this will give you 1 gold at the beginning of every turn monitor_event FactionTurnStart FactionIsLocal console_command add_money 1 end_monitor ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; End of your code ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; Spin forever - Do not let the script terminate or any monitors you have set up will immediately get thrown away. ; In M2TW scripts, this loop is replaced by the wait_monitors command. Unfortunately, this command is not available in RTW. while I_TurnNumber < 99999 suspend_unscripted_advice true end_while end_script
1. Other resources
Recommended reading:
- Beginning Guide to Scripting
- Intermediate Guide to Scripting
- Check out other tutorials in the parent forum
Referrence materials:
- Unofficial scripting documentation (updated for BI) - Released by Jerome Grasdyke (lead developer at Creative Arts) back in Sep'05
- Available UI elements that can be accessed via scripting
Where to ask for advice:
2. A few notes to help you with your scripting:
- The following commands do not work inside a monitor_event block: wait, campaign_wait, battle_wait, while, and nested monitor_event/monitor_conditions blocks. If you try to use them, your script will freeze.
- Most scripting commands and conditions use objects exported by events as an implied parameter and thus only work in the context of a monitor_event block. The type of object expected by the command/condition must match the type of one of the objects exported by the monitored event, or they won't work. To give you some examples...
This works, because FactionTurnStart exports the faction object, needed for the FactionIsLocal condition:
This does not work, because FactionTurnStart does not export a character object:Code:monitor_event FactionTurnStart FactionIsLocal console_command add_money 1 end_monitor
- An exception to the above are Independent commands (commands that start with "I_") and console commands, because parameters for these commands are either explicitly named objects (i.e. specific characters/settlements/etc.), or they do not require parameters.Code:monitor_event FactionTurnStart CharacterIsLocal console_command add_money 1 end_monitor
- Always, always, always have -show_err in your shortcut's target line!!!
- Errors in console_command lines never produce any error messages and never cause CTDs. They're just quietly ignored.
- Other errors, depending on how severe they are, can cause a CTD or a pop-up dialog box with an error message when shutting down the game.
- Some commands can freeze the game completely, so it won't respond at all, even to Alt-F4. I found that out first-hand when I tried to add the following code (don't try this at home!):
So, don't do it!Code:monitor_event CharacterSelected CharacterIsLocal call_object_shortcut hud_select_prev_item_cycle end_monitor
- Clicking on an army that's inside a settlement does not generate a CharacterSelected event
- It's only possible to use scripting to move field armies/characters. AFAIK, it does not work on armies/characters that are inside a settlement.
- To be able to take full advantage of all the possibilities scripting offers, you should become familiar with a few other areas of modding. In particular, having a good understanding of these will make you a much more effective scripter: descr_strat.txt, advice threads, traits & ancillaries, units (EDU/DMB) and buildings (EDB).
- Unlike M2TW, counter values are NOT saved when a game is saved. This means that you'll have to use other means to keep track of important information that you'll need when the script is restarted. The most common ways are using traits (especially hidden traits), ancillaries, and buildings (EDB).
- In M2TW, you don't have to create a separate background script because the campaign script restarts automatically when you load a saved game.
- Advice thread counter is incremented when you click on the advisor portrait to open the text bubble.
- The AbandonShowMe event is generated when you dismiss the advisor.
- The I_WonBattle condition works when used with a "normal" faction, but does not with the special slave/rebel faction.
ps: Feel free to discuss here or at .org (http://forums.totalwar.org/vb/showthread.php?t=104133)
Reply With Quote
... because it seems it is possible to relaunch the scripts automatically after reloading, without the trick of voice-only adviser.
Although I would love to be wrong
Originally Posted by HouseOfHam
