Why did I write this tutorial when there is one already by Turk?
There are several serious bugs in Turk's example, so I felt a better explanation was in order. If I could, I would have removed the old one.
Basic syntax:
Code:
spawn_army
faction <faction type> [sub_faction <subfaction_type>]
character <character name>, <character type>, age <age>, , x <x-coord>, y <y-coord>
; a list of 1-20 units, one per line
unit <unit type>, [soldiers <n>] [exp <0-9>] [armor <0-3>] [weapon_lvl <0-3>]
end
Parameters:
Parameters shown in <>'s are required. Parameters shown in []'s are optional and can be omitted. Anything after a semicolon is a comment.
faction type - faction types are defined in descr_sm_factions.txt
subfaction type - subfactions are defined in desc_rebel_factions.txt
character name - Must be a valid male name for the above faction from the descr_names.txt file. Character name must at the very least consist of a first name. Last name is optional.
character type - 'general' (i.e. captain) or 'named character'. A general is just a generic army captain. A named character has his own portrait and can be assigned traits/ancillaries (via additional commands).
age - from 16 to ... whatever the maximum is
x-coord and y-coord - coodinates on the strategy map where to spawn the army. To get coordinates under the current mouse position on the strategy map, open the Rome command shell by hitting the ~ key, then type in show_cursorstat and hit Enter.
unit type - from export_descr_unit.txt. The EDU entry for the unit type must have the faction in its ownershp line. Also, unless the unit has the mercenary_unit attribute in EDU, the corresponding entry in descr_model_battle.txt (DMB) must have texture and model entries for that faction. IMPORTANT: The example of this command given in CA's scripting documentation (i.e. the docudemon_commands.txt file) is incorrect - it's missing commas after unit types. These commas are required.
soldiers - where n is the number of soldiers to spawn for this unit.
- n is an absolute value and doesn't auto-adjust no matter what the unit size is set to in the game's options. You can spawn a unit with 240 soldiers even when unit size is set to small (60 soldiers)
- for the 1st (general's) unit, can be anywhere from 2 (soldier + general) to 240. For other units, 1-240.
- if you ask for 0, you'll still get 1 (+1 more, if it's the general's unit)
- if you ask for a number higher than the allowed max (value from the unit's soldiers line in EDU, multiplied by 4), only the max allowed number will actually spawn
exp - Experience. Same as in-game. 0 for fresh recruits and up to 9 for battle-hardened veterans.
armor - 0 for default, 1, 2, and 3 for bronze, silver, and gold armor upgrades correspondingly
weapon_lvl - same as armor, but for weapons
The maximum number of units per spawned army is 20 (full stack). The character leading it will be attached to the 1st unit on the list.
Unused/Ignored parameters:
Many (I would even say most) examples showing how to use the spawn_army command also include command, influence, management, and subterfuge parameters in the character line, like this...
Code:
spawn_army
faction slave
character Esugenos, named character, command 0, influence 0, management 0, subterfuge 0, age 40, , x 45, y 32
unit generic rebel general, exp 9 armour 3 weapon_lvl 3
end
These 4 parameters are left-overs from some old version of the game's engine. They don't cause any harm, but they don't do anything either, no matter what you set them to. They're useless, so I say just skip them altogether. If you want to increase these 4 attributes, you can do so by giving the character traits/ancillaries via console_command give_trait and/or console_command give_ancillary commands.
Spawning location rules:
1. You cannot spawn an army on any water tile, including river crossings (though you can reposition it to a river crossing after spawning)
2. If the coordinates where the army is supposed to spawn are already occupied by a diplomat, assassin, or spy, they will get out of the way to make room for the new army.
3. If there is another army at those coordinates, the new army will spawn right on top of it
4. If you spawn at the coordinates of a settlement, it will spawn on top of that settlement, but will not enter/attack it. Doesn't matter if the settlement is garrisoned or not, or if it's hostile/neutral/friendly.
5. The game will let you spawn an army on a ground type that's not normally accessible (a mountain peak, or dense forest), but even though it will spawn, it may not be able to move.
Warning about character-cloning CTDs:
According to research that has been discussed at length here (http://www.twcenter.net/forums/showthread.php?t=418396), spawning characters for the player faction doesn't cause CTDs, but spawning a character for an AI faction that has a family tree set up in descr_strat.txt can cause a CTD -- if the character is adopted into the ruling family, he will be cloned, and when either he or the clone eventually dies, the game will crash and you will not be able to continue the campaign.
Movement points:
Upon spawning, the army's movement point gage will be full.
Spawned armies and ambushing:
If you spawn an army in a forested area, it will not be able to ambush enemy until next turn. Though, you could spawn it on an adjacent tile and use the move command to have it march to a forested area, then it will hide and can ambush immediately.
Example of a complete script:
Here is a script that will spawn an army at the beginning of player's turn 10:
Code:
script
monitor_event FactionTurnStart FactionIsLocal
and I_TurnNumber = 10
; In case there is an Esugenos already in game, kill him off. Otherwise, you
; might end up with 2 (or more) characters with the same name
; running around, confusing the player. :)
console_command kill_character "Esugenos"
spawn_army
faction slave
character Esugenos, named character, age 40, , x 45, y 32
unit generic rebel general,
end
terminate_monitor
end_monitor
while I_TurnNumber < 9999
suspend_unscripted_advice true
end_while
end_script
What's wrong with Turk's example?
- Do not try to spawn an army during the slave turn. It will cause a CTD.
- You don't need to declare/set/check any counters to spawn armies. It's simply unnecessary. Any given turn number can only start once per faction.
- Remember, declaring a monitor is not the same as executing it. If you use the spawn_army command in a monitor_event/monitor_conditions block, the script must include a loop before the end_script line, or else it will simply exit and your monitor will be thrown away before the code in it has a chance to detect the corresponding event/conditions and be run.