Skip to main content
Version: 🚧 Alpha 🚧

The `gama` platform agent

The unique gama agent represents the running GAMA platform. In addition to platform information, it provides explicit operations for preferences, model execution, tests, and validation. These actions can be called from model code or from the interactive console while an experiment is active.

Preferences​

gama.preferences() lists preferences exposed to GAML with their current values, types, constraints, default values, and restart requirements. Pass a key to inspect one preference:

write gama.preferences("pref_check_memory");

Preference updates are in-memory by default. Set persist: true to write the change to the user's preference store:

gama.set_preference("pref_check_memory", false);
gama.set_preference("pref_check_memory", true, persist: true);
gama.reset_preference("pref_check_memory", persist: true);

The in-memory value is restored when the active experiment closes; a persistent write remains saved in the preference store. Only preferences already marked as GAML-accessible can be inspected or changed this way.

Opening experiments and playable packages​

gama.open(model, experiment) opens an experiment from a model path. If another experiment is active, GAMA asks before closing it. The optional confirm argument can be set to false for deliberate scripted experiment chains:

gama.open("/workspace/Project/model.gaml", "first");
gama.open("/workspace/Project/model.gaml", "second", confirm: false);

Model paths can be absolute file paths or workspace-relative paths. Opening an experiment requires the GUI workbench and does not import the model into the workspace.

A playable .gamx archive is launched separately in its isolated player process:

gama.play_package("/path/to/model.gamx");

Playable packages are not regular .gaml files and cannot be launched through this action in headless mode.

Running tests and validating models​

gama.run_tests(model) synchronously runs the model's test experiments headlessly and returns a summary for each experiment. gama.validate_workspace() compiles every model discovered in the current workspace and returns a success or diagnostic string per model. gama.validate_code(code, syntax_only: true) validates a GAML snippet without executing it:

write gama.run_tests("/workspace/Project/model.gaml");
write gama.validate_workspace();
write gama.validate_code("1 + 1", syntax_only: true);

Workspace validation and test execution can take time on large workspaces. Validation reports compilation diagnostics; it does not execute models. The interactive console itself still requires an active experiment; these actions do not turn it into a standalone platform shell.