Skip to main content
Version: 🚧 Alpha 🚧

Developing Extensions

GAML can be extended without modifying GAMA itself: new skills, statements, operators, types, species, control architectures, file types, displays... are written in Java, in an Eclipse/OSGi plugin, and loaded by GAMA at startup. Two mechanisms work together:

  1. The plugin declares that it contributes to GAML through the gaml.extension extension point (in its plugin.xml) and depends on gama.core (which re-exports gama.api, gama.annotations and gama.processor). See Developing Plugins.
  2. Java annotations (package gama.annotations) mark the classes and methods that implement GAML elements. At compile time, the annotation processor (gama.processor) reads them and generates, in the gaml/ folder of the plugin, a class gaml.additions.<shortcut>.GamlAdditions that registers these elements, their documentation and their tests. At startup, GAMA loads the GamlAdditions of every plugin declaring gaml.extension. The generated code must never be edited: it is regenerated at each build.
flowchart LR
A["Java classes annotated with<br/>@skill, @symbol, @operator..."] -->|"compiled with<br/>gama.processor (APT)"| B["gaml/gaml/additions/&lt;shortcut&gt;/<br/>GamlAdditions.java"]
B -->|"plugin declares<br/>gaml.extension"| C["GAMA at startup<br/>(GamaBundleLoader)"]
C --> D["New keywords available<br/>in the GAML editor and at runtime"]

Prerequisites​

You need the development environment described in Installing the development version, including the GAMA Developer Tools. Code written for GAMA 2025 or earlier must be migrated (new annotation packages, gama.api module...): see the GAMA 2026 migration guide.

Creating artefacts with the developer tools​

The GAMA > Create GAMA artefacts menu (also in File > New > Other... > GAMA Development) provides wizards that generate correct, documented skeletons:

WizardCreates
New GAMA PluginA plugin with the annotation processor configured, gaml.extension declared, Maven pom.xml, model folders, an optional example operator and its test model, and optionally its registration in the GAMA build.
New GAMA SkillA Skill subclass with one attribute (getter/setter) and one action.
New GAMA OperatorA class with documented, tested @operator methods.
New GAMA ActionA skill defining a single action, to use as is or to merge into an existing skill.
New GAMA TypeA GAML type and the Java class of its values.
New GAML Test ModelA GAML model with a test experiment.

The class wizards ask for the target GAMA plugin, the package, the class name and the GAML name. Other useful commands while developing an extension:

  • GAMA > Search GAML keyword... (Ctrl/Cmd+Shift+Alt+K) finds the Java code implementing a GAML keyword: the best way to find real examples in the GAMA sources.
  • GAMA > Clean GAMA plugins (Cmd+B on macOS, Ctrl+B elsewhere) repairs the plugin configurations, deletes and regenerates the gaml/ folders and rebuilds the workspace.
  • GAMA > Report > Missing annotations lists undocumented elements and untested operators. The corresponding processor warnings have quick fixes (Ctrl/Cmd+1) adding @doc or @test skeletons.

Extension mechanisms​

WhatJava elementMain annotationsPage
PluginOSGi bundle declaring gaml.extension–Developing Plugins
Skill (attributes and actions added to species with skills: [...])Subclass of gama.api.kernel.skill.Skill@skill, @vars/@variable, @getter, @setter, @action/@argDeveloping Skills
StatementSubclass of gama.api.gaml.statements.AbstractStatement (or AbstractStatementSequence)@symbol, @inside, @facets/@facet, @validatorDeveloping Statements
Operatorstatic Java method@operator, @test, @no_testDeveloping Operators
TypeGAML type class and value class@typeDeveloping Types
Built-in speciesAgent class@species, @varsDeveloping Species
Control architectureSubclass of gama.api.kernel.skill.AbstractArchitecture (itself a skill)@skillDeveloping Control Architectures
Non-agent classClass implementing IObject@gaml_classMigration guide
File type, display, experiment type, constants, listenersVarious@file, @display, @experiment, @constant, @listenerIndex of annotations

Every GAML element should be documented with @doc (and operators tested with @example/@test): this documentation is shown in the GAML editor and used to generate the reference documentation. All annotations are described in the Index of annotations.

Some extensions do not use annotations but Eclipse extension points declared by gama.api, for instance gama.display (display surfaces), gama.create, gama.save and gama.draw (delegates of the create, save and draw statements), gama.event_layer, gama.experiment, gama.constants, gama.metadata and gama.server_command (gama-server commands). Look at their schemas in gama.api/schema/ and at their uses in the GAMA plugins.

Pages of this section​

  1. Developing Plugins
  2. Developing Skills
  3. Developing Statements
  4. Developing Operators
  5. Developing Types
  6. Developing Species
  7. Developing Control Architectures
  8. IScope
  9. Index of annotations