How to set objectives

An objective is a goal for a scenario. Meeting an objective may lead to another objective or may complete the scenario. You can combine objectives in various ways to make the scenario's goals more complex. Objectives include destroying units, reaching a given location, and time limits. You can set rewards that get handed out when the objective is met. Objective is a scenario property.

General properties

Once a given objective is met, the scenario may end. You can specify this through the endscenario property. When there's a new objective to meet, the viewer may decide to report a description of the objective to the user. This can be customized through the goal property if the default isn't sufficient. Once an objective is met, a message may be shown through the viewer to give an explanation. You can override the default message through the message property. See Rewards for how to hand out rewards and punishments when an objective has been achieved.

   <objective>
      <!-- when this objective is met, scenario will end -->
      <endscenario>true</endscenario>
      <!-- when objective needs to be met, goal will be displayed -->
      <goal>Pawn must spin around three times</goal>
      <!-- when objective is met, message will be display -->
      <message>Pawn has successfully spun around three times</message>
   </objective>

Basic objectives

The simplest objective is a time limit. When the given number of ticks has elapsed, the objective has been met. In the following example, the objective is met once 500 ticks have elapsed.

   <objective class="com.loki3.cyber.server.ObjectiveTime">
      <timelimit>500</timelimit>
   </objective>

Other objectives can be set based on the identity of pawns. You can specify how many pawns of the given identity must meet those objectives. If an identity isn't specified, all pawns will be checked to see if they meet the objective. Of the pawns that match the optional identity, you can declare that all pawns or a certain number of pawns must meet the objective. The following properties are common to the destroy and location objectives:

   <objective>
      <!-- all pawns of given identity must meet the objective -->
      <all>true<all>
      <identity>
         <!-- any pawn having at least one of these identities is a match -->
         <name>some identity</name>
         <name>another identity</name>
      </identity>
   </objective>

   <objective>
      <!-- 2 pawns must meet the objective -->
      <howmany>2<howmany>
   </objective>

If you want set an objective of having a pawn or group of pawns destroyed, you can use any of the preceding properties.

   <!-- 2 pawns called 'joe' must be destroyed -->
   <objective class="com.loki3.cyber.server.ObjectiveDestroy">
      <howmany>2<howmany>
      <identity>
         <name>joe</name>
      </identity>
   </objective>

In addition to the preceding properties, a location objective includes where and distance properties. The proper number of pawns of the specified identity (if any) must be within distance units of the given location for the objective to be met.

   <!-- all pawns must be within 3 units of (10,10) -->
   <objective class="com.loki3.cyber.server.ObjectiveLocation">
      <all>true<all>
      <where>10 10</where>
      <distance>3</distance>
   </objective>

Rewards

You can set rewards or punishments that are handed out to the appropriate pawn or team when an objective is met. A reward can have an Identity associated with it that identitifies who is given the reward. If there is no identity, it's assumed to be a single player game so the reward is automatically handed out when the objective is achieved. You can have multiple rewards associated with the same objective.

RewardWin is used to declare who wins and who loses. RewardPoints is used to hand out points.

   <objective class="com.loki3.cyber.server.ObjectiveTime">
      <timelimit>500</timelimit>
      <rewards>

         <!-- 'joe' is declared the winner -->
         <reward class="com.loki3.cyber.server.RewardWin">
            <win>true</win>
            <identity> <name>joe</name> </identity>
         </reward>

         <!-- 'bob' is given 42 points -->
         <reward class="com.loki3.cyber.server.RewardPoints">
            <points>42</points>
            <identity> <name>bob</name> </identity>
         </reward>

      </rewards>
   </objective>

Combining objectives

You can declare that all or any of a group of objectives have to be met. ObjectiveAnd indicates that all objectives declared under it must be met simultaneously. In contrast, if any of the objectives under ObjectiveOr are met, the objective is met.

   <!-- objective is met when a pawn named 'joe' has made it to location 25,25
      and two pawns of identity 'bob' have been destroyed -->
   <objective class="com.loki3.cyber.server.ObjectiveAnd">
      <objective class="com.loki3.cyber.server.ObjectiveLocation">
         <where>25 25</where>
         <distance>1</distance>
         <identity>
            <name>joe</name>
         </identity>
      </objective>
      <objective class="com.loki3.cyber.server.ObjectiveDestroy">
         <howmany>2<howmany>
         <identity>
            <name>bob</name>
         </identity>
      </objective>
   </objective>

   <!-- objective is met when time has expired
      or a pawn named 'joe' has made it to location 25,25 -->
   <objective class="com.loki3.cyber.server.ObjectiveOr">
      <objective class="com.loki3.cyber.server.ObjectiveTime">
         <timelimit>2000<timelimit>
      </objective>
      <objective class="com.loki3.cyber.server.ObjectiveLocation">
         <where>25 25</where>
         <distance>1</distance>
         <identity>
            <name>joe</name>
         </identity>
      </objective>
   </objective>

Note that ObjectiveAnd and ObjectiveOr can be arbitrarily nested within themselves or within ObjectiveChain to build up complex goals for a scenario.

Chaining objectives

If you want them to have to accomplish one objective before continuing to another objective, you can chain them together with ObjectiveChain. You can have any number of objectives chained together this way.

   <!-- once any two pawns have been destroyed,
      a pawn must make it to the given location  -->
   <objective class="com.loki3.cyber.server.ObjectiveChain">
      <objective class="com.loki3.cyber.server.ObjectiveDestroy">
         <howmany>2<howmany>
      </objective>
      <objective class="com.loki3.cyber.server.ObjectiveLocation">
         <where>25 25</where>
         <distance>1</distance>
      </objective>
   </objective>

The following example shows several of these objectives all combined together.

   <!-- once any two pawns have been destroyed,
      a pawn must make it to the given location before time expires  -->
   <objective class="com.loki3.cyber.server.ObjectiveChain">
      <objective class="com.loki3.cyber.server.ObjectiveDestroy">
         <goal>First you must destroy two pawns</goal>
         <howmany>2<howmany>
      </objective>
      <objective class="com.loki3.cyber.server.ObjectiveOr">
         <goal>You must make it home before time expires</goal>
         <objective class="com.loki3.cyber.server.ObjectiveTime">
            <message>Sorry, time ran out</message>
            <reward class="com.loki3.cyber.server.RewardWin">
               <win>false</win>
            </reward>
            <timelimit>2000<timelimit>
         </objective>
         <objective class="com.loki3.cyber.server.ObjectiveLocation">
            <message>You made it!</message>
            <reward class="com.loki3.cyber.server.RewardWin">
               <win>true</win>
            </reward>
            <where>25 25</where>
            <distance>1</distance>
         </objective>
      </objective>
   </objective>