The use of destroy_units in the campaign script

[Gorrrrrn]

destroy_units
-------------

This is quite a powerful command in the wrong hands.

However with some care it can be a useful tool, especially for AI armies.

Here's three sample uses - you can clone for all relevant factions in your mod.

They are for the AI, rather than human players, but you can include them by omitting the "not FactionIsLocal"

1) Disbanding crusading / jihadi units after a crusade ends.

Here is an example:

monitor_event FactionTurnStart not FactionIsLocal
and FactionType aragon
and I_TurnsSinceLastCrusade = 3
destroy_units aragon, crusading_unit
end_monitor

As you can see the command requires a faction and attribute and the "crusading_unit" isn't part of the normal attribute list.

However, there's nothing stopping us adding to the attributes, providing we don't use anything that might cause confusion to the game engine.

To choose which units should qualify go the descr_mercenaries.txt file - probably in your campaign folder - and check to see which have the crusading qualifier. Add the relevant "crusading_unit" (or "jihad_unit") attribute to those unit entries in the EDU and you're ready to go.

The rationale here is that the AI can get lumbered with units it can't replenish, which take up space that would be better used with units that can be replenished after battles. (Especially if they are sucessful target garrison units.) Also those armies that fail to make it to the crusade / jihad target can spend a long time getting back home - if they ever do. All soak up upkeep for no reward for the AI. Even if this doesn't remove all the units in such armies it should make then easier to destroy

----

2) Disbanding mercenary units the AI can't afford to keep.

Here is an example;

monitor_event FactionTurnStart not FactionIsLocal
and FactionType aragon
and not I_CrusadeInProgress
and Treasury < 25,000
destroy_units aragon, generic_mercenary_unit
end_monitor

Again this version is for the AI factions.

We add the bit about a crusade (or jihad) not being in progress to allow AI Factions to keep recruited mercenary units en route to targets (as these won't be costing the AI any upkeep.)

The value for Treasury you can set to whatever value you think is best for your Mod.

This time we are using the new attribute "generic_mercenary_unit". Aagin not one currently in the EDU, so you add to relevant units.

Note some Mods use mercenary_unit to cover Area of Recruitment units and we don't want to include those, so you have to be careful which mercenary units you give the attribute to.

Hopefully this will help AI factions balance their books better- the AI seems better at deciding what to recruit as opposed to what it can afford in terms of recurring upkeep costs.

----

3) Disbanding obsolete units.

Here is an example:

monitor_event FactionTurnStart not FactionIsLocal
and FactionType aragon
and I_TurnNumber > 320
destroy_units aragon, obsolete_by_1260
end_monitor

Many Mods, especially those with long time spans, put date limits on when certain units can be recruited. However, there's nothing then to clear up all the bits and pieces of units that get left once the recruitment time has ended.

Again alter the dates and turns to suit your particular Mod.

The one above is for a 2 TPY Mod, starting in the year 1100. The units stop being recruitable around 1210 - 1215. We give the AI plenty of time to get lots of usage out of the units, but by 1260 any recruits would be past retirement age so it's time to disband what's left of any remaining units.

So you check in the EDB this time to see what conditions are put on recruiting units. Cross-reference with the descr_events.txt file, if the conditions relate to events. (Most do.) You can also check the descr_mercenaries.txt file to see if which mercenary units also have date limited recruitment. It's probably best to limit the attribute "obsolete_by_xxxx" to a few dates and apply them across the board rather than try work out different dates for every unit / faction combination.

Here the hope is that the AI will be encouraged to recruit more modern units to replace the disbanded ones. Which should give the human player a better gaming experience. Possibly.

----

Here's a simple way to remove unwanted pirate ships.

add pirate_ships to the pirate ship attributes.

then either:

monitor_event FactionTurnEnd FactionType slave
and I_TurnNumber = 50
destroy_units, slave, pirate_ships
terminate_monitor
end_monitor

and clone for the required turns

or

monitor_event FactionTurnEnd FactionType slave
destroy_units, slave, pirate_ships
end_monitor

to remove them at the end of the slave turn throughout the game.
----

I am sure people can come up with even better uses for the command.

(Maybe if the FactionLeader offends the nobility, they go on strike and leave the army? using the knight attribute.)

(Mods -feel free to move tutorials if this is better placed there.)

[Darkstar]

Very useful stuff. Can you talk more about adding new attributes? I could see this being very useful for something I'm working on.

+rep

[Tsarsies]

Nice work Rozanov... I like the last sample the best. I would like to reinforce the point that those units that are given the attributes have to be selected very carefully. If the AI was able to recruit the unit with (crusading_unit) attribute 'outside' a crusade, it will cause major issues. The Last 2 examples are brilliant however and will surely aid the AI's economy. +Rep. Brilliant work.

@Darkstar
You simply add an attribute in the attribute line, its as simple as writing text. The attribute does nothing until called for in script. I actually suggested this a long time ago but it was dismissed due to to it having no other use other then in a script...but, script is powerful and alot of people dont realize what can be done with it.

[Darkstar]

@Darkstar
You simply add an attribute in the attribute line, its as simple as writing text. The attribute does nothing until called for in script. I actually suggested this a long time ago but it was dismissed due to to it having no other use other then in a script...but, script is powerful and alot of people dont realize what can be done with it.

Great, that's exactly what I want to use it for.

My idea for this is that I have two separate factions, each led by a brother. If one brother dies I want his faction to basically dissolve with everything going over to the other brother. However, I thought this was too unbalanced using the give_everything command. The destroy_units plus a new attribute will allow me to selectively destroy units before using the give_everything command so only a handful of units are transferred over to the new faction.

Thanks again to both. I would +rep but it won't let me give you any more right now.

[Taiji]

Good job Rozanov, nice scripts, and good ideas too +rep

edit:

Tiny (almost offtopic) point of interest about the original mercenary_unit attribute: It forces all factions to use the same skin, the 'merc' skin. Hence apparent usefulness in AoR work.

[Gorrrrrn]

Hi T.

. If the AI was able to recruit the unit with (crusading_unit) attribute 'outside' a crusade, it will cause major issues

Yes you need to ONLY select the units which can be recruited during a crusade.

It is possible that you can make any unit a "crusading" unit (or "jihad" unit for that matter.) which could be recruited elsewhere as well.

I've omitted Crusader States from the factions it applies to in my Mod, in case they can recruit the current units (from RC/RR / SS6.2) - and anyway if they do pick some up, there's no harm in them keeping them as it seems appropriate.

Currently it's just the religious units (pilgrims, religious fanatics, flagellants) plus crusader knights, serjeants. Plus Ghazis and Mutatawwi'a for islamic factions

But yes - use with care - even now I'm not certain which units should be classed as "generic_mercenary_unit" - for now it's any owned by slave faction and possibly a few others.

More ideas welcome!

[TNZ]

Do you need to use a pre-existed unit attribute with the ‘destroy_units’ command or can you just make a new attribute, such as ‘garrison_unit’, and then add that to a unit in the export_descr_unit file?

My idea is to make a garrison script using the ‘create_unit’ and ‘destroy_units’ commands, something like this:

Spoiler Alert, click show to read: 

declare_counter has_garrison_unit

	monitor_event FactionTurnStart FactionType milan
		and IsFactionAIControlled
 		if I_UnitExists scotland Garrison Sword
		set_counter has_garrison_unit 1
	end_if
 		if I_UnitExists scotland Garrison Spear
		set_counter has_garrison_unit 1
	end_if
		if I_UnitExists scotland Garrison Bow
		set_counter has_garrison_unit 1
	end_if
		I_CompareCounter has_garrison_unit = 1
		destroy_units scotland garrison_unit
		set_counter has_garrison_unit 0
	end_monitor

	monitor_event FactionTurnEnd FactionType milan
		and IsFactionAIControlled
		and I_SettlementOwner Gap-of-Rohan = milan
		create_unit Gap-of-Rohan, Garrison Sword, num 4, exp 0, arm 0, wep 0
		create_unit Gap-of-Rohan, Garrison Spear, num 2, exp 0, arm 0, wep 0
		create_unit Gap-of-Rohan, Garrison Bow, num 3, exp 0, arm 0, wep 0
	end_monitor

I see this as a way to get around some of the problems garrison scripts have, such as the inability of the player to see how many units will actually be defending a settlement before he besiege it, and the fact that a player can get around the script just by attacking a unit next to the settlement. Not to mention the impact theses unit must have on an AI faction’s economy.

[SigniferOne]

Woah, super +rep!

Can you provide the syntax for adding attribute?

[Gigantus]

Theoretically it should be possible to create units with a garrison script that can otherwise not be recruited (unavailable hidden_resource). If these units have a certain attribute, then the garrison can be 'dissolved' once the siege has ended.

I have been thinking about this as it has been a bone of contention for me that a bankrupt AI has an endless supply of units as long as the siege isn't successful. Especially annoying when a different AI faction comes with a four unit stack to siege the apparent 1 unit garrison.

[SigniferOne]

That's an excellent application! They don't even have to be unrecruitable units, just a variant of the normal units but with a label. What's the syntax for assigning the label?

[Darkstar]

That's an excellent application! They don't even have to be unrecruitable units, just a variant of the normal units but with a label. What's the syntax for assigning the label?

If I understand Tsarsies post correctly you just need to add the label to the attribute line. You can use whatever text you want.

[TNZ]

I was hoping to use a script, similar to the one I posted, to provide garrison units for AI controlled fort in the Kingdoms of the Isles mod. But I don’t see a good way to determine fort ownership.

[Darkstar]

I was hoping to use a script, similar to the one I posted, to provide garrison units for AI controlled fort in the Kingdoms of the Isles mod. But I don’t see a good way to determine fort ownership.

I've never used this command but could you do something with I_FactionNearTile?

I_FactionNearTile romans_julii 0 48,30

I'm not sure if 0 is a valid distance in squares.

[Gorrrrrn]

The 0 is the distance from the square (so 0 = the square itself.)

you can check to see if the fort is garrisoned using IsFortGarrisoned condition.
I presume you then use the I_FactionNearTile condition as above.

Fort ownership can be tricky to determine - slave forts can stay that way even after the region is captured if nobody else claims them.
if a fort is captured it stays with the capturing faction (as long as that faction exists) until it is captured by another faction.
if the capturing faction is destroyed it goes back to slave faction.
If the regional settlement falls the garrison in situ remains until booted out - or it leaves of its own accord.

putting garrisons in at the start of the game is easy enough, I usually let the AI decide whether to garrison or not after that.

[TNZ]

Here is my first attempt at a script that can hopefully determine fort ownership:

Spoiler Alert, click show to read: 

declare_counter aberdeen_fort_one_scotland
declare_counter aberdeen_fort_two_scotland
declare_counter aberdeen_fort_one_denmark
declare_counter aberdeen_fort_two_denmark
declare_counter aberdeen_fort_one_normans
declare_counter aberdeen_fort_two_normans
declare_counter aberdeen_fort_one_portugal
declare_counter aberdeen_fort_two_portugal
declare_counter aberdeen_fort_one_sicily
declare_counter aberdeen_fort_two_sicily
declare_counter aberdeen_fort_one_hungary
declare_counter aberdeen_fort_two_hungary
declare_counter aberdeen_fort_one_saxons
declare_counter aberdeen_fort_two_saxons
declare_counter aberdeen_fort_one_hre
declare_counter aberdeen_fort_two_hre
declare_counter aberdeen_fort_one_spain
declare_counter aberdeen_fort_two_spain
declare_counter aberdeen_fort_one_russia
declare_counter aberdeen_fort_two_russia
declare_counter aberdeen_fort_one_venice
declare_counter aberdeen_fort_two_venice
declare_counter aberdeen_fort_one_poland
declare_counter aberdeen_fort_two_poland

;###### Fort Ownership At Game Start #######

	monitor_event PreFactionTurnStart FactionIsLocal
		and I_TurnNumber = 0
		set_counter aberdeen_fort_one_scotland 1
		set_counter aberdeen_fort_two_scotland 1
	terminate_monitor
	end_monitor

;###### Fort Ownership #######

	monitor_event GeneralCaptureResidence AgentType >= general
		if I_FactionNearTile scotland 0 232,414
		set_counter aberdeen_fort_one_scotland 1
	end_if
		if I_FactionNearTile scotland 0 202,409
		set_counter aberdeen_fort_two_scotland 1
	end_if
		if I_FactionNearTile denmark 0 232,414
		set_counter aberdeen_fort_one_denmark 1
	end_if
		if I_FactionNearTile denmark 0 202,409
		set_counter aberdeen_fort_two_denmark 1
	end_if
		if I_FactionNearTile normans 0 232,414
		set_counter aberdeen_fort_one_normans 1
	end_if
		if I_FactionNearTile normans 0 202,409
		set_counter aberdeen_fort_two_normans 1
	end_if
		if I_FactionNearTile portugal 0 232,414
		set_counter aberdeen_fort_one_portugal 1
	end_if
		if I_FactionNearTile portugal 0 202,409
		set_counter aberdeen_fort_two_portugal 1
	end_if
		if I_FactionNearTile sicily 0 232,414
		set_counter aberdeen_fort_one_sicily 1
	end_if
		if I_FactionNearTile sicily 0 202,409
		set_counter aberdeen_fort_two_sicily 1
	end_if
		if I_FactionNearTile hungary 0 232,414
		set_counter aberdeen_fort_one_hungary 1
	end_if
		if I_FactionNearTile hungary 0 202,409
		set_counter aberdeen_fort_two_hungary 1
	end_if
		if I_FactionNearTile saxons 0 232,414
		set_counter aberdeen_fort_one_saxons 1
	end_if
		if I_FactionNearTile saxons 0 202,409
		set_counter aberdeen_fort_two_saxons 1
	end_if
		if I_FactionNearTile hre 0 232,414
		set_counter aberdeen_fort_one_hre 1
	end_if
		if I_FactionNearTile hre 0 202,409
		set_counter aberdeen_fort_two_hre 1
	end_if
		if I_FactionNearTile spain 0 232,414
		set_counter aberdeen_fort_one_spain 1
	end_if
		if I_FactionNearTile spain 0 202,409
		set_counter aberdeen_fort_two_spain 1
	end_if
		if I_FactionNearTile russia 0 232,414
		set_counter aberdeen_fort_one_russia 1
	end_if
		if I_FactionNearTile russia 0 202,409
		set_counter aberdeen_fort_two_russia 1
	end_if
		if I_FactionNearTile venice 0 232,414
		set_counter aberdeen_fort_one_venice 1
	end_if
		if I_FactionNearTile venice 0 202,409
		set_counter aberdeen_fort_two_venice 1
	end_if
		if I_FactionNearTile poland 0 232,414
		set_counter aberdeen_fort_one_poland 1
	end_if
		if I_FactionNearTile poland 0 202,409
		set_counter aberdeen_fort_two_poland 1
	end_if
	end_monitor

;###### Reset Fort Ownership #######

	monitor_event PreFactionTurnStart FactionIsLocal
		if I_NumberOfSettlements scotland <= 0
		set_counter aberdeen_fort_one_scotland 0
		set_counter aberdeen_fort_two_scotland 0
	end_if
		if I_NumberOfSettlements denmark <= 0
		set_counter aberdeen_fort_one_denmark 0
		set_counter aberdeen_fort_two_denmark 0
	end_if
		if I_NumberOfSettlements normans <= 0
		set_counter aberdeen_fort_one_normans 0
		set_counter aberdeen_fort_two_normans 0
	end_if
		if I_NumberOfSettlements portugal <= 0
		set_counter aberdeen_fort_one_portugal 0
		set_counter aberdeen_fort_two_portugal 0
	end_if
		if I_NumberOfSettlements sicily <= 0
		set_counter aberdeen_fort_one_sicily 0
		set_counter aberdeen_fort_two_sicily 0
	end_if
		if I_NumberOfSettlements hungary <= 0
		set_counter aberdeen_fort_one_hungary 0
		set_counter aberdeen_fort_two_hungary 0
	end_if
		if I_NumberOfSettlements saxons <= 0
		set_counter aberdeen_fort_one_saxons 0
		set_counter aberdeen_fort_two_saxons 0
	end_if
		if I_NumberOfSettlements hre <= 0
		set_counter aberdeen_fort_one_hre 0
		set_counter aberdeen_fort_two_hre 0
	end_if
		if I_NumberOfSettlements spain <= 0
		set_counter aberdeen_fort_one_spain 0
		set_counter aberdeen_fort_two_spain 0
	end_if
		if I_NumberOfSettlements russia <= 0
		set_counter aberdeen_fort_one_russia 0
		set_counter aberdeen_fort_two_russia 0
	end_if
		if I_NumberOfSettlements venice <= 0
		set_counter aberdeen_fort_one_venice 0
		set_counter aberdeen_fort_two_venice 0
	end_if
		if I_NumberOfSettlements poland <= 0
		set_counter aberdeen_fort_one_poland 0
		set_counter aberdeen_fort_two_poland 0
	end_if
	end_monitor

[Gigantus]

;###### Fort Ownership At Game Start #######

Inconclusive and not necessary

I_NumberOfSettlements scotland <= 0

The faction is defeated

[TNZ]

Here is a working test of a garrison script that uses the ‘create_unit’ and ‘destroy_units’ commands.

campaign_script:

Spoiler Alert, click show to read: 

	monitor_event FactionTurnStart FactionType scotland
		and IsFactionAIControlled
		and I_SettlementOwner Edinburgh = scotland
		and I_TurnNumber >= 1
		destroy_units scotland garrison_unit
	end_monitor

	monitor_event FactionTurnEnd FactionType scotland
		and IsFactionAIControlled
		and I_SettlementOwner Edinburgh = scotland
		create_unit Edinburgh, Garrison Spear Militia, num 6, exp 0, arm 0, wep 0
	end_monitor

export_descr_unit:

Spoiler Alert, click show to read: 

type             Garrison Spear Militia
dictionary       Garrison_Spear_Militia      ; Spear Militia
category         infantry
class            spearmen
voice_type       Light
banner faction   main_spear
banner holy      crusade
soldier          Spear_Militia, 60, 0, 1.5
attributes       sea_faring, hide_forest, can_withdraw, free_upkeep_unit, garrison_unit
formation        1.2, 1.2, 2.4, 2.4, 4, square, schiltrom
stat_health      1, 0
stat_pri         7, 3, no, 0, 0, melee, melee_blade, piercing, spear, 25, 0.6
;stat_pri_ex      0, 0, 0
stat_pri_attr    spear, spear_bonus_8
stat_sec         0, 0, no, 0, 0, no, melee_simple, blunt, none, 25, 1
;stat_sec_ex      0, 0, 0
stat_sec_attr    no
stat_pri_armour  0, 3, 8, flesh
;stat_armour_ex   0, 2, 3, 5, 3, 8, 8, flesh
stat_sec_armour  0, 0, flesh
stat_heat        4
stat_ground      1, -2, 3, 4
stat_mental      3, normal, trained
stat_charge_dist 20
stat_fire_delay  0
stat_food        60, 300
stat_cost        1, 0, 0, 55, 135, 290, 4, 80
armour_ug_levels 1
armour_ug_models Spear_Militia_ug1
ownership        england, scotland, france, barons_alliance, venice, slave, norway, hre, denmark, spain, portugal, normans, saxons, poland, hungary, russia, sicily, venice, wales, norway
era 0            england, scotland, france, barons_alliance, venice, slave, norway, hre, denmark, spain, portugal, normans, saxons, poland, hungary, russia, sicily, venice, wales, norway
era 1            england, scotland, france, barons_alliance, venice, slave, norway, hre, denmark, spain, portugal, normans, saxons, poland, hungary, russia, sicily, venice, wales, norway
;unit_info        7, 0, 11
recruit_priority_offset    -25

[Gorrrrrn]

Stainless steel ran out of regions so lakes count as The Sea.
and we keep getting pirate ships spawning in them.

So, we add the attribute pirate_ships to the pirate ships in the EDU.

and add this to the campaign script:

monitor_event FactionTurnEnd FactionType slave

and I_TurnNumber = 50

destroy_units, slave, pirate_ships

end_monitor
terminate_monitor

you can clone for whatever turns you feel works best.
It'll clean them out on T50 and any further turns you specify.

It'll also clear pirates from the open seas but the spawn again anyway.

If you really want to remove pirates from your game, do the EDU attribute trick and simply:

monitor_event FactionTurnEnd FactionType slave

destroy_units, slave, pirate_ships

end_monitor

which removes any that spawn at the end of each turn.

simples.
--

well I tested this and the pirate ship lurking in one of the lakes was still there on T51 - but was gone on T52.

so it works!

I'll add to the O/P.

(in this particular case you can stop the pirates from spawning by using the no_pirates line in descr_regions for every region you need.)

but the general principle works.)

[Augustus Lucifer]

Very nice find Rozanov. I've added a link in the OP of the Research Hub thread so this find won't be lost to the sands of time.

Already thinking about interesting ways to use this, but the ideas already provided are solid. One question which comes to mind, is whether or not there's a limit on how many faux-attributes the game will recognize, or if it treats them like counters where it doesn't matter. Further, whether or not there's a limit to the amount of attributes each unit entry can have would be important.

[Taiji]

I just thought of some very nice ways to use it; set up catholic religious order troops with a common attribute, and then destroy them when the faction gets excommunicated.

And also for destroying crusading mercenaries when the crusade is over.

I think they're both great ideas and I might use them (if I can work out how ). Thanks for the inspiration, Rozanov! +rep