Headless Server
Running a Gama Headless server​
Before doing anything, make sure that you possess the rights to create files and directories at the location you are running gama-server because it will need it to create workspaces on the fly.
From the release​
Go to the headless
directory in your Gama installation folder and run the script gama-headless.sh
(or gama-headless.bat
) with the argument -socket
followed by the port number you want your Gama server to run on.
For example on Mac OS you could do:
cd Gama.app/Contents/headless
to move to the right directory, then run the script to listen on port 6868
with:
gama-headless.sh -socket 6868
From the command-line tool​
The users who installed gama through a .deb
file or aur
have access to the command gama-headless
and thus only need to open a terminal and run
gama-headless -socket 6868
to run a Gama server on the port 6868
.
From the source code​
In Eclipse, instantiate a headless server by running msi.gama.headless.id4_full
with the following argument -os ${target.os} -ws ${target.ws} -arch ${target.arch} -nl ${target.nl} -socket 6868
(you can specify any other port)
From docker​
First ensure to pull the official docker image
docker pull gamaplatform/gama:<version>
Then, run the container with the image you just pulled.
Do not forget to (1) expose the port you're starting your server on, and (2) mount your workspace inside the started container as below :
docker run -v <path/to/your/workspace>:/working_dir -p 6868:6868 gamaplatform/gama:<version> -socket 6868
For more informations, please refer to Docker's official documentation or GAMA image's repository.
Connection​
To connect to gama-server as a client you just need to access the following address: ws://<ip>:<port>
. For example if you try to connect to a gama-server running on your current computer and started with the command gama-headless -socket 6868
, you will have to connect to ws://localhost:6868
.
Once a client is connected, gama-server will send a json object of type ConnectionSuccessful
.
General description of interactions​
Once connected, you can ask gama-server to execute different commands to control the execution of different simulations.
If you close your client application (or just close the socket on client-side) gama-server will destroy all running simulations of that client, so you have to keep your client alive.
For every command treated by gama-server, it will send back a json object describing if the command has been executed correctly or if there was a problem. If an unexpected exception is raised in gama-server, it will try to send the connected clients a json-object describing it. The same goes if a simulation throws an exception/error while running, the client that asked for it to run will receive it as a json-object.
In addition, the client can ask gama-server to receive (or not) the different outputs of a simulation: write
statements, dialogs, status-bar changes etc. they will be sent as they come, in a specific json wrapper.
Available commands​
All the commands sent to gama-server must be formatted as a json
object.
The available commands are:
The exit
command​
This command is used to kill gama-server. It is triggered by sending a json object formatted as follows to the server
{
"type": "exit"
}
Answer from gama-server​
It is the only command that won't send back a json object.
The load
command​
This command is used to ask the server to initialize a specific experiment in a gaml file on the server's file-system. It is triggered by sending a json object formatted as follows to the server:
{
"type": "load",
"model": "<gaml_file_path>",
"experiment": "<experiment_name>",
"console": "<console>", //optional
"status": "<status>", //optional
"dialog": "<dialog>", //optional
"runtime": "<runtime>",//optional
"parameters": "<params>", //optional
"until": "<end_condition>", //optional
}
The model
parameter indicates the path of the experiment file on the server's file-system, and experiment
is the actual name of the experiment to run.
The four parameters console
, status
, dialog
and runtime
are booleans used to determine if the messages from respectively the console, the status-bar, the dialogs and the runtime errors should be redirected to the client. They are optional as per default console
and runtime
are set to true
and the two others to false
.
You can add an array of parameters that will be used to initialize the experiment's variables with the values you picked.
The value of parameters
should be formatted as follows:
[
{
"type": "<type of the first parameter>",
"value": "<value of the first parameter>",
"name": "<name of the first parameter in the gaml file>"
},
{
"type": "<type of the second parameter>",
"value": "<value of the second parameter>",
"name": "<name of the second parameter in the gaml file>"
},
...
]
You can also add an ending condition to your simulation with the parameter until
, the condition must be expressed in gaml.
Answer from gama-server​
The content
field of the response json sent by gama-server after processing this command will directly contain the experiment_id
value stored as a string.
The experiment id should be used in all the other commands to refer to that specific experiment in order to control it.
The play
command​
This command is used to actually run an experimented already initialized. It is triggered by sending a json object formatted as follows to the server
{
"type": "play",
"exp_id": "<experiment_id>",
"sync": "<synchronized>", //optional
}
The experiment_id
is used to identify the experiment to play, and the optional sync
is a boolean used in the case where there was an end condition defined in the load
command, if it is true, gama-server will not send a response to the command, but only a end of simulation message once the condition is reached, if it's false gama-server will send both the response to the command and the SimulationEnded
message.
Answer from gama-server​
This command has an empty content
field in the response json sent by gama-server after processing it.
In case where the end condition is reached, a message of type SimulationEnded
is sent to the client with an empty content
.
The pause
command​
This command is used to pause a running experiment. It is triggered by sending a json object formatted as follows to the server
{
"type": "pause",
"exp_id": "<experiment_id>"
}
Answer from gama-server​
This command has an empty content
field in the response json sent by gama-server after processing it.
The step
command​
This command is used to process one (or a defined number of) step(s) of a simulation that has already been loaded. It is triggered by sending a json object formatted as follows to the server
{
"type": "step",
"exp_id": "<experiment_id>",
"nb_step": "<number_of_steps>", //optional
"sync": "<synchronized>", // optional
}
As usual exp_id
refers to the experiment you want to apply the command to. The nb_step
parameter indicates how many steps you want to execute, if you do not give that parameter gama-server will execute one step. The sync
parameter indicates whether gama-server must wait for the end of the step(s) to send back a success message (when its value is true), or just plan the step(s) and send one directly after (when its value is false), this parameter can be ignored and will be interpreted as if it were false
.
Answer from gama-server​
This command has an empty content
field in the response json sent by gama-server after processing it.
The stepBack
command​
This command is used to rollback the simulation one (or a defined number of) step(s) back. This command only works on experiments of type memorize
.
It is triggered by sending a json object formatted as follows to the server
{
"type": "stepBack",
"exp_id": "<experiment_id>",
"nb_step": "<number_of_steps>", //optional
"sync": "<synchronized>", // optional
}
The parameters are exactly the same as in the step
command.
Answer from gama-server​
This command has an empty content
field in the response json sent by gama-server after processing it.
The stop
command​
This command is used to stop (kill) a running experiment. It is triggered by sending a json object formatted as follows to the server
{
"type": "stop",
"exp_id": "<experiment_id>",
}