MesaLingua Specification
Design and Development Roadmap for Simplified Agent-Based Modeling
The MesaLingua Project and the MesaScript Language are designed to simplify the process of creating and managing agent-based models (ABMs) using the Mesa library in Python. This project was conceptualized to bridge the gap between beginner and advanced users of Mesa, offering a more intuitive approach to ABM design and implementation. These methods were designed, written, and tested by David Burgess (University of Saskatchewan).
Project Overview
%%{init: {'theme':'neutral'}}%% graph TB AS["MesaLingua"] -- "Translated by" --> ML["MesaLingua Translator"] ML -- "Generates" --> MC["Mesa/Python Code"] MC -- "Runs on" --> MM["Mesa Modeling Framework"] AS -- "Commands include" --> CC["Pre-defined Foundational Commands"] AS -- "Objects include" --> OC["agents,
environments"] AS -- "Attributes include" --> AC["location,
health,
energy"] AS -- "Conditions include" --> CO["if: but if: otherwise:,
when: otherwise:,
before: after:,
first: then: finally:"] CC -- "Lifecycle
Actions" --> LifecycleActions["create,
delete,
reproduce,
die,
rest,
wake up,
prioritize"] CC -- "Movement
Actions" --> MovementActions["move to/toward,
move randomly,
navigate,
avoid
follow"] CC -- "Attribute
Modification
Actions" --> AttributeModificationActions["change,
increase,
decrease"] CC -- "Environmental
Interaction
Actions" --> EnvironmentalActions["gather,
drop,
modify
environment,
forage,
seek shelter"] CC -- "Communication
Actions" --> CommunicationActions["communicate,
broadcast,
send data,
receive data"] CC -- "Timer
Actions" --> TimerActions["wait,
schedule"] CC -- "Learning
and
Perception
Actions" --> LearningActions["learn,
adapt,
perceive,
sense"] CC -- "Evolution
and
Survival
Actions" --> FitnessActions["regenerate,
mutate,
evolve,
metabolize"] CC -- "Economic
and
Interaction
Actions" --> TradeActions["trade,
buy,
sell,
price,
produce,
consume,
interact,
cooperate,
compete"] CC -- "Network
and
Connectivity
Actions" --> NetworkActions["connect,
disconnect"] CC -- "Social
and
Cultural
Actions" --> SocialActions["celebrate,
migrate"] subgraph ProjectComponents[" "] AS ML MC MM subgraph MesaScriptLanguage[" "] OC CC AC CO LifecycleActions MovementActions AttributeModificationActions EnvironmentalActions CommunicationActions TimerActions LearningActions FitnessActions TradeActions NetworkActions SocialActions end end linkStyle 0 fill:#ffffff,stroke:#222222,stroke-width:2px; linkStyle 1 stroke:#222222,stroke-width:2px; linkStyle 2 stroke:#222222,stroke-width:2px; linkStyle 3 stroke:#222222,stroke-width:2px; linkStyle 4 stroke:#222222,stroke-width:2px; style ProjectComponents fill:#ffffff,stroke:#000000,stroke-width:1px; style MesaScriptLanguage fill:#ffffff,stroke:#000000,stroke-width:1px;
Summary

The MesaLingua and MesaScript project is designed to help beginners learn agent-based modelling (ABM) using a simplified language called MesaScript. MesaScript commands are translated into Mesa/Python code by the MesaLingua Translator, and the generated code is implemented on the Mesa modeling framework.

MesaScript includes commands for creating, moving, and following objects, among other actions. Objects in the language include agents (individuals, resources, environmental factors, and other objects) and environments, with various attributes like location, health, and movement.

MesaScript Language Specification
Version 0.49n (2024)

Basic Syntactic Conventions

Agent Creation, Randomness, and Commentary

  • action:['create'] number:int=1 "objectAgent:agent_type:str" agents;
    Creates a specified number of agents of a given type.
     
    
create 10 "predator" agents;
    MesaScript


  • action:['create'] number:int=1 "objectAgent:agent_type:str" agents [with .attribute=value:{int, float, bool, str, 'R(expression[; seed:int])'} [... and with .attribute=value:{int, float, bool, str, 'R(expression[; seed:int])'} ...]];
    Creates a specified number of agents of a given type with specific attributes. Attributes are defined using a dot prefix.
     
    
create 1 "prey" agent with .speed = 5;
    MesaScript


  • action:['create'] number:int=1 "objectAgent:agent_type:str" agents based on "baseAgent:agent_type:str" agents [but with .attribute=value:{int, float, bool, str, 'R(expression[; seed:int])'} [... and with .attribute=value:{int, float, bool, str, 'R(expression[; seed:int])'} ...]];
    Creates a new agent type based on (object-oriented inheritance) an existing type with (multiple, using the and with modifier) additional or modified attributes.
     
    
create 20 "fast predator" agents based on "predator" agents but with .speed = 10 and with .health = 20;
    MesaScript


  • action:['create'] number:int=1 "objectAgent:agent_type:str" agents at [.position=](xValue:{int, 'R'}, yValue:{int, 'R'}):tuple;
    Creates a specified number of agents of a given type at random locations on the grid. R values generate random coordinates. (R, _) values may be any integer x, such that 0 < x <= model.grid.width; (_, R) values may be any integer y, such that 0 < y <= model.grid.height
     
    
create 10 "predator" agents at (R, R);
    MesaScript


  • action:['create'] number:int=1 "objectAgent:agent_type:str" agents at [.position=](xValue:{int, 'R'}, yValue:int):tuple;
    Creates a specified number of agents of a given type at random x-coordinates and a specific y-coordinate. (R, _) values may be any integer x, such that 0 < x <= model.grid.width; (_, y) values may be any integer y, such that 0 < y <= model.grid.height
     
    
create 5 "prey" agents at (R, 3);
    MesaScript


  • action:['create'] number:int=1 "objectAgent:agent_type:str" agents at [.position=](xValue:int, yValue:{int, 'R'}):tuple;
    Creates a specified number of agents of a given type at a specific x-coordinate and random y-coordinates. (x, _) values may be any integer x, such that 0 < x <= model.grid.width; (_, R) values may be any integer y, such that 0 < y <= model.grid.height
     
    
create 100 "water" agents at (5, R);
    MesaScript


  • action:['create'] number:int=1 "objectAgent:agent_type:str" agents [with .attribute='R(minValue:{int, float} & maxValue:{int, float}[; seed:int])'[floatDecimal:int=2]];
    Creates a specified number of agents of a given type and assigns a random value for the attribute within the specified range. Integers and floats are generated based on the range; floats can be limited to a specified number of decimal places; where minValue < maxValue and where if minValue !== 0 && maxValue !== 1 then returns int, and where minValue == 0 && maxValue == 1 then returns float. The option to include a random seed value is provided. The bracketed integer that follows a R(0 & 1) statement dictates the number of decimal places to which the random value should be limited. For example, R(0 & 1)[7] will return a random value to seven decimal places (e.g., 0.7487134). Default is two decimal places. Additional parentheses may be used as necessary; standard order of operations will be followed after random values have been rendered.
     
    
create 1 "predator" agent with .speed = R(3 & 12);
create 3 "prey" agents with .strength = (R(0 & 1)[4] * 10);
    MesaScript

    For boolean attributes, R(true) or R(false) provides a 50/50 chance of being true or false. For example:
     
    
create 10 "prey" agents with .scared = R(true);
    MesaScript

    For a list or array of attributes from which a random selection may be made, R(list) may be used. Each value is equally likely to be selected.
     
    
create 5 "food" agents with .nutrition = R("low", "moderate", "high");
    MesaScript


  • action:['create'] number:int=1 "objectAgent:agent_type:str" agents at (xValue:int, yValue:int):tuple [with .attribute=value:{int, float, bool, str, 'R(expression[; seed:int])'} [... and with .attribute=value:{int, float, bool, str, 'R(expression[; seed:int])'} ...]];
    Creates a specified number of agents of a given type at specific coordinates with specific attributes. (x, _) values may be any integer x, such that 0 < x <= model.grid.width; (_, y) values may be any integer y, such that 0 < y <= model.grid.height. The option to include a random seed value is provided. Additional attributes may be defined by using the and with modifier.
     
    
create 100 "dog" agents at (5, 10) and with .speed = 10 and with .health = 80;
    MesaScript


  • # comment
    Allows for the addition of comments to be embedded within a MesaScript statement. Such commentary is ignored by the MesaLingua parcer and lexer.
     
    
# Commentary may be added to any line, following a hash ...
create 1 "predator" agent at (R, R); # ... including here

# ========================================= #
#                                           #
#  So, you can also do this kind of thing.  #
#                                           #
# ========================================= #
    MesaScript


Object Deletion

  • action:['delete'] number:{'X=1', 'all'} "objectAgent:agent_type:str" agents at (xValue:int, yValue:int):tuple;
    Deletes a specified number or all agents of a given type at a specific location. Coordinates must be within the grid boundaries; thus (x, _) values may be any integer x, such that 0 < x <= model.grid.width, and (_, y) values may be any integer y, such that 0 < y <= model.grid.height
     
    
delete all "prey" agents at (10, 10);
    MesaScript


Grid Creation

  • action:['create'] [number:int=1] gridType:{'Moore non-toroidal', 'Moore toroidal', 'von Neumann non-toroidal', 'von Neumann toroidal'}='Moore toroidal' grid [with .size=(xValue:int=100, yValue:int=100):tuple];
    Creates a grid of a specified type (von Neumann or Moore, toroidal or non-toroidal) with a specified size. Coordinates must be positive integers; thus (x, _) values may be any integer x, such that 0 < x < math.inf, and (_, y) values may be any integer y, such that 0 < y < math.inf
     
    
create Moore non-toroidal grid with .size (50, 50);
    MesaScript

    In the absence of a create ... grid ... ; statement, by default, MesaLingua will assume create 1 Moore toroidal grid with .size = (100, 100); was intended.

General Object Actions

  • action:['move'] "objectAgent:agent_type:str" agent to (xValue:int, yValue:int):tuple;
    Moves an agent of a specified type to a given location on the grid. Coordinates must be within the grid boundaries; thus (x, _) values may be any integer x, such that 0 < x <= model.grid.width, and (_, y) values may be any integer y, such that 0 < y <= model.grid.height. The move action is included as a predefined action, as outlined within this specification.
     
    
move "salamander" agent to (5, 5);
    MesaScript


  • "subjectAgent:agent_type:str" agent action:{'x', ... '/z/'} "objectAgent:agent_type:str" agent;
    Specifies an interaction between two agents, where the second agent (objectAgent) is the target of the first agent's (subjectAgent) action. In its English implementation, MesaScript follows a subject-verb-object (SVO or subjectAgent action objectAgent) structure. x actions include all predefined actions, as outlined within this specification; /z/ actions include all extensible actions, as constructed from predefined actions and declared within a MesaScript statement.
     
    
"salamander" agent /bullies/ "insect" agent;
    MesaScript


  • "objectAgent:agent_type:str" agent action:{'x', ... '/z/'};
    Specifies an action that an agent takes. x actions include all predefined actions; /z/ actions include all extensible actions declared within a MesaScript statement.
     
    
"salamander" agent reproduces;
    MesaScript


Multi-Step Actions

{statement};
Multi-step actions are separated by semicolons (;) and are written on separate lines.


move "salamander" agent to (5, 5);
"salamander" agent eats any "insect" agents in .range R(0 & 1);

MesaScript

Defining Agents

define "objectAgent:agent_type:str" agent as:\n
\t[.attribute=value:{int, float, bool, str, 'R(expression[; seed:int])'} [...]];
Defines a new agent without creating an instance on the grid. The definition of the agent follows this line. Agents may be defined before they are used within MesaScript statements or at the time of creation with action:[create]. Agents (re)defined after creation overwrite attributes defined at creation.


define "prey" agent as:
	.hunger 20;
	.health 50;
	every tick:
		increase .hunger by 1;
		if .hunger is less than 10 or greater than 90:
			rest;
		otherwise:
			decrease .health by 1;
			/hunt/;

MesaScript

Defining Actions

define /action:str/ action as:\n
\t{actions:list};
Defines a new action. The definition of the action follows this line. Actions must be defined before they may be used within MesaScript statements.


define /follows/ action as:
	move towards target agent;

define /hunt/ or /hunts/ action as:
	move towards nearest "prey" agent;
	if any "prey" agent in .range 1: 
		delete "prey" agent;
		decrease .hunger by 20;

define /hungry/ action as:
	.health less than 10 or .hunger greater than 70;

define /tired/ action as:
	.energy less than 10;

define /rest/ or /rests/ action as:
	do not move;

define /explore/ or /explores/ action as:
	move randomly;

define /wake up/ or /wakes up/ action as:
	increase .energy by 20;
	.health * 1.005

MesaScript

Conditionality

Conditional actions are declared by using colons (:), are indented, and are written on separate lines.

If, But If, Otherwise

  • condition:['if']:\n
    \t{actions:list}\n
    [condition:['but if']:\n
    \t{actions:list}\n
    condition['otherwise']:\n
    \t{actions:list}];
    Provides behaviour based on meeting a condition established within the statement.
     
    
if any agent is /hungry/:
	the agent /searches/ for "food" agents;
but if the agent is /tired/:
	the agent rests;
otherwise:
	the agent /explores/;

    MesaScript


When, Otherwise

  • condition:['when']:\n
    \t{actions:list}\n
    [condition:['otherwise']:\n
    \t{actions:list}];
    Executes actions based on conditions using a when-otherwise structure.
     
    
when any agent is /hungry/:
	the agent /searches/ for "food" agent;
when the agent is /tired/:
	the agent rests;
otherwise:
	the agent /explores/;

    MesaScript


Some Action, When Successful, Otherwise

  • action;\n
    condition:['when successful']:\n
    \t{actions:list}\n
    [condition:[otherwise]:\n
    \t{actions:list}];
    Executes statements following on when successful: if true is returned in the backend; if false is returned, then executes statements following on otherwise:.
     
    
while any "predator" agent is /hungry/:
	the agent /hunts/ for "prey" agents;
	when successful:
		set the agent .hunger to 0;
		set the agent .health to 80;
	otherwise:
		increase the agent .hunger by 2;
		decrease the agent .health by 1;

    MesaScript


Before, After

  • condition:['before']:\n
    \t{actions:list}\n
    [condition['after']:\n
    \t{actions:list}];
    Executes actions in a sequence based on before and after conditions.
     
    
before any agent eats:
	the agent /searches for food/;
after any agent eats:
	the agent rests;

    MesaScript


First, Then OR Next, Finally

  • condition:['first']:\n
    \t{actions:list}\n
    [{then, next}:\n
    \t{actions:list}]\n
    condition:['finally']:\n
    \t{actions:list};
    Specifies a sequence of actions that are executed in a defined order. The first block is executed initially, followed by the then or next block, and finally, the finally block.
     
    
first the agent wakes up:
	then the agent /searches for food/;
next the agent /explores/;
finally the agent rests;

    MesaScript

    This construct ensures a clear and explicit sequence of actions. The presence of the finally block guarantees that its actions will execute after all preceding actions, even if one of the previous actions fails or encounters an error. This ensures that certain cleanup or concluding actions always take place, which is not guaranteed when simply listing multiple statements sequentially.

While

  • condition:['while']:\n
    \t{actions:list};
    Executes actions while conditions are met.
     
    
while any "prey" agent .energy is less than 50:
	increase "prey" agent .energy by 1;

    MesaScript


Every

  • condition:['every'] interval:{int, int str}='10 ticks':\n
    \t{actions:list};
    Executes actions each time a condition is met.
     
    
every 10 ticks:
	decrease "predator" agent .energy by 1;

    MesaScript


Choose, If, Otherwise

  • condition['choose']:\n
    \tcondition:['if']\n
    \t\t{actions:list};\n
    \tcondition['otherwise']:\n
    \t\t{actions:list};
    ​DEPRICATED as redundant form of if: but if: otherwise:​
    Chooses actions based on conditions.
     
    
choose action based on .energy level:
	if .energy is greater than 50:
		"prey" agent /explores/;
	otherwise:
		"prey" agent rests;
	
    MesaScript



Changing States

In MesaScript, changing the state of an agent is a crucial part of modeling dynamic behaviors. This involves updating attributes based on certain conditions or events within the simulation. The following commands and syntax allow for defining and manipulating states of agents.

Syntax for Changing States

  • action:['change'] "objectAgent:agent_type:str" agent .attribute to value:{int, float, bool, str, (xValue:int, yValue:int):tuple, list};
    Directly change the value of an agent's attribute. The .attribute element is assumed to take on the data type of its most recent value (i.e., if the last value is of type bool, the .attribute will likewise be of type bool, or said otherwise.attribute:bool). As such, any non-type comparison will return false (although, integers 0 and 1 will be treated as synonomys of false and true, respectively, if .attribute:bool).
     
    
change "predator" agent .health to 50;
    MesaScript


  • action:['set'] "objectAgent:agent_type:str" agent .attribute to value:{int, float, str, (xValue:int, yValue:int):tuple};SYNONYM of action:['change']
    Directly sets the value of an agent's attribute.
     
    
set "predator" agent .health to 50;
    MesaScript


  • action:['increase'] "objectAgent:agent_type:str" agent .attribute by value:{int, float};
    Increase the value of an agent's attribute.
     
    
increase "prey" agent .energy by 10;
    MesaScript


  • action:['decrease'] "objectAgent:agent_type:str" agent .attribute by value:{int, float};
    Decrease the value of an agent's attribute.
     
    
decrease "predator" agent .hunger by 5;
    MesaScript


  • condition:['if'] "objectAgent:agent_type:str" agent .attribute comparisonOperator:{'==', '!=', '<', '<=', '>', '>='} value:{int, float, str}:\n
    \t{actions:list};
    Conditionally change the value of an agent's attribute.
     
    
if any "predator" agent .hunger is greater than 20:
	change "predator" agent .health to 30;
    MesaScript


  • condition:['when'] "subjectAgent:agent_type:str" agent action:{'x', ... '/z/'} "objectAgent:agent_type:str" agent:\n
    \t{actions:list};
    Change the value of an agent's attribute based on an interaction with another agent.
     
    
when "predator" agent /hunts/ "prey" agent:
	change "predator" agent .hunger to 0;
    MesaScript


  • action:['change', 'set'] "objectAgent:agent_type:str" agent .attribute to value:{'R(minValue:{int, float} & maxValue:{int, float}[; seed:int])'[floatDecimal:int=2], R(list[; seed:int])};
    Assign a random value within a specified range to an agent's attribute, where minValue < maxValue and where if minValue !== 0 && maxValue !== 1 then returns int, and where minValue == 0 && maxValue == 1 then returns float. The option to include a random seed value is provided. The bracketed integer that follows a R(0 & 1) statement dictates the number of decimal places to which the random value should be limited. For example, R(0 & 1)[7] will return a random value to seven decimal places (e.g., 0.7487134). Default is two decimal places. Additional parentheses may be used as necessary; standard order of operations will be followed after random values have been rendered.
     
    
change "prey" agent .speed to R(3 & 12);
change "preditor" agent .strength to (R(0 & 1) * 5)
    MesaScript


  • action:['append'] "objectAgent:agent_type:str" agent .attribute:list with value:str;EXPERIMENTAL
    Append a value to a list attribute of an agent.
     
    
append "predator" agent .preyList with "rabbit";
    MesaScript


  • action:['update'] "objectAgent:agent_type:str" agent .attribute:dict to value:dict;EXPERIMENTAL
    Update a key-value pair in a dictionary attribute of an agent.
     
    
update "predator" agent .stats to {"speed": 12, "strength": 15};
    MesaScript


Examples of Changing States

  • Health Recovery
    Agents recover health over time or under certain conditions.
     
    
every 5 ticks:
	increase "prey" agent .health by 5;

    MesaScript


  • Energy Consumption
    Agents consume energy while moving or performing actions.
     
    
every step "predator" agent moves:
	decrease "predator" agent .energy by 2;

    MesaScript


  • Resource Gathering
    Agents gather resources, which changes the state of both the agent and the resource.
     
    
"prey" agent "gathers" "food" agent:
	change "prey" agent .energy to 100;
	change "food" agent .quantity to 0;

    MesaScript


  • Reproduction
    Agents reproduce when certain conditions are met, changing their state and possibly creating new agents.
     
    
if any "prey" agent .energy is greater than 80:
	"prey" agent reproduces;
	change "prey" agent .energy to 50;

    MesaScript


Conditional Actions with State Changes

  • Behavior Based on Health
    Example:
     
    
if any "predator" agent .health is less than 20:
	"predator" agent rests;
otherwise:
	"predator" agent /hunts/;

    MesaScript


  • Energy-Based Movement
    Example:
     
    
if any "prey" agent .energy is less than 10:
	change "prey" agent .speed to 2;
otherwise:
	change "prey" agent .speed to 5;

    MesaScript


Integrating State Changes into Models

State changes are integral to creating dynamic and realistic agent behaviors in simulations. By incorporating state changes, you can model complex interactions and adaptive behaviors.

Example Model: Predator-Prey Dynamics with State Changes

create 10 "predator" agents with .hunger 20;
create 50 "prey" agents with .energy 50;

every tick:
	if any "predator" agent .hunger is greater than 15:
		"predator" agent /hunts/ "prey" agent:
			when successful:
				change "predator" agent .hunger to 0;
				change "prey" agent .health to 0;
	otherwise:
		"predator" agent rests;

	increase "prey" agent .energy by 5;
	if any "prey" agent .energy is greater than 80:
		"prey" agent reproduces;
		change "prey" agent .energy to 50;
	
model

This example shows how state changes can drive the behaviors of agents in a predator-prey model, creating a dynamic and evolving simulation.
 

Pre-Defined Actions in MesaScript

MesaScript provides a set of foundational actions that can be used to define more complex behaviors. Actions are usable in any present form of a verb in any person (first, second, or third). Here are examples of each predefined action, organized by their category:

Lifecycle Actions

  • create
    action:literal['create', 'creates'] [value:literal[int, 'a', 'an', 'any', 'all']=1] "type:str" objectAgent:object at [.position[=]](Literal:[xValue:int, 'R'], Literal:[yValue:int, 'R']):tuple
    Creates a given number of agents at a given or random location on the grid.
     
    
create 10 "predator" agents at (R, R);
    MesaScript


  • delete
    action:literal['delete', 'deletes'] [value:literal[int, 'a', 'an', 'any', 'all']='all'] [type:literal[str, 'any']='any'] objectAgent:object [at [.position[=]](Literal:[xValue:int, 'R'], Literal:[yValue:int, 'R']):tuple=agent.pos()]
    Deletes agents, by default at their current position on the grid.
     
    
delete "prey" agents at (5, 5);
    MesaScript


  • reproduce
    [value:literal[int, 'a', 'an', 'any', 'all']='all'] [type:literal[str, 'any']='any'] subjectAgent:object action:literal['reproduce', 'reproduces'] [at [.position[=]](Literal:[xValue:int, 'R'], Literal:[yValue:int, 'R']):tuple=agent.pos()]
    Agents reproduce, by default at their current position on the grid.
     
    
"prey" agent reproduces;
    MesaScript


  • die
    action:literal['die', 'dies'] ... SYNONYM of delete
    Agents die, by default at their current position on the grid.
     
    
"prey" agent dies;
    MesaScript


  • rest
    [value:literal[int, 'a', 'an', 'any', 'all']='all'] [type:literal[str, 'any']='any'] subjectAgent:object action:literal['rest', 'rests'] [at [.position[=]](Literal:[xValue:int, 'R'], Literal:[yValue:int, 'R']):tuple=agent.pos()]
    Agents rest, by default at their current position on the grid.
     
    
"predator" agent rests;
    MesaScript


  • wake up
    [value:literal[int, 'a', 'an', 'any', 'all']='all'] [type:literal[str, 'any']='any'] subjectAgent:object action:literal['wake up', 'wakes up'] [at [.position[=]](Literal:[xValue:int, 'R'], Literal:[yValue:int, 'R']):tuple=agent.pos()]
    Agents wake up, by default at their current position on the grid.
     
    
"prey" agent wakes up;
    MesaScript


  • prioritize
    [value:literal[int, 'a', 'an', 'any', 'all']='all'] [type:literal[str, 'any']='any'] subjectAgent:object action:literal['prioritize', 'prioritizes'] action1:literal['a' ... '/z/'] over action2:literal['a' ... '/z/']
    Agents prioritize different actions that may be taken, where action1 !== action2 and where action1 is given higher priority than action2.
     
    
"predator" agent prioritizes /hunt/ over rest;
    MesaScript


Movement Actions

  • move to
    move X to Y OR moves X to Y
    Moves an agent to a specified location.
     
    
"predator" agent moves to (10, 10);

    MesaScript


  • move ... to
    move X to Y ANALOGUE of move to
    Moves an agent to a specified location.
     
    
move "predator" agent to (10, 10);

    MesaScript


  • move toward
    move X toward Y OR moves X toward Y
    Moves an agent in a general direction, including north, south, east, west, northwest, northeast, southwest, southeast, as well as (0, 1), (0, -1), (1, 0), (-1, 0), (-1, 1), (1, 1), (-1, -1), (1, -1).
     
    
"prey" agent moves toward (0, -1);
move "predator" agent toward northwest;
    MesaScript


  • move ... toward
    move X toward Y ANALOGUE of move toward
    Moves an agent in a general direction, including north, south, east, west, northwest, northeast, southwest, southeast, as well as (0, 1), (0, -1), (1, 0), (-1, 0), (-1, 1), (1, 1), (-1, -1), (1, -1).
     
    
move "prey" agent toward (0, -1);
move "predator" agent toward northwest;
    MesaScript


  • move randomly
    move X randomly OR moves X randomly
    Moves an agent to a random location.
     
    
"prey" agent moves randomly;
    MesaScript


  • move ... randomly
    move X randomly ANALOGUE of move randomly
    Moves an agent to a random location.
     
    
move "prey" agent randomly;
    MesaScript


  • navigate toward
    X navigate toward Y SYNONYM of move toward
    Agents navigate through the environment in the direction of other specific agents or types of agents.
     
    
"predator" agent navigates toward nearest "prey" agent;
    MesaScript


  • avoid
    X avoid Y OR X avoids Y
    Agents avoid certain agents or locations.
     
    
"prey" agent avoids "predator" agents;
    MesaScript


  • follow
    X follow Y OR X avoids Y
    Agents avoid certain agents or locations.
     
    
"prey" agent avoids "predator" agents;
    MesaScript


Attribute Modification Actions

  • change X to Y OR changes X to Y
    Directly changes an agent's attribute.
     
    
change "predator" agent .health to 50;
    MesaScript


  • increase X by Y OR increases X by Y
    Increases an agent's attribute.
     
    
increase "prey" agent .energy by 10;
    MesaScript


  • decrease X by Y OR decreases X by Y
    Decreases an agent's attribute.
     
    
decrease "predator" agent .hunger by 5;
    MesaScript


Conditional Actions

  • if X
    Executes actions based on conditions.
     
    
if any "predator" agent .hunger is greater than 20:
	change "predator" agent .health to 30;

    MesaScript


  • while X
    Executes actions while conditions are met.
     
    
while any "prey" agent .energy is less than 50:
	increase "prey" agent .energy by 1;

    MesaScript


  • choose: if: otherwise:​DEPRICATED as redundant form of if: but if: otherwise:​
    Chooses actions based on conditions.
     
    
choose action based on .energy level:
	if .energy is greater than 50:
		"prey" agent /explores/;
	otherwise:
		"prey" agent rests;
	
    MesaScript


Environmental Interaction Actions

  • X gather Y OR X gathers Y
    Agents gather resources.
     
    
"prey" agent gathers "food" agent;
    MesaScript


  • X drop Y OR X drops Y
    Agents drop resources.
     
    
"prey" agent drops "food" agent;
    MesaScript


  • X modify environment OR X modifies environment
    Agents modify the environment.
     
    
"prey" agent modifies environment;
    MesaScript


  • X forage OR X forages
    Agents forage for resources.
     
    
"prey" agent forages;
    MesaScript


  • X seek shelter OR X seeks shelter
    Agents seek shelter.
     
    
"prey" agent seeks shelter;
    MesaScript


Communication Actions

  • X communicate with Y OR X communicates with Y
    Agents communicate with each other.
     
    
"prey" agent communicates with "prey" agent;
    MesaScript


  • X broadcast value of Y OR X broadcasts value of Y
    Agents broadcast information.
     
    
"prey" agent broadcasts .danger;
    MesaScript


  • X send value of Y to Z value of A OR X sends value of Y to Z value of A OR X send key and value pair of Y to Z value of A OR X sends key and value pair of Y to Z value of A
    Agents send data to other agents.
     
    
"prey" agent sends .id and .height to "predator" agent .heightRecord;
    MesaScript


  • X receive value of Y from Z value of A OR X receives value of Y from Z value of A OR X receive key and value pair of Y from Z and A values of B OR X receives key and value pair of Y from Z and A values of B
    Agents receive data from other agents.
     
    
"prey" agent receives data from "predator" agent;
    MesaScript


Timer Actions

  • X wait Y ticks OR X waits Y ticks
    Agents wait for a specified amount of time.
     
    
"predator" agent waits 5 ticks;
    MesaScript


  • schedule X to Y in Z ticks OR schedules X to Y in Z ticks
    Schedules actions to occur after a specified amount of time.
     
    
schedule "prey" agent to /gather/ in 10 ticks;
    MesaScript


Resource Management Actions

  • X consume Y OR X consumes Y OR X eat Y OR X eats Y OR X destroy Y OR X destroys Y
    Agents consume or eat or destroy another agent.
     
    
"predator" agent eats "food" agent;
    MesaScript


  • X produce Y OR X produces Y OR X make Y OR X makes Y OR X build Y OR X builds Y
    Agents produce or make or build another agent.
     
    
"prey" agent produces "food" agent;
    MesaScript


  • X metabolize Y into attribute Z value OR X metabolizes Y into attribute Z value OR X convert Y into attribute Z value OR X converts Y into attribute Z value
    Agents metabolize or convert other agents.
     
    
"prey" agent metabolizes "food" agent into .energy 100;
    MesaScript


Learning and Perception Actions

  • X learn from Y OR X learns from Y
    Agents learn from their experiences.
     
    
"predator" agent /learns from hunt/ ;
    MesaScript

    This action can be used to simulate the improvement of an agent's attributes based on past experiences. For example, a predator might increase its hunting skill after each successful hunt.

    In Python using Mesa, "learning" can be implemented as updating agent attributes based on experiences. For example, a predator might learn to improve its hunting efficiency after successful hunts.

    
class PredatorAgent(Agent):
    def __init__(self, unique_id, model):
        super().__init__(unique_id, model)
        self.hunting_skill = 1.0

    def hunt(self):
        # Attempt to hunt prey
        prey = self.find_prey()
        if prey:
            self.hunting_skill += 0.1  # Improve hunting skill after a successful hunt

    def find_prey(self):
        # Logic to find prey
        pass

    Python: learnsFromHunt.py

    In MesaScript, this would be:

    
define action /learns from hunt/ as:
    increase .hunting_skill by 0.1;

    MesaScript
  • X adapt to Y OR X adapts to Y
    Agents adapt to changes in their environment.
     
    
"prey" agent adapts to "predator" agent presence;
    MesaScript

    This action can be used to adjust an agent's behavior or attributes based on external stimuli. For example, prey might increase its speed when predators are nearby.

    Adapting to the presence of other agents can be modeled as changing behavior based on perceived threats. For instance, prey might increase their speed or change their movement pattern when predators are nearby.

    
class PreyAgent(Agent):
    def __init__(self, unique_id, model):
        super().__init__(unique_id, model)
        self.speed = 1.0

    def step(self):
        if self.model.predators_nearby(self.pos):
            self.adapt()

    def adapt(self):
        self.speed *= 1.5  # Increase speed when predators are nearby

    Python: adaptsToPresence.py

    In MesaScript, this would be:

    
define action /adapts to predator presence/ as:
    change .speed to .speed * 1.5;

    MesaScript
  • X perceive Y OR X precieves Y
    Agents perceive their surroundings.
     
    
"predator" agent perceives "prey" agent;
    MesaScript

    Perception involves detecting other agents within the environment and updating internal state or attributes accordingly. For example, a predator might set a target prey after perceiving it in the environment.

    This can be implemented as checking the agent's surroundings and updating internal state or attributes accordingly.

    
class PredatorAgent(Agent):
    def __init__(self, unique_id, model):
        super().__init__(unique_id, model)
        self.target_prey = None

    def perceive_prey(self):
        # Check for prey in the neighborhood
        neighbors = self.model.grid.get_neighbors(self.pos, moore=True, radius=2)
        prey = [agent for agent in neighbors if isinstance(agent, PreyAgent)]
        if prey:
            self.target_prey = prey[0]  # Set the first prey found as the target

    Python: learnsFromHunt.py

    In MesaScript, this would be:

    
define action /perceives prey/ as:
    if any "prey" agent in range 2:
        set .target_prey to first "prey" agent in range 2;

    MesaScript
  • X sense Y OR X senses Y
    Agents sense their environment.
     
    
"prey" agent senses "predator" presence;
    MesaScript

    Sensing can involve more complex perception mechanisms, such as detecting the presence of agents or environmental changes. For example, prey might update its safety status based on the presence of predators.

    
class PreyAgent(Agent):
    def __init__(self, unique_id, model):
        super().__init__(unique_id, model)
        self.is_safe = True

    def sense_predator_presence(self):
        neighbors = self.model.grid.get_neighbors(self.pos, moore=True, radius=3)
        predators = [agent for agent in neighbors if isinstance(agent, PredatorAgent)]
        self.is_safe = len(predators) == 0  # Update safety status based on predator presence

    Python: learnsFromHunt.py

    In MesaScript, this would be:

    
define action /senses predator presence/ as:
    if any "predator" agent in range 3:
        set .is_safe to false;
    otherwise:
        set .is_safe to true;

    MesaScript

Evolution and Survival Actions

  • X regenerate Y OR X regenerates Y
    Agents regenerate lost attributes.
     
    
"prey" agent regenerates .health;
    MesaScript


  • X mutate Y OR X mutates Y
    Agents undergo mutation.
     
    
"prey" agent mutates .speed;
    MesaScript


  • X evolve Y OR X evolves Y
    Agents evolve over generations.
     
    
"prey" agent /evolves to adapt/ to "predator" agent;
    MesaScript


  • X metabolize Y to Z OR X metabolizes Y to Z
    Agents metabolize resources.
     
    
"prey" agent metabolizes "food" agent to .energy;
    MesaScript


Economic and Interaction Actions

  • trade
    Agents trade resources.
     
    
"prey" agent trades .food with "predator" agent;
    MesaScript


  • buy
    Agents buy resources.
     
    
"prey" agent buys .food from "predator" agent;
    MesaScript


  • sell
    Agents sell resources.
     
    
"predator" agent sells .food to "prey" agent;
    MesaScript


  • price
    Sets the price of resources.
     
    
sets the price of .food to 5;
    MesaScript


  • produce
    Agents produce goods.
     
    
"prey" agent produces 3 .food;
    MesaScript


  • consume
    Agents consume goods.
     
    
"predator" agent consumes 2 .food;
    MesaScript


  • interact
    Agents interact with each other.
     
    
"predator" agents interact with "prey" agents;
    MesaScript


  • cooperate
    Agents cooperate with each other.
     
    
"prey" agents cooperate with "prey" agents;
    MesaScript


  • compete
    Agents compete with each other.
     
    
"predator" agents compete with "predator" agents;
    MesaScript


Network and Connectivity Actions

  • connect
    Agents connect with each other.
     
    
"positive node" agents connect with "negative node" agents;
    MesaScript


  • disconnect
    Agents disconnect from each other.
     
    
"positive node" agents disconnect from "negative node" agents;
    MesaScript


Social and Cultural Actions

  • celebrate
    Agents celebrate events.
     
    
"predator" agents celebrate;
    MesaScript


  • migrate
    Agents migrate to new locations.
     
    
"prey" agents migrate to (10, 10);
    MesaScript


Extensibility with New Actions

The extensibility of MesaScript allows for the combination of foundational actions to define more complex behaviors. Extensible actions may be defined (and if so defined, must be) in multiple present forms of a verb in any number of persons (first, second, or third) through the use of "or". Prepositions (and other articles or modifiers) are required if they are to be expected and interpreted correctly by the MesaLingua lexer and parcer. The exception I don't know what "X" means. will be thrown by the parcer, and the process will fail, if the parcer encounters a new action that is not earlier defined. Here are some examples of new actions that can be defined using existing foundational actions:

Hunting

Combining movement and interaction actions to create a complex behavior.


define action /hunt/ or /hunts/ as:
	move towards nearest "prey" agent;
	if any "prey" agent in .range 1:
		"predator" agent /attacks/ "prey" agent;
		change "predator" agent .hunger to 0;
		change "prey" agent .health to 0;
MesaScript
Patrolling

Combining movement and sensing actions to create a patrolling behavior.


define action /patrol/ or /patrols/ as:
	move randomly;
	if sense "predator" agent in .range 5:
		move away from "predator" agent;
MesaScript
Resource Sharing

Combining interaction and resource management actions to create a resource-sharing behavior.


define action /share resources with/ or /shares resources with/ as:
	if "prey" agent .energy is greater than 50:
		"prey" agent gives 10 .energy to "prey" agent;
MesaScript
Cooperative Defense

Combining communication, movement, and interaction actions to create a cooperative defense behavior.


define action /cooperate in defense of/ or /cooperates in defense of/ or /cooperate in the defense of/ or /cooperates in the defense of/ as:
	if sense "predator" agent in .range 5:
		set .danger to true;
		broadcast .danger to all "prey" agents;
		move towards nearest "prey" agent;
		if within .range 1 of other "prey" agent:
			"prey" agent /defends against/ "predator" agent;
MesaScript
Migration

Combining movement, sensing, and state-based actions to create a migration behavior.


define action "migrate to" or "migrates to" as:
	if "prey" agent .energy is greater than 50:
		move towards (10, 10);
		if any "prey" agent in .range 5:
			move towards nearest "prey" agent;
MesaScript


MesaLingua Translation Platform
Version 0.2 (2024)
  1. Define the Language Mapping
    Clearly define how MesaScript maps to Mesa/Python code for each command.
  2. Design the Translator
    Create a Python or JavaScript script that takes MesaScript commands as input and outputs the corresponding Mesa/Python code.
  3. Create a Web Interface
    Develop a frontend where users can enter MesaScript commands and view the generated Mesa model and its visualization.
  4. Backend Development
    Accept MesaScript commands from the frontend, send them to the translator, and return the generated Mesa/Python code and visualization.
  5. Integration with Mesa
    Implement a secure and efficient way to run Mesa/Python code on the server side.
  6. Visualization
    Integrate Mesa's visualization capabilities into the platform.
  7. Testing and Iteration
    Test extensively, fix bugs, and improve based on user feedback.
Additional Considerations
Lexer and Parser Design
MesaScript is a domain-specific language (DSL) designed to translate commands via the MesaLingua Workflow into executable Python code (using the Mesa library) for agent-based modeling. The following sections outline the key components of MesaScript's lexer and parser design, highlighting flexibility and the workflow integration.

Syntactic Flexibility

One of the primary goals of MesaScript is to provide a flexible syntax that accommodates natural language elements. This allows users with little to no programming experience to define agent behaviors intuitively. Below are examples showcasing the flexibility of MesaScript:

Example 1: Object Creation with Optional Syntax

create 10 "predator" agents;
create "predator" agents with "hunger" 20;
create "predator" agents;  # Default number can be 1

examples
Example 2: Natural Language Commands

if any "predator" agent's hunger is > 15:
    "predator" agent /hunts/ "prey" agent;
otherwise:
    "predator" agent rests;

MesaScript
Example 3: Error Tolerance

create 10 "predator" agents;  # Correct
create "predator" agents with hunger 20;  # Missing quotes around "hunger"

example with error

Domain-Specific Language (DSL) Nature of MesaLingua

MesaLingua is designed as a DSL to cater specifically to agent-based modeling. It focuses on providing simple, yet powerful, commands that directly translate to Mesa's Python API. This allows users to create and manipulate agents, define their interactions, and set up the environment without requiring deep programming knowledge.

Key Features of MesaLingua DSL

MesaLingua Workflow

The MesaLingua Workflow involves translating high-level commands written in MesaScript into executable Python code using the Mesa library. The workflow consists of the following steps:

  1. Grammar Definition
    Set of rules describing the possible combinations of phrases.
  2. Lexer Design
    Recognize and tokenize the various parts of a command.
     
    
import ply.lex as lex

tokens = (
    'CREATE', 'SPAWN', 'AGENT', 'NUMBER', 'STRING', 'IF', 'HUNGER', 'HUNTS',
    'INCREASE', 'DECREASE', 'ATTRIBUTE', 'IS', 'GREATER_THAN', 'THAN', 'BY', 'SEMICOLON',
)

# Regular expression rules for simple tokens
t_CREATE = r'create|spawn'
t_IF = r'if'
t_HUNTS = r'hunts'
t_INCREASE = r'increase'
t_DECREASE = r'decrease'
t_IS = r'is'
t_GREATER_THAN = r'greater than|>'

# A regular expression rule with some action code
def t_NUMBER(t):
    r'\d+'
    t.value = int(t.value)    
    return t

def t_STRING(t):
    r'\".*?\"'
    return t

# Define a rule so we can track line numbers
def t_newline(t):
    r'\n+'
    t.lexer.lineno += len(t.value)

# A string containing ignored characters (spaces and tabs)
t_ignore  = ' \t'

# Error handling rule
def t_error(t):
    print(f"Illegal character '{t.value[0]}'")
    t.lexer.skip(1)

# Build the lexer
lexer = lex.lex()

def lexer(input_text):
    lexer.input(input_text)
    tokens = []
    while True:
        tok = lexer.token()
        if not tok:
            break
        tokens.append(tok)
    return tokens

    Python: lexer.py
  3. Parser Design
    Interpret tokens according to predefined rules and translate them into a format for execution.
     
    
import ply.yacc as yacc

def p_command(p):
    '''command : create_command
               | conditional_command
               | action_command'''
    p[0] = p[1]

def p_create_command(p):
    '''create_command : CREATE NUMBER STRING AGENT SEMICOLON
                      | CREATE STRING AGENT SEMICOLON'''
    if len(p) == 5:
        p[0] = ('create', p[2], p[3])
    else:
        p[0] = ('create', p[2])

def p_conditional_command(p):
    '''conditional_command : IF STRING AGENT ATTRIBUTE IS GREATER_THAN NUMBER COLON action_command'''
    p[0] = ('if', p[2], p[3], p[4], '>', p[6], p[8])

def p_action_command(p):
    '''action_command : STRING AGENT HUNTS STRING AGENT SEMICOLON
                      | STRING HUNTS STRING SEMICOLON'''
    if len(p) == 7:
        p[0] = ('hunts', p[2], p[4])
    else:
        p[0] = ('hunts', p[1], p[3])

# Error rule for syntax errors
def p_error(p):
    print(f"Syntax error at '{p.value}'")

# Build the parser
parser = yacc.yacc()

def parse(tokens):
    return parser.parse(tokens)

    Python: parser.py
  4. Integration with Backend
    Call appropriate Mesa/Python functions based on parsed commands.
     
    
def interpret(parsed_command):
    if parsed_command[0] == "create":
        create_agent(parsed_command[2]) # where parsed_command[2] is the agent's name, e.g., "predator"
    elif parsed_command[0] == "if":
        # Implement the conditional logic here
        pass
    elif parsed_command[0] == /hunts/:
        # Implement the action logic here
        pass
    # ... among other actions

def create_agent(agent_name):
    print(f"Creating agent: {agent_name}")
    # Add actual agent creation logic here

# Example usage
input_text = 'create 10 "predator" agents;'
tokens = lexer(input_text)
parsed_command = parse(tokens)
interpret(parsed_command)

    Python: interpret.py

Abstract Syntax Trees (ASTs)

An Abstract Syntax Tree (AST) represents the hierarchical structure of source code, capturing its syntactic and semantic structure. ASTs are crucial for interpreting and translating high-level commands into executable code. Below are examples of ASTs for MesaScript commands:

Example 1: CreateStatement

CreateStatement
  ├── Number(10)
  ├── AgentType("predator")
  └── Action(agents)

MesaScript
Example 2: IfStatement

IfStatement
  ├── Condition
  │    ├── AgentType("predator")
  │    └── Attribute("hunger")
  ├── ComparisonOperator(is greater than)
  ├── Value(15)
  └── Action
       ├── AgentType("predator")
       └── Command(/hunts/, "prey")

MesaScript
Example 3: Complex IfStatement

IfStatement
  ├── Condition
  │    ├── AgentType("predator")
  │    └── Attribute("hunger")
  ├── ComparisonOperator(is greater than)
  ├── Value(20)
  └── Actions
       ├── Action
       │    ├── AgentType("predator")
       │    └── Command(/hunts/, "prey")
       └── Action
            ├── AgentType("predator")
            └── Command("rests")

MesaScript

Using ASTs, MesaLingua can efficiently parse and interpret commands, making it easier to create complex agent-based models with intuitive syntax.

Challenges
Unresolved Questions
Future Developments
Next Steps
MesaScript Type Hints Guide
Understanding and Implementing Type Hints in MesaScript
MesaScript type hints provide a structured and flexible way to specify agent behaviors and interactions in simulations. This method uses specific syntax elements to indicate types and roles of agents and their attributes, allowing for both strict and flexible command interpretations. Below is a detailed explanation of how to understand and implement these type hints:
Key Concepts
Type Hints Explained

Each component of the type hints structure plays a critical role in defining the syntax and semantics of MesaScript commands. Here is a detailed explanation:

subjectAgent

The agent performing the action. This is the primary agent that initiates the command. In the following, this is represented by the "predator" agent:

"predator" agent /hunts/ "prey" agent

objectAgent

The target agent of the action. This is the agent that is affected by the action performed by the subjectAgent. In the following, this is represented by the "prey" agent:

"predator" agent /hunts/ "prey" agent

type

The type of agent or object involved. This specifies the kind or category of agents or objects. Examples include:

"predator", "prey", "food", "grid"

action

The action to be performed by the subjectAgent or performed upon the objectAgent involved. Actions define what the agents do in the simulation. Examples include:

create, eat, gather, move, rest, /learn from hunting/, /age/

attribute

A specific characteristic of an agent. Attributes define properties that agents possess and can be modified. Examples include:

.speed, .health, .energy, .position

value

Numerical values for attributes. Values define the magnitude or quantity of an attribute. Examples include:

10, 5.5, 100, random, randomly

literal

Fixed values or strings. Literals are exact representations used within commands. Examples include:

Moore toroidal, grid

[...]

Optional elements in the command. Optional elements provide additional flexibility by allowing or omitting certain parts of a command. Examples include:

... and with .attribute[=]value:[int, float]
Creation Statement

Syntax

create value=1:literal[int, 'a':{'alias':1}] "type:str" subjectAgent:object based on "type:str" objectAgent:object but with .attribute[=]value:[int, float] [... and with .attribute[=]value:[int, float] ...];

Example

create 5 "predator" agents based on "fast predator" agents but with .speed=10 and with .strength=15;
Conditional Statements

Syntax

if value='any':literal[int, ['the', 'a', 'an']:self.conditionalAgent, ['any', 'all', 'each']:model.schedule.conditionalAgent] "type:str" conditionAgent:object .attribute comparisonOperator value:float:  "type:str" subjectAgent:object action [...];

Example

if any "predator" agent .hunger is greater than 20: "predator" agent /hunts/ "prey" agent;
Movement Actions

Syntax

action:['move'] "type:str" subjectAgent:object to (xValue:int, yValue:int);

Example

move "predator" agent to (10, 10);

Random movement

action:['move'] "type:str" subjectAgent:object randomly;

Example

move "prey" agent randomly;
Attribute Modification

Change

action:['change'] subjectAgent:object .attribute[=]value:[int, float];

Increase

action:['increase'] subjectAgent:object .attribute by value:[int, float];

Decrease

action:['decrease'] subjectAgent:object .attribute by value:[int, float];

Example

change "prey" agent .health=50;
Interaction Actions

Syntax

subjectAgent:object action objectAgent:object;

Example

"predator" agent /hunts/ "prey" agent;
Benefits of Using Type Hints
Implementing Type Hints
  1. Define Actions: Use type hints to define possible actions and interactions within your simulation.
  2. Write Commands: Follow the specified syntax structures to write commands that the lexer and parser can interpret.
  3. Test: Regularly test commands to ensure they are correctly interpreted and executed within the Mesa framework.
Example Usage in Context

Conditional Actions

if any "predator" agent .hunger > 15:
    "predator" agent /hunts/ "prey" agent:
        change "predator" agent .hunger=0;
        change "prey" agent .health=0;
otherwise:
    "predator" agent rests;

Complex Interactions

"prey" agent gathers "food" agent:
    increase "prey" agent .energy by 20;
    decrease "food" agent .quantity by 1;
Type Hints for Various MesaScript Commands

Creation Statements

Basic Creation
action:['create'] value=1:int "type:str" objectAgent:object;
Example
create 10 "predator" agents;
Creation with Attribute
action:['create'] value=1:int "type:str" objectAgent:object with .attribute[=]value:[int, float];
Example
create 5 "prey" agents with .speed=3.5;
Creation Based on Existing Agent
action:['create'] value=1:int "type:str" objectAgent:object based on "type:str" objectAgent:object but with .attribute[=]value:[int, float] [... and with .attribute[=]value:[int, float] ...];
Example
create 20 "fast predator" agents based on "predator" agents but with .speed=10;
Creation at Random Location
action:['create'] value=1:int "type:str" objectAgent:object at [.position=](RValue:int, RValue:int):tuple;
Example
create 10 "predator" agents at (RValue:int, RValue:int);
Creation at Random X, Fixed Y
action:['create'] value=1:int "type:str" objectAgent:object at [.position=](RValue:int, yValue:int):tuple;
Example
create 5 "prey" agents at (R, 3);
Creation at Fixed X, Random Y
action:['create'] value=1:int "type:str" objectAgent:object at [.position=](xValue:int, RValue:int):tuple;
Example
create 100 "water" agents at (5, R);
Creation with Random Attribute Value
action:['create'] value=1:int "type:str" objectAgent:object with .attribute[=]R(minValue:literal[int, float] & maxValue:literal[int, float]);
Example
create 1 "predator" agent with .speed=R(3 & 12);
Creation at Specific Location with Attributes
action:['create'] value=1:int "type:str" objectAgent:object at [.position=](xValue:int, yValue:int):tuple and with .attribute[=]value:[int, float] [... and with .attribute[=]value:[int, float] ...];
Example
create 1 "predator" agent at (5, 5) and with .speed=4 and with .strength=7;
Deletion Statements

Deletion

action:['delete'] X:literal[0<x<=len(model.schedule.agents):int, 'all'] "type:str" objectAgent:object at [.position=](xValue:int, yValue:int):tuple;

Example

delete all "prey" agents at (10, 10);
Grid Creation

Grid Creation

action:['create'] [X=1] type:literal['Moore non-toroidal', 'Moore toroidal', 'von Neumann non-toroidal', 'von Neumann toroidal']='Moore toroidal' grid:literal['grid':object,'multigrid':object]='grid':object [with .size[=]](xValue=100:int, yValue=100:int):tuple;

Example

create Moore toroidal grid with .size=(50, 50);
Action Statements

Movement Action

action:literal['move']='move' "type:str" objectAgent:object to [.position=](xValue:int, yValue:int):tuple;

Example

move "predator" agent to (10, 10);

Interaction Action

"type:str" subjectAgent:object action:literal[x, ... /z/] "type:str" objectAgent:object;

Example

"predator" agent /hunts/ "prey" agent;

Agent-Specific Action

"type:str" objectAgent:object action:literal[x, ... /z/];

Example

"predator" agent rests;
Summary

These type hints provide a clear and consistent way to define commands in MesaScript. The structure ensures that each element of the command is well-defined, allowing for both specific and flexible syntax that caters to various modeling needs.