# Bos Wars Scripting API: Research

Stratagus FAQ PREV NEXT LUA Index

CheckDependency DefineAllow DefineDependency DefineModifier GetDependency

## Intro - Introduction to research functions and variables

Everything around researching and upgrades.

## Functions

### CheckDependency()

NOT WRITTEN YET.

.
  .

#### Example

        CheckDependency()

### DefineUnitAllow(name, N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, N)

Define how many units of a given type each player can have.

name
  Name of an unit-type to be defined.
N
  The initial quantity of units per type at level start. Each player has his quatinty, the first is for player 0 and the last is for player 15.

#### Example

        -- Allow 1 catapult for the 2nd player.
        DefineUnitAllow("unit-catapult", 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)

### DefineAllow(name, str16)

Define what upgrades are enabled for each player during a level.

name
  Name of an upgrade to be defined.
str16
  The initial allow state for the upgrade at level start:
  - A - Allowed
  - E - Enabled, allowed by level but currently forbidden
  - F - Forbidden
  - R - Researched or acquired
  - Q - Acquired but currently forbidden (does it make sense?:)
  Each player has his own character, the first is for player 0 and the last is for player 15.

#### Example

        -- Allow the metal upgrade for all 16 players.
        DefineAllow("upgrade-metal", "AAAAAAAAAAAAAAAA")
        --                            ^- player 0    ^- player 15

### DefineDependency( unit-type/upgrade ...)

Define the dependencies for an unit-type or an upgrade. The dependency must be full filled before an unit or research can be used.

`DefineDependency unit-type/upgrade '( required-part ) ['or '( optional-or-part ) ...] )`

required-part
  `unit/upgrade [count]`

  A list of unit-types or upgrades required.

  unit/upgrade
    Unit-type name or upgrade name required.
  count
    Optional count, how many units of the unit-type are required.
'or optional-or-part
  `unit/upgrade [count]`

  Optional list of or parts. One or list must be complete full filled.

  unit/upgrade
    Unit-type name or upgrade name required.
  count
    Optional count, how many units of the unit-type are required.

#### Example

        -- The second sword upgrade is only possible, if the first sword upgrade is
        -- researched.
        (define-dependency "upgrade-sword2" '(upgrade-sword1))
        -- The ranger upgrade is only available if a keep or castle is available.
        (define-dependency 'upgrade-ranger '(unit-keep) 'or '(unit-castle))

### DefineModifier("upgrade-name", {effect1, effect1-arg}, {effect2, effect2-arg}, ... )

Define the effects (modifier) of an upgrade. An upgrade can have multiple modifiers. It can activate, enable or disable other upgrades and allows complex reactions.

"upgrade-name"
  Name of the upgrade, which has this effects. All effects change all old units and any new unit of a player.
{effectN, effectN-arg}
  A list of effects of the upgrade. Here are all possible effects:
  {"attack-range", N}
    Increase the attack range of all units of the unit-types given with '(apply-to ...). Note it can be increased with positive numbers and decreased with negative numbers.
  {"sight-range", N}
    Increase the sight range of all units of the unit-types given with '(apply-to ...).
  {"basic-damage", N}
    Increase the basic damage of all units of the unit-types given with '(apply-to ...).
  {"piercing-damage", N}
    Increase the piercing damage of all units of the unit-types given with '(apply-to ...).
  {"armor", N}
    Increase the armor of all units of the unit-types given with '(apply-to ...).
  {"hit-points", N}
    Increase the hit points of all units of the unit-types given with '(apply-to ...).
  {"regeneration-rate", N}
    Increase the amount of HP a unit gains per seconds
  {"variable-name", N}
    Increase the user defined variable of all units of the unit-types given with '(apply-to ...). Note Variable must be defined with DefineVariables().
  {"cost", ("resource-name", N}}
    Increase the costs for the resource type of all unit-types or upgrade-ids given with '(apply-to ...).
  {"allow-unit", "unit-type", N}
    Change the state of an upgrade. N is the maximum quantity of this unit per player.
  {"allow", "upgrade", 'A' or 'E' or 'F' or 'R' or 'Q'}
    Change the state of an upgrade. state can be
    - A - Allowed
    - E - Enabled, allowed by level but currently forbidden
    - F - Forbidden
    - R - Researched or acquired
    - Q - Acquired but currently forbidden (does it make sense?:)
    FIXME: The correct possible changed must be described.
  {"apply-to", "unit-type" or "upgrade"}
    The modifiers are applied to this unit-type or upgrade.
  {"convert-to", "unit-type"}
    All units of the unit-types given with '(apply-to ...) are converted into this unit-type.

#### Example

    -- This is the default effect of the first sword upgrade. The piercing damage
    -- of the listed units is increased.
    DefineModifier("upgrade-sword1",
      {"piercing-damage", 2},
      {"apply-to", "unit-footman"}, {"apply-to", "unit-knight"}, {"apply-to", "unit-paladin"},
      {"apply-to", "unit-dwarves"}, {"apply-to", "unit-arthor-literios"}, {"apply-to", "unit-wise-man"},
      {"apply-to", "unit-man-of-light"}, {"apply-to", "unit-knight-rider"})

### GetDependency()

NOT WRITTEN YET.

#### Example

        GetDependency()

All trademarks and copyrights on this page are owned by their respective owners.