Craig Brett's Tactical Battle scripts and stuff

By Craig Brett

Introduction

Hello and welcome. This documentation is for the Craig Brett collection of scripts. These scripts are designed to help map creaters for Tactical Battle utilize the powerful scripting capabilities built in to the engine. These scripts and this documentation are copyright, left and any other direction Craig Brett. Anyone else taking credit for them will suffer the consequences.

How to use the scripts

Loading the scripts into your map pack

Firstly, to use this collection of scripts, you need to allow your map pack to use them. In your map pack's Map Pack Settings.txt file, on a blank line, put:

load_scripts=craig_brett

And these scripts will be loaded when someone plays your map pack. Easy!

If you already have load_scripts in your map pack, simply put a comma ',' after the last name in the list, and add me in as well.

load_scripts=victorious,craig_brett

Script flags

To use script flags, such as the ones in these scripts, your map pack must be converted up to parser version 10. If your map pack isn't already, you must do this first.

To quickly start this, in the game on the map pack selection screen, highlight the map pack you want to convert and press ctrl+u. This will do some of the initial heavy lifting for you. All you will need to do is correct any issues that the game didn't properly resolve. A common one is point flags such as auto_regen which require a true after them now. Maps themselves won't be converted to version 10, unless you go into the map editor. When you save a map that isn't converted yet in a version 10 map pack, it will convert it for you.

Once you've moved up to version 10, your skills, units, effects, etc, will all have a script_flags section towards the bottom of the file, that will look something like this:

|script_flags

Here is where you will place the flags you want. A quick example.

|script_flags
transforms_into warrior

Arguments

Some flags take an argument after the flag. In the example above, the transforms_into flag takes the name of a unit as an argument. This allows you to pass in additional information to the script. Some flags take numbers, some flags take true or false. For ones that you want to put true for, you can also just omit the true and by the flag being there it will behave as if you put true.

The different types of argument are outlined below:

The magic of strings

Strings are arguments that take one or many words.

In my particular set of scripts, I have a couple of tricks you can use to take better advantage of strings for flavour text and such.

Placeholders

Placeholders allow you to inject values into your text. This is normally limited to the units involved in a script, unless otherwise specified.

Placeholders work by wrapping a number (starting at 0) in curly braces "{}". With "{0}" being the first placeholder value possible.

In script flags on units or on effect fizzled messages, {0} will insert the unit. On skills and effects, {0}will be the user, while {1} will be the target. On the success_message flag, {1} will refer to the target as well, unless there isn't one, in which case it will be the tile on which this skill was used.

An example, for Chelsea the good witch, is below:

|script_flags
death_message {0} disappears in a swirl of mystic energies, which fade to nothing

If the worst should happen to Chelsea the good witch in battle, the following will be read:

Chelsea the good witch disappears in a swirl of mystic energies, which fade to nothing

Multiple alternative strings

Almost all flags that take strings of text as an argument for flavour text / messages can have multiple alternatives listed. One of these strings will be chosen at random and read, allowing you to vary up the flavour text a little.

To do this, separate your strings with the bar or pipe symbol "|". An example of a death_message is below:

|script_flags
death_message {0} fades, leaving only their robes behind | {0} seems to evaporate before you, leaving no body behind.

The flags

Below, I will describe all the flags provided by these scripts and explain how to use them, giving examples where appropriate, as well as the supporting flags (i.e flags that help other flags but do nothing on their own).

transport_capacity

Argument: number

Use on: Units

Description: This flag designates that this unit is a transport and sets the unit's capacity for carrying other units. When a unit tries to board this transport, the passenger's transport_capacity_required is checked to see if there will be room for this unit and if there is, the unit may board the transport.

Example: transport_capacity 5

transport_capacity_required

Argument: number

Use on: Units

Description: This flag is used when a unit boards a transport to show how much space this unit will take up in this transport. You may choose to have larger units taking up more space in a transport. I.e. a tank will take up more space than a soldier, etc. When a unit boards a transport, this value is checked against the transport's transport_capacity to see if there will be sufficient room for this unit.

Example: transport_capacity_required 1

enters_transport

Argument: boolean

Use on: Skills

Description: This skill will attempt to board the user onto the target (a transport). If the target is not a transport or has insufficient space, the unit will not board the transport.

Example: enters_transport

supporting flags

loads_onto_transport

Argument: boolean

Use on: Skills

Description: This script works like enters_transport with the target reversed. It will load the targeted unit onto the user of this skill if they are a valid transport with capacity available.

Example: loads_onto_transport

supporting flags

Same as for enters_transport

unloads_transport

Argument: boolean

Use on: Skills

Description: This skill will unload all transported units on the tile of the transport or onto adjacent tiles. If there isn't enough free space around the transport, the units may not all be unloaded.

Example: unloads_transport

supporting flags

unloads_cargo_on_death

Argument: boolean

Use on: Units

Description: This skill will unload all transported units upon the unit's death. If there is insufficient space around the transport to offload when it dies, the units will not be unloaded (and will disappear into the ether, presumably dying with their transport).

Example: unloads_cargo_on_death

adjusts_transport_capacity

Argument: number

Use on: Skills

Description: This skill will adjust the amount of transport capacity on its target. This can be a negative number. If the negative adjustment will take the transport capacity below 0, it is capped at 0 and cannot go any lower.

Example: adjusts_transport_capacity 1

death_message

Argument: string

Use on: Units

Description: This string will be read after one of these units die.

Example: death_message {0} whines pitteously, rolls over and moves no more

toggle_to_user_team

Alternatives: charm

Argument: boolean

Use on: Skills, Effects

Description: If in a skill, this will permenantly move the target onto the team of the user. If this is an effect, then the unit will be on that team only as long as the effect lasts. Once the effect is removed or fizzles, the target will move back to their original team.

Example: toggle_to_user_team

Another example: charm

supporting flags

toggle_to_team

Argument: number

Use on: Skills, Effects

Description: The same as toggle_to_user_team, except that you may specify the number of a team to transfer the unit to.

Example: toggle_to_team 4

Supporting flags

Same as for toggle_to_user_team

toggle_team_immune

Argument: boolean

Use on: Units

Description: This specifies that this unit will always be immune to having its team changed. This is useful for scenarios where you may want the skill to succeed or the effect to be applied but not want the unit to change teams.

Example: toggle_team_immune

untoggle_team

Argument: boolean

Use on: Skills

Description: This skill will remove the toggle_team effects from a unit, moving them back to their original team. If the toggle_team comes from an effect, this will not remove the effect, only the toggle_team part of it. It is recommended to remove the effect instead.

Example: untoggle_team

transform_into

Argument: string

Use on: Skills, Effects

Description: If in a skill, this will permenantly change this unit into the new type of unit. If in an effect, the unit will transform into the new type of unit for the duration of the effect. A slash separated list may be given to randomly pick one of the given unit types to transform into.

Example: transform_into frog/pig

Supporting flags

Advanced transformation flags

You may wish to apply one type of transform to one type of unit and a different one to any other target of this skill or effect. Or even only transform certain types of units.

This is possible by using comma and pipe separated lists of units. To do this, first specify the type of unit that will be specially transformed, then put a pipe "|" symbol, then the unit it will be transformed into. For example:

transform_into frog|prince

The above example will transform any frog unit into a prince. On other units, it will do nothing. If we wanted to also turn toads into a prince as well, we could use a comma to separate this.

transform_into frog|prince,toad|prince

This will do the same as the above, but it would also do the transformation on toads. We can also utilize the slash "/" separator to randomise, as you can with normal transformations. In the following example, we also make it so that any cat is turned into a witch or a wizard at random.

transform_into frog|prince,toad|prince,cat|witch/wizard

Finally, you can have a unit that any other type of unit is transformed into. In this example, if they're not a cat, toad or frog, we turn them into a sparrow. To do this, have a unit with no pipe or other unit in the list. Like so.

transform_into frog|prince,toad|prince,cat|witch/wizard,sparrow

As you can see, the last item has no pipe, so is the default transformation if the unit isn't one of the other types.

death_transformation

Argument: string

Use on: Units

Description: When this unit dies, it will transform into the given unit. A '/' separated list may be given, and one of these units will be chosen at random.

Example: death_transformation zombie/skeleton

Supporting flags

revert_transformation

Argument: boolean

Use on: Skills

Description: This skill will undo transformations placed on a unit, reverting them back to their original unit type.

Example: revert_transformation

success_message

Argument: string

Use on: Skills

Description: This will add flavour text to a skill, which will be read if the skill succeeds.

Example: success_message {0}'s arrow strikes true, burying itself in {1}

failure_message

Argument: string

Use on: Skills

Description: This will add flavour text to a skill, which will be read if the skill fails

Example: failure_message {0} fires an arrow which falls short of {1}

fizzle_sound

Argument: string

Use on: Effects

Description: This plays the given sound file upon the effect fizzling. This will not occur if the effect is removed by a skill.

Example: fizzle_sound sizzle.wav

fizzle_message

Argument: string

Use on: Effects

Description: This reads the given flavour text once the effect fizzles of its own accord. This will not happen if the effect is removed by a skill.

Example: fizzle_message {0} wakes up suddenly

move_other_unit_toward

Argument: number

Use on: Skills

Description: This will move the target of the skill the given number of tiles closer to the user. If the path between the user and the target is blocked (i.e by impassable terrain, too many other units), the target will be bought as close as it can be before reaching the blockage.

Example: move_other_unit_toward 1

Supporting flags

move_other_unit_away

Argument: number

Use on: Skills

Description: This will move the target of the skill the given number of tiles away from the user. If the path behind the target is blocked (i.e by impassable terrain, too many other units), the target will be sent as far away as it can be before reaching the blockage.

Example: move_other_unit_away 2

Supporting flags

Same as move_other_unit_toward

critical_hit_chance

Argument: percent

Use on: skills

Description: The percentage chance that this hit will be a critical hit. You can then apply replacement damage, restoration or effects if you so choose.

Example: critical_hit_chance 10%

Supporting flags

stack_into

Argument: string

Use on: skills

Description: Allows you to use a skill to combine a unit with other units of the same type on the same tile into a different unit. Useful for Form Squad type abilities. The A.I does not currently understand how to use these type of skills. You must use this with the stack_number flag, and must have the prerequsite number of units on the tile where this skill is used. The target of this skill should be one of the units that will be put into the stack. Self is a good flag to have on skills like these.

Example: stack_into zombie army

Supporting flags

drops_item

Argument: string

Use on: units

Description: Causes this unit to drop the given item on death. The unit does not need to possess any of this item to drop it. The real power of this script comes in with its supporting arguments.

Example: drops_item healing_potion

Supporting flags

Closing

Thank you for taking the time to make use of my collection of scripts. I hope you find them useful in making a more feature-filled Tactical Battle map pack. If you notice any problems or have any questions, I can be reached in the mailing list. Or alternatively by my e-mail address craigbrett17@aol.com.

My thanks go out to Ian, engine designer extraordinaire, for making Tactical Battle and the associated engine behind it. My thanks also go out to the various map pack makers, for being a friendly bunch o'people and making maps that are what make this game fun.

Happy mapping!