Tribe Scripting

From PSwiki
Jump to navigation Jump to search

Recipe Logic

Recipes

A recipe database entry

id name requirements algorithm persistent
used for db storing Name of the recipe requirement string containing all requirements algorithm string containing all algorithm steps If this flag is on, the recipe won't ever be deleted from the recipe tree. After parsing it, if no other recipe has a higher priority... it will be reparsed.

Usage of Recipes

Recipes is used to describe how tribes react. See Tribe Design for details.

On initialization, a tribal recipe is first loaded in respect of the information indicated by the 'tribal_recipe' field. (see tribes.sql). The tribal recipe is formed from 'Tribe Info' functions. (see below)

Based on those functions the npctype for each tribe is created and initial recipes are loaded.

Further on, each Recipe has two important sections: requirements and algorithm. Each of those two is represented by a long string (the maximum is set in the database to 1000 characters) of functions separated by a semi-colon ';'. Upon parsing the long string is split in respect of the semicolons (;) and the recipe manager analyzes each resulting function.

Recipe-Tree Nodes

Inside a tribe object, recipes are stored as Recipe Tree Nodes. This class was created to facilitate the management of recipes and the way recipes are selected to be parsed.

All recipes are stored as leaves in a tree. This way we can always know their hierarchy and precedence.

Besides the obvious usage as a tree, recipe tree nodes also hold vital data for recipe parsing: last requirement parsed, last algorithm step parsed, remaining waiting time.

Let's consider an example of a tribe which has some building spots available and the task to build on those spots.

Adobe SVG Viewer plugin (for Internet Explorer) or use Firefox, Opera or Safari instead.

Having the tree above, it's easy to select the actions required to complete the task. We first get some more food. After that we get the required members, search for wood and stone, and finally build the buildings.

Tribe Info

Brain

Syntax: brain(x);

Arguments:

  • x brain eg. behaviour to use for the tribe.

Effect: Override the AbstractTribesman as the brain for the tribe.

For each tribe the server create an tribe_<tribe_id> behavior that inherit from the brain given i the brain command. If no brain entry is given the tribe behaviour will use the AbstractTribesman behaviour. This can be used to create tribes with special behaviours.

Aggressivity

Syntax: aggressivity(x);

Arguments:

  • x in { warlike, neutral, peaceful }

Effect: Decides the way the tribe reacts to other entities around it's members:

  • Warlike -- Attack anything on sight.
  • Neutral -- Attack only if members are attacked.
  • Peaceful -- If tribe members are attack they flee, trying to escape.

Mechanics: Upon parsing this function, an extra reaction is added to the tribal npctype in respect of this function's argument.

LoadRecipe

Syntax: loadRecipe(x); loadRecipe(x,distributed);

Arguments:

  • 'x' is a Recipe Name

Effect: Loads a recipe into the recipe tree. The new recipe's priority will be the current recipe's priority + 1.

LoadCyclicRecipe

Syntax: loadCyclicRecipe(x,t);

Arguments:

  • 'x' is a Recipe Name
  • 't' is an int, representing the number of ticks (milliseconds) between recipe executions

Effect: Loads a recipe into the recipe tree once every 't' ticks, with highest priority.

SleepPeriod

Syntax: sleepPeriod(x);

Arguments: x in { diurnal, nocturnal, nosleep }

diurnal 22:00 - 06:00 Sleep during night
nocturnal 08:00 - 18:00 Sleep during day

Effect: Makes the tribe members sleep at the given period of day.

Mechanics: Upon parsing this function, an extra reaction is added to the tribal npctype. The reaction should react to timeofday perceptions.

Requirements

Building

Syntax: building(x,y,r);

Arguments:

  • 'x' is a building name.
  • 'y' is an int defining the quantity of buildings needed.
  • 'r' is the recipe needed to get the building if not available

Effect & Mechanics: At the moment, items are 'magically' stored inside the tribal object. This object keeps track on items and buildings with the 'Asset' structure. 'x' can be any string with the condition that the tribe can actually gain the requested asset. Otherwise the requirement will never be met. Upon parsing this requirement, the tribal object checks it's asset arrays for the building 'x' of quantity 'y'.

Tribesman

Syntax: tribesman(x,y);

Arguments:

  • x is a tribesman type (types are not well-defined at the moment). Keyword 'any' is accepted too in order to define any member.
  • y is an int defining the number of tribesmen needed

Effect & Mechanics: The tribal object checks for a number 'y' of tribesman typed 'x' with the current behavior equal to the tribe's idle behavior. (e.g. "do nothing" behavior) If 'y' members are found idle, the requirement is considered met.

Resource

Syntax: resource(x,y,r);

Arguments:

  • x is the resource name
  • y is the resource quantity required
  • r is the recipe needed to get the resource if not available

Effect & Mechanics: The tribal object checks for a 'y' quantity of 'x' resource. If this quantity is found then the resource is considered complete. $RESOURCE_AREA, $REPRODUCTION_RESOURCE and $REPRODUCTION_COST are valid variables.

Judging by the way natural resources are defined, any string declared in natural_resources.sql as a resource can be parsed and mined by the tribe. By default, any new mine found by the tribesmen is stored as a memory named 'mine'. Upon it's first mining action done on the 'mine' memory, a reward is granted to the npc. When the NPC gets home and gives that to the tribal object, the memory 'mine' is renamed after the reward. In conclusion, having a resource named 'Space Shuttle' is valid and works.

Note: The resource requirement just checks if enough resources are available. Use 'alterResource' function in your recipes in order to actually substract resource from the tribe bank.

Knowledge

Syntax: knowledge(x);

Arguments: 'x' can be any string.

Effect & Mechanics: As described in the Tribe Design document, knowledge are tokens that keep track on technologies developed by the tribe. It's valid to request any string as long as it would be possible for the tribe to develop the knowledge. Otherwise the requirement will never be met.

Item

Syntax: item(x,y);

Arguments:

  • 'x' is an item/building name.
  • 'y' is an int defining the quantity of items needed.

Effect & Mechanics: At the moment, items are 'magically' stored inside the tribal object. This object keeps track on items and buildings with the 'Asset' structure. 'x' can be any string with the condition that the tribe can actually gain the requested asset. Otherwise the requirement will never be met. Upon parsing this requirement, the tribal object checks it's asset arrays for the item 'x' of quantity 'y'.

Recipe

Syntax: recipe(x,y);

Arguments:

  • 'x' is a recipe name.
  • 'y' is an int defining the quantity of recipes needed.

Effect & Mechanics: Upon parsing this requirement, the parser just adds an 'y' number of 'x' recipes to the recipe tree.

This requirement isn't quite practical and should be avoided.

Trader (Not available)

Syntax: trader(x);

Arguments:

  • 'x' is an item name

Effect: This requirement should check the traders array for a nearby trader giving item 'x'.

Memory

Syntax: memory(m,p,r);

Arguments:

  • 'm' is a memory name
  • 'p' is a probability between 0-100. Setting this to 10 make it 10% probably that the r will be run even if m is found.
  • 'r' is a recipe that will be run if the memory isn't found.

Effect & Mechanics: Upon parsing this requirement, the parser checks the memory array for a memory called 'm'. If it is found, requirement is considered met. If it isn't found or the probability for failure has hit it will run the recipe 'r'.

Algorithm Steps

AddKnowledge

Syntax: addKnowledge(x);

Arguments:

  • 'x' can be any string.

Effect & Mechanics: Adds the 'x' token as a piece of knowledge in the knowledge array.

AlterResource

Syntax: alterResource(x,y);

Arguments:

  • 'x' is a resource name
  • 'y' is an int describing quantity

Effect & Mechanics: Upon parsing this function, the parser modifies the quantity of resources available in the tribe.

Note: The 'y' value will be added to the current value in the tribe's bank. Use negative value to represent costs. (e.g. alterResource(gold,-20); in order to pay for a building)

Attack

Syntax: attack();

Arguments: None.

Effect & Mechanics: It sends to previously selected members the 'tribe:attack' perception to attack a previously selected location. If the selected location is not an attackable entity they will simply move there and attack whatever is near.

Gather

Syntax: gather();

Arguments:

  • None.

Effect & Mechanics: It sends previously selected members to a previously selected field and fires their 'tribe:gather' behavior.

GoWork

Syntax: goWork(x);

Arguments:

  • 'x' is an int defining the number of seconds the npcs should work for.

Effect & Mechanics: The 'goWork' function sends previously selected npcs to a previously selected location, set the npc buffer [Work_Duration] to 'x' and send 'tribe:work' behavior.

Guard (Not available)

Note:

 guard() function not implemented yet, use percept(selection, tribe:guard) instead.

Syntax: guard();

Arguments:

  • None.

Effect & Mechanics: It sends previously selected members to guard the selected location. Members will just patrol the area and attack whatever poses a threat.

LoadLocation

Syntax: loadLocation(x,y,z,r);

Arguments:

  • 'x', 'y' and 'z' are a set of coordinates.
  • 'r' is the location name.

Effect & Mechanics: add a new memory in the Database, adding a new location named "work" in the coordinates x,y,z.

LocateMemory

Syntax: locateMemory(x,r);

Arguments:

  • 'x' is a memory name.
  • 'r' is a recipe to load if the memory 'x' isn't found.

Effect & Mechanics: It looks in the tribe's memory array for the memory called 'x' and loads it into the previous selected npc's buffers. It is vital to use it before basic functions like mine,gather,guard,attack that use the npc buffers to execute.

LocateResource

Syntax: locateResource(x,r);

Arguments:

  • 'x' is a resource name.
  • 'r' the recipe to load if no resource 'x' is found

Effect & Mechanics: This function works like the above-mentioned 'locateMemory' function. The sole difference is that this function tries to locate resource 'x', and it case it fails it tries to locate memories 'mine' or 'field'. (which are the standard names of unprospected/undiscovered resource zones). In case nor 'mine' or 'field' are found, it sends the previous selected npcs to explore for them.

LocateBuildingSpot

Syntax: locateBuildingSpot(x);

Arguments:

  • 'x' is a building name.

Effect & Mechanics: This functions locates a building spot previously reserved via 'reserveBuildingSpot' function. It searches for building spots in the asset array and set the selected assess in the npc building spot asset. The NPC can use the Build Operation to build a building at the selected spot. NBUFFER[Building] is set to x, and NBUFFER[Work_Duration] is set to the building time of the building.

Example Tribe Script:

 select(Worker,1);locateBuildingSpot(Campfire);percept(selection,tribe:build)

Example NPC Script:

 <behavior name="DoBuild">
     <locate obj="building_spot" />
     <navigate />
     <wait duration="$NBUFFER[Work_Duration]" />
     <build />
     <talk text="Nice work building this $NBUFFER[Building]" />
 </behavior>
 <react event="tribe:build" behavior="DoBuild" />

Mate

Syntax: mate();

Arguments:

  • None.

Effect & Mechanics: It sends previously selected members to their home and fires their 'tribe:breed' behavior.

Note: By default, the 'mate' functions requires no resources and has no checks. Use it in a recipe that checks that enough resources for breeding are available.


Examples:

 select(any,1);
 setBuffer(selection,Reproduce_Type,$member_type);
 mate();
 alterResource($REPRODUCTION_RESOURCE, -$REPRODUCTION_COST);

Mine

Syntax: mine();

Arguments:

  • None.

Effect & Mechanics: It sends previously selected members to a previously selected mine and fires their 'tribe:mine' behavior.

Percept

Syntax: percept(t,p);

Arguments:

  • 't' is either selection or tribe
  • 'p' is the perception to send

Effect & Mechanics: It sends a perception to previously selected members or to the tribe.

Examples:

 select(any,1);
 percept(selection,tribe:gather)
 percept(tribe,tribe:flee)

ReserveSpot

Syntax: reserveSpot(x,y,z,bname);

Arguments:

  • 'x', 'y' and 'z' are coordinates in the same sector as the tribe
  • 'bname' is the building name we want to reserve the spot for

Effect & Mechanics: This function is used so the scripter (you) can arrange the future village of the tribe. When creating a tribe, a recipe containing building spots should be wrote in order to pinpoint where building should be constructed in the future.

Select

Syntax: select(x,y);

Arguments:

  • 'x' is a tribe member type. Types can be crated using the Reproduce Operation
  • 'y' is an int defining the number of members to be selected.

Effect & Mechanics: The 'select' function is probably the most important algorithm step. It selects the members passed as arguments and keeps them in a temporary npc array so they can accept orders from the next algorithm steps. It actually works like selecting units and commanding them in a strategy game. After a 'select' function, all next algorithm steps apply to selected members only, until another 'select' command is issued or the recipe is completed.

 Example:
    // Will send 3 miners to mine for gold.
    select(miner,3);
    locateResource(gold,Explore);
    mine();

SetBuffer

Syntax: setBuffer(target,name,value);

Arguments:

  • 'target' is either selection or tribe.
  • 'name' is the name of the buffer to set.
  • 'value' is the new value to set for Buffer.

For selection this resolve to NBUFFER[name] in recipes and $NBUFFER[name] in behaviors. For tribes this resolve to TBUFFER[name] in recipes and $TBUFFER[name] in behaviors.

This set the buffers used by NPC Variables to replace buffers.

Example:

In an algorithm:

select(Worker,2);
setBuffer(selection,Work_Time,10);
percept(tribe:work);

In a NPC behavior:

<wait duration="$NBUFFER[Work_Time]" />

Wait

Syntax: wait(x);

Arguments:

  • 'x' is an float defining number seconds to halt recipe for.

Effect & Mechanics: This function sets the wait time for a recipe. By default, no recipes with a wait time bigger than 0 are reparsed. As a consequence, applying wait time to a recipe will make the parser halt the current recipe at the current algorithm step and parse other recipes that wait in line. The function will also fire the 'tribe:wait' reaction.