# Modding guide

Contents

- the rules
  - ability properties
    - effect
      - apply_bonus
      - bonus
      - conversion
      - raise_dead
      - recall
      - resurrection
      - summon
      - teleportation
    - effect_target
    - effect_range

# the rules

Since SoundRTS 1.1, the rules of the game are stored in a file called rules.txt.

## ability properties

### effect

effect <effect type> [parameters]

Default value: (none)

An effect is a property of an ability. When an ability is used by a unit, the effect will take place unless no effect type has been mentionned.

Additional properties can modify an effect: effect_target and effect_range.

#### apply_bonus

effect apply_bonus <property name>

Increases the property of the affected units. The value is defined in the property of the unit called "<property name>_bonus". For example, "effect apply_bonus damage" will look for a property called "damage_bonus" in the definition of each affected unit. This way, units benefiting from the same upgrade can have different bonus values.

#### bonus

effect bonus <property name> <value>

Increases by the indicated value the property of the affected units.

At least the following properties should work: damage, armor, range, heal_level, speed, hp_max (old units won't have their hp updated to hp_max though). food_cost and food_provided probably don't work correctly.

#### conversion

effect conversion (no parameter)

Moves the target to the caster's army.

If the target isn't an enemy of the caster, nothing will happen.

Allowed values for the related properties:

- effect_target: ask
- effect_range: square, nearby, anywhere

TODO: add a <limit> so units in a targeted square are chosen (instead of having to target a unit)

#### raise_dead

effect raise_dead <life span (in seconds)> <unit types and numbers>

Creates the required units in the targeted square from the corpses in the square, in the order of the units list. If there are not enough corpses, the end of the list will not be created. The units will disappear after <life span> seconds, unless <life span> is set to 0.

If no corpse is in the targeted square, the order won't be executed.

Allowed values for the related properties:

- effect_target: self, ask, random
- effect_range: square, nearby, anywhere

#### recall

effect recall (no parameter)

Similar to teleportation. Teleports the player's units from the targeted square back to the caster's square. Buildings are unaffected. Allied units are unaffected too.

If no unit is in the targeted square, the order won't be executed.

Allowed values for the related properties:

- effect_target: ask, random
- effect_range: nearby, anywhere

#### resurrection

effect resurrection <limit>

Resurrects the corpses of the caster's army lying in the targeted square, with a maximum of <limit> resurrected units. The oldest corpses are resurrected first. The hit points are restored to one third of their maximum.

If no corpse of a unit in the same army is in the targeted square, the order won't be executed.

Allowed values for the related properties:

- effect_target: self, ask, random
- effect_range: square, nearby, anywhere

#### summon

effect summon <life span (in seconds)> <unit types and numbers>

Creates the required units in the targeted square and adds them to the caster's army. The summoned units will disappear after <life span> seconds, unless <life span> is set to 0.

Allowed values for the related properties:

- effect_target: self, ask, random
- effect_range: square, nearby, anywhere

#### teleportation

effect teleportation (no parameter)

Moves the player's units in the caster's square to the target square. Buildings are unaffected. Allied units are unaffected too.

If the destination is the same as the caster's square, nothing will be done.

Allowed values for the related properties:

- effect_target: ask, random
- effect_range: nearby, anywhere

### effect_target

effect_target <selection method>

Determines how the target will be selected.

Default value: self

Possible values:

- self: the target will be the caster (or the location of the caster if the target must be a place)
- ask: the user interface will ask for a target
- random: the game will choose a random square as a target

### effect_range

effect_range <distance>

Determines the distance between the caster and the target.

Default value: square

Possible values:

- square: they must be in the same square
- nearby: they must be in an adjacent square or in the same square
- anywhere: any distance is allowed

If the current distance is greater than the required distance, the caster will try to move to a closer place and use the ability from there.