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...).

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

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.

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):

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).

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.

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.

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 project must contain its .project, GAML files and all the data and imported models it needs. Keep resource paths relative to the project when possible: paths to files outside the project will not become portable just by packaging it. A plugin created as described above already declares gaml.extension and has the annotation processor configured. GAMA discovers models in bundles declaring that extension, as well as in gama.core and gama.library; simply adding models/ to an arbitrary Eclipse plugin is not enough.

Using GAMA Developer Tools: in an Eclipse workspace with the target plugin open, choose GAMA > Import GAMA project into plugin.... Select the directory containing the source project's .project, the target plugin, and Data, Demos, Library, Recipes, Tutorials or Tests. Finish creates:

gama.extension.foo/
  models/Recipes/My Project/
    .project
    models/...
    includes/...

The source is copied, not moved or modified. The destination folder uses the name in .project; an existing destination is not overwritten. The copy's GAMA and Xtext natures and Xtext builder are normalized, obsolete GAMA classification natures are removed, and its comment is set to the target bundle symbolic name. The assistant adds models/ to bin.includes in build.properties. It excludes Git metadata and rejects symbolic links and Eclipse linked resources; copy their contents into the source project first. The command is available in versions of GAMA Developer Tools that include this assistant.

Manually: copy the complete project directory, including .project, into models/<category>/<project name>/ in the plugin. For example, use models/Recipes/My Project/ as above. Do not copy external links or Git metadata in place of the files needed by the models. In the copied .project, use the Xtext builder org.eclipse.xtext.ui.shared.xtextBuilder and the natures org.eclipse.xtext.ui.shared.xtextNature and gama.workspace.nature; remove obsolete classification natures such as gama.workspace.recipeNature. Set the project comment to the plugin's Bundle-SymbolicName. Classification is determined by the containing folder, not the nature. In the plugin's build.properties, add models/ to the existing bin.includes, for example:

bin.includes = META-INF/,\
               .,\
               plugin.xml,\
               models/

Preserve any other entries already required by the plugin. Refresh the plugin in Eclipse and verify that the copied files, including .project, are included in the exported bundle.

Run and distribute: adding a project to the bundle does not by itself install that bundle in GAMA. For a workspace launch, include the plugin in a feature reachable from gama.product (use GAMA > Add to GAMA build... if needed), then launch the UI and open the project in its library category. For a full release, build the product with that feature included. For separate installation, publish a compatible feature containing the plugin in a p2 update site, then install the feature in the matching GAMA version and restart GAMA. See section 6, section 8 and Creating a release of GAMA. Check the packaged bundle and the resulting installation, not just the source workspace; project names that collide with existing projects can be renamed by GAMA when imported into its workspace.

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.

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.

• 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.

• 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.

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.