# Widelands Productionsite Program Reference

Productionsites can have programs that will be executed by the game engine. Each productionsite must have a program named work, which will be started automatically when the productionsite is created in the game, and then repeated until the productionsite is destroyed. Each program must be declared with program=<name> in the [global] section of the productionsite's definition. A program can call another program, which must have been declared earlier. A program is defined in the section that has the same name as the program (the order of program definitions does not matter). A program consists of a sequence of commands. A command is written as <type>=<parameters>. The different command types and the parameters that they take are explained below.

## command types

- return
- call
- worker
- sleep
- animate
- consume
- produce
- mine
- check_soldier
- train
- playFX

### return

Returns from the program.

Parameter syntax:

      parameters         ::= return_value [condition_part]
      return_value       ::= Failed | Completed | Skipped
      Failed             ::= failed
      Completed          ::= completed
      Skipped            ::= skipped
      condition_part     ::= when_condition | unless_condition
      when_condition     ::= when condition {and condition}
      unless_condition   ::= unless condition {or condition}
      condition          ::= negation | economy_condition | workers_condition
      negation           ::= not condition
      economy_condition  ::= economy economy_needs
      workers_condition  ::= workers need_experience
      economy_needs      ::= needs ware_type
      need_experience    ::= need experience

Parameter semantics:

      return_value:
         If return_value is Failed or Completed, the productionsite's
         statistics is updated accordingly. If return_value is Skipped, the
         statistics are not affected.
      condition:
         A boolean condition that can be evaluated to true or false.
      condition_part:
         If omitted, the return is unconditional.
      when_condition:
         This will cause the program to return when all conditions are true.
      unless_condition:
         This will cause the program to return unless some condition is true.
      ware_type:
         The name of a ware type (defined in the tribe). A ware type may only
         appear once in the command.
      economy_needs:
         The result of this condition depends on whether the economy that this
         productionsite belongs to needs a ware of the specified type. How
         this is determined is defined by the economy.

Aborts the execution of the program and sets a return value. Updates the productionsite's statistics depending on the return value.

Note: If the execution reaches the end of the program, the return value is implicitly set to Completed.

### call

Calls a program of the productionsite.

Parameter syntax:

      parameters                 ::= program [failure_handling_directive]
      failure_handling_directive ::= on failure failure_handling_method
      failure_handling_method    ::= Fail | Repeat | Ignore
      Fail                       ::= fail
      Repeat                     ::= repeat
      Ignore                     ::= ignore

Parameter semantics:

      program:
         The name of a program defined in the productionsite.
      failure_handling_method:
         Specifies how to handle a failure of the called program.
         * If failure_handling_method is Fail, the command fails (with the
           same effect as executing return=failed).
         * If failure_handling_method is repeat, the command is repeated.
         * If failure_handling_method is ignore, the failure is ignored
           (the program is continued).
      failure_handling_directive:
         If omitted, the value Ignore is used for failure_handling_method.

### worker

Calls a program of the productionsite's main worker.

Parameter syntax:

      parameters ::= program

Parameter semantics:

      program:
         The name of a program defined in the productionsite's main worker.

### sleep

Does nothing.

Parameter syntax:

      parameters ::= duration

Parameter semantics:

      duration:
         A natural integer. If 0, the result from the most recent command that
         returned a value is used.

Blocks the execution of the program for the specified duration.

### animate

Runs an animation.

Parameter syntax:

      parameters ::= animation duration

Parameter semantics:

      animation:
         The name of an animation (defined in the productionsite).
      duration:
         A natural integer. If 0, the result from the most recent command that
         returned a value is used.

Starts the specified animation for the productionsite. Blocks the execution of the program for the specified duration. (The duration does not have to equal the length of the animation. It will loop around. The animation will not be stopped by this command. It will run until another animation is started.)

### consume

Consumes wares from the input storages.

Parameter syntax:

      parameters ::= group {group}
      group      ::= ware_type{,ware_type}[:count]

Parameter semantics:

      ware_type:
         The name of a ware type (defined in the tribe).
      count:
         A positive integer. If omitted, the value 1 is used.

For each group, the number of wares specified in count is consumed. The consumed wares may be of any type in the group.

If there are not enough wares in the input storages, the command fails (with the same effect as executing return=failed). Then no wares will be consumed.

Selecting which ware types to consume for a group so that the whole command succeeds is a constraint satisfaction problem. The implementation does not implement an exhaustive search for a solution to it. It is just a greedy algorithm which gives up instead of backtracking. Therefore the command may fail even if there is a solution.

However it may be possible to help the algorithm by ordering the groups carefully. Suppose that the input storage has the wares a:1, b:1 and a consume command has the parameters a,b:1 a:1. The algorithm tries to consume its input wares in order. It starts with the first group and consumes 1 ware of type a (the group becomes satisfied). Then it proceeds with the second group, but there are no wares of type a left to consume. Since there is no other ware type that can satisfy the group, the command will fail. If the groups are reordered so that the parameters become a:1 a,b:1, it will work. The algorithm will consume 1 ware of type a for the first group. When it proceeds with the second group, it will not have any wares of type a left. Then it will go on and consume 1 ware of type b for the second group (which becomes satisfied) and the command succeeds.

Note: It is not possible to reorder ware types within a group. a,b" is equivalent to b,a because in the internal representation the ware types of a group are sorted.

### produce

Produces wares.

Parameter syntax:

      parameters ::= group {group}
      group      ::= ware_type[:count]

Parameter semantics:

      ware_type:
         The name of a ware type (defined in the tribe). A ware type may only
         appear once in the command.
      count:
         A positive integer. If omitted, the value 1 is used.

For each group, the number of wares specified in count is produced. The produced wares are of the type specified in the group. How the produced wares are handled is defined by the productionsite.

### mine

Takes resources from the ground. This command type is subject to change.

### check_soldier

Returns failure unless there are a specified amount of soldiers with specified level of specified properties. This command type is subject to change.

### train

Increases the level of a specified property of a soldier. No further documentation available.

### playFX

Plays a soundFX.

Parameter syntax:

      parameters ::= soundFX [priority]

Parameter semantics:

      soundFX:
         The filename of a soundFX (relative to the productionsite's
         directory).
      priority:
         An integer. If omitted, 127 is used.

Plays the specified soundFX with the specified priority. Whether the soundFX is actually played is determined by the sound handler.