Tribe Scripting

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

On tribe 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.

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);

Known Arguments: x in { civilised, savage, inhuman }

Effect: Decides the advancement of this tribe. At the moment it acts only as a token. An expression with the same syntax (e.g. "brain(civilised);") can be placed as a requirement.

Aggressivity

Syntax: aggressivity(x);

Known 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);

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 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 }

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

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.

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 Tribes 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(x);

Arguments:

• 'x' is a memory name

Effect & Mechanics: Upon parsing this requirement, the parser checks the memory array for a memory called 'x'. If it is found, requirement is considered met.

Algorithm Steps

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)

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.

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);
    locate(gold);
    mine();

Locate

Syntax: locate(x);

Arguments: 'x' is a memory name.

Effect & Mechanics: This function works like the 'locate operation' from the NPC Scripting. 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);

Arguments: 'x' is a resource name.

Effect & Mechanics: This function works like the above-mentioned 'locate' 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 in the asset array and uploads it's position in the npc's memory buffers.

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.

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 and activates their 'work' behavior on that location for 'x' number of seconds.

Wait

Syntax: wait(x);

Arguments: 'x' is an int defining number of ticks 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.

Mine

Syntax: mine();

Arguments: None.

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

Gather

Syntax: gather();

Arguments: None.

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

Mate

Syntax: mate();

Arguments: None.

Effect & Mechanics: It sends previously selected members to their home and fires their '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.

Attack

Syntax: attack();

Arguments: None.

Effect & Mechanics: It sends previously selected members 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.

Guard

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.