Developing Plugins

A GAMA plugin is an Eclipse/OSGi bundle that contributes new elements to GAML (skills, statements, operators, types, species...) and, optionally, models. This page explains how to create one with the GAMA Developer Tools, what the generated configuration contains, and how to run, test and repair it.

We assume that the development environment is installed as described in Installing the development version (Eclipse 2026-03 with PDE, JDK 25, GAMA core sources imported with GAMA > Install GAMA sources > Install core plugins...).

1. Create the plugin

Choose GAMA > Create GAMA artefacts > New GAMA Plugin (or File > New > Other... > GAMA Development > New GAMA Plugin). The wizard has a single page:

Field	Meaning
Plugin id	Bundle symbolic name, e.g. gama.extension.foo or org.myinstitution.gama.foo. Its last segment (the shortcut, here foo) names the generated package gaml.additions.foo: it must not be shared with another GAMA plugin. The default prefix can be set in Preferences > GAMA Developer Tools.
Name, Vendor, Description	Bundle name, vendor and README/feature description.
Base package	Package of the Java sources (defaults to the plugin id).
Location	Parent folder of the project. Defaults to the folder containing gama.processor, i.e. next to the other GAMA projects in the git checkout. Choose your own repository for a plugin developed outside the GAMA repository.
Layout	Optional libs/ folder for third-party jars, models/Tests, models/Recipes, models/Library models, models/Data, and an example operator with its test model (checked by default).
Integration in the GAMA build	Either add the plugin to gama.feature.extensions, or create a dedicated feature gama.feature.extension.<shortcut> referenced in the update site (gama.p2site/category.xml). The Register... checkbox also adds the module(s) to gama.parent/pom.xml.

On Finish, the wizard creates the project(s), applies the registration (missing gama.parent, gama.feature.extensions or gama.p2site projects are reported in a notification instead), opens the example class (or the manifest) and starts a clean and rebuild of the new plugin, which generates its GamlAdditions.

2. Layout and configuration

gama.extension.foo/
  src/<base package>/        Java sources (and the example FooOperators.java)
  gaml/                      generated by the annotation processor (git-ignored, never edited)
  libs/                      third-party jars (optional)
  models/Tests/ ...          GAML models shipped with the plugin
  META-INF/MANIFEST.MF  build.properties  plugin.xml  pom.xml  README.md  .gitignore
  .classpath  .factorypath  .settings/ (APT, JDT, encoding)

What the wizard configures, for reference (and as a checklist for plugins created by hand or by older versions):

File	Content
META-INF/MANIFEST.MF	Bundle-SymbolicName: <id>;singleton:=true, Bundle-Version: 0.0.0.qualifier, Require-Bundle: gama.core, gama.dependencies, Bundle-RequiredExecutionEnvironment: JavaSE-25, Bundle-ActivationPolicy: lazy, Bundle-ClassPath: .. gama.core re-exports gama.api, gama.annotations and gama.processor; write your code against the interfaces of gama.api whenever possible. Add Export-Package only for packages that other plugins must use.
plugin.xml	Declares the gaml.extension extension point, which tells GAMA to load the plugin's GamlAdditions.
build.properties	source.. = src/, gaml/, output.. = bin/, jre.compilation.profile = JavaSE-25, bin.includes with META-INF/, ., plugin.xml and models/, UTF-8 encoding.
.classpath	JRE container (JavaSE-25), PDE required plugins, src and gaml (optional) source folders.
.factorypath and .settings/org.eclipse.jdt.apt.core.prefs	Annotation processing enabled, with the processor /gama.processor/gama.processor.jar (workspace jar), generated source directory gaml, processing during reconcile disabled.
.settings/org.eclipse.jdt.core.prefs, org.eclipse.core.resources.prefs	Java 25 compliance, annotation processing enabled, UTF-8 encoding.
pom.xml	Parent org.gama:gama.parent:0.0.0-SNAPSHOT (relativePath ../gama.parent/), packaging eclipse-plugin, for the Maven/Tycho build.
.gitignore	Ignores bin/, target/ and gaml/.

The annotation processor writes gaml/gaml/additions/<shortcut>/GamlAdditions.java. If the gaml/ folder is empty or outdated, do not edit it: run GAMA > Clean GAMA plugins (see section 7).

3. Add GAML elements

Write the Java classes in src/, using the annotations of gama.annotations, or generate skeletons with GAMA > Create GAMA artefacts > New GAMA Skill / Operator / Action / Type. See:

• Developing Skills
• Developing Statements
• Developing Operators
• Developing Types
• Developing Species
• Developing Control Architectures

Each build regenerates GamlAdditions. The processor reports errors (e.g. a setter without argument) and warnings (missing documentation, untested operators) in the Problems view.

4. Add third-party libraries

First check whether the library is already provided: gama.dependencies bundles most common libraries (GeoTools, Apache Commons, Jackson, EJML, Apache Fory...), and many others are available as OSGi bundles in the target platform (for instance gama.extension.image requires the com.github.weisj.jsvg bundle). Prefer a Require-Bundle on such a bundle to a private copy; never embed a second copy of a library already supplied by GAMA.

Otherwise, put the jars in libs/ (check the libs/ option in the wizard or create the folder) and declare only the runtime jars, explicitly, in three places, as done in gama.extension.sound:

• Bundle-ClassPath of MANIFEST.MF (after .);
• bin.includes of build.properties;
• .classpath (<classpathentry exported="true" kind="lib" path="libs/..."/>).

Source and Javadoc archives must be attached to their library in the build path, not added to the runtime classpath (exclude them with bin.excludes if they are in libs/). The configuration checks and Clean GAMA plugins never register jars found in libs/ automatically.

To see which packages and modules a library actually needs (and whether some are missing or duplicated), use GAMA > Report > Native library dependencies: it runs jdeps on the compiled bundles and libraries and opens an interactive dependency explorer.

5. Models and tests

The sub-folders of models/ are scanned by GAMA and their projects appear in the navigator of GAMA. Folders named Data, Demos, Library, Recipes, Tutorials and Tests are mapped to the corresponding categories; the other folders (such as Library models) go to the Library category. Provide example models that show modelers how to use the new keywords, and put GAML test models (experiments of type test) in models/Tests. Make sure models/ is in bin.includes (the wizard and the configuration checks do it).

The example created by the wizard contains models/Tests/<shortcut>_doubleTests.gaml, which tests the example operator. Tests can also be written in Java annotations (@example, @test): the processor generates the corresponding test models in gaml/models. GAMA > Repair GAMA plugins > Generate missing tests writes models/Tests/Untested Operators.gaml with one stub per untested operator. See Writing Tests.

Run all the tests with GAMA > Run GAMA > Run tests (headless, results in the Eclipse console), or open the test models in the GAMA UI.

6. Run the plugin in GAMA

GAMA > Run GAMA > Run UI (or Debug UI) launches the workspace GAMA defined by gama.product/gama.product, with feature-based plugin selection: the plugin is included only if it belongs to a feature reachable from the product.

• If the wizard added the plugin to gama.feature.extensions, nothing else is needed.
• Otherwise (dedicated feature, plugin created by hand or imported), select the project and choose GAMA > Add to GAMA build... in its context menu. It adds the bundle to the Maven reactor (gama.parent/pom.xml), reuses or creates a feature declaring it, and makes sure this feature is included in gama.product/gama.product.

To check that the plugin has been loaded, look in the console for the line > GAML : Extensions in <plugin id> ... loaded in <n>ms (printed when GAMA logging is enabled), then use the new keywords in a model: they are proposed by completion and documented in the GAML editor. If a mandatory GAML initialization fails, GAMA exits with status 42 and the developer tools offer Clean and Relaunch.

The same integration (Maven module, feature, product) is used by GAMA > Run GAMA > Build local release... and by the official build: a plugin added with the wizard registration or Add to GAMA build... is included in local releases.

Using an existing plugin

• Community plugins of gama-platform-plugins can be cloned and imported with GAMA > Install GAMA sources > Install community plugins....
• For other plugins, clone their repository and use File > Import... > General > Existing Projects into Workspace (do not copy them into the workspace).

Then run GAMA > Check workspace... and use Add to GAMA build... on the plugin (or add its feature to gama.product/gama.product) before running GAMA.

7. Repair a plugin

• GAMA > Clean GAMA plugins (Cmd+B on macOS, Ctrl+B on Windows/Linux): saves the editors, refreshes the workspace, repairs the plugin configurations, disables the annotation processor, deletes the gaml/ folders, re-enables the processor, then cleans and rebuilds the workspace and checks that every GamlAdditions.java was regenerated. GAMA > Clean... in the context menu of a plugin does the same for the selected plugins only.
• GAMA > Check workspace...: checks the configuration of the open GAMA plugins, the workspace projects and target-platform bundles required by the product and the JDK 25, and offers (after confirmation) to repair what can be repaired.
• Problems view: the configuration problems that remain after a clean are reported there, with quick fixes (Ctrl/Cmd+1).
• GAMA > Repair GAMA plugins > Rebuild annotation processor: only needed after modifying gama.processor or gama.annotations.

The configuration checks apply to every project whose .factorypath references gama.processor or whose plugin.xml declares gaml.extension. They verify that APT is enabled with gaml as generated source directory and reconcile disabled, that the factory path contains /gama.processor/gama.processor.jar (up to date), that gaml is a source folder in .classpath and build.properties, that plugin.xml declares gaml.extension and the bundle is a singleton, that models/ is exported, that the encoding is UTF-8, that the bundle name matches the project name, and that no two plugins share the same last segment.

8. Distribution

Plugins integrated in the GAMA build are packaged with GAMA:

• in gama.feature.extensions, they are part of every GAMA release;
• with a dedicated feature gama.feature.extension.<shortcut> referenced in gama.p2site/category.xml, they are also published, as a separate installable feature, on the update site built from gama.p2site.

Contributing a plugin to the GAMA repository follows the usual pull request process (see the contribution guidelines). Community plugins are maintained in their own repositories in gama-platform-plugins, on a branch per GAMA version (e.g. GAMA_2026-06); contact the GAMA team to have them published.