Version: 🚧 Alpha 🚧

Architecture of GAMA

GAMA is an Eclipse RCP application made of OSGi bundles (Eclipse plugins), grouped into features that are assembled into two products (desktop and headless). All the projects live at the root of the gama repository and are built by Maven/Tycho from gama.parent.

Vocabulary

A plugin (bundle) is a Java project with a META-INF/MANIFEST.MF (and often a plugin.xml). Its dependencies are declared in the Require-Bundle header of the manifest.
A feature is a project containing only a feature.xml that lists plugins (and other features). Features are the units installed by the update site.
A product (gama.product/gama.product, gama.product/gama.headless.product) lists the features that make up a runnable application.

To create a new plugin, use the New GAMA Plugin wizard of the developer tools (see Developing Plugins).

The projects

Language and core

Project	Role
`gama.annotations`	The Java annotations (`@operator`, `@skill`, `@species`, `@symbol`, `@type`, `@doc`, ...) used to declare GAML elements, and `gama.annotations.constants.IKeyword`. Has no dependency and targets JavaSE-21, as it is also loaded by the annotation processor inside Eclipse.
`gama.processor`	The annotation processor. It reads the annotations of each GAMA plugin at compile time and generates `gaml/gaml/additions/<shortcut>/GamlAdditions.java` (plus documentation and tests). It is used through the prebuilt `gama.processor.jar`, referenced by the `.factorypath` of each plugin.
`gama.dev`	Low-level developer utilities used everywhere: `gama.dev.DEBUG` (logging, timers) and `gama.dev.FLAGS` (system properties).
`gama.dependencies`	Bundles the external Java libraries used by GAMA (JTS, GeoTools, JGraphT, StreamEx, Fory, JFreeChart, ... in `libs/`). Plugins must reuse them rather than embed their own copies.
`gaml.grammar`	The Xtext grammar of GAML (`src/gaml/grammar/Gaml.xtext`) and its MWE2 generator (`Generate_GAML_Artefacts.mwe2`). It is only needed to regenerate the parser, which is written into `gaml.compiler/src-gen` and `gama.ui.editor/src-gen` (GAMA > Repair GAMA plugins > Regenerate Xtext grammar). It is not part of the runtime.
`gama.api`	The public API: interfaces (`IAgent`, `IScope`, `IShape`, `IList`, `IType`...), the static factories (`GamaListFactory`, `GamaPointFactory`...), the types (`Types`), the runtime entry point `gama.api.GAMA`, and the loader of language extensions (`gama.api.additions.GamaBundleLoader`). It also declares the extension points used by the other plugins. See Introduction to the GAMA Java API.
`gaml.compiler`	The GAML compiler (parser, validation, scoping, descriptions, expressions), built on Xtext. Depends on `gama.api`.
`gama.core`	The implementation: agents, populations, simulations and experiments, topologies, outputs, and most of the built-in GAML operators (`gama.gaml.operators`), statements (`gama.gaml.statements`), skills (`gama.gaml.skills`) and architectures. Its activator (`gama.core.CoreActivator`) installs the concrete factories into `gama.api` and loads all the language additions.
`gama.workspace`	Integration with the Eclipse workspace: GAMA project natures, models manager, status messages.
`gama.headless`	The runtime without user interface (batch, server mode, tests). Defines the `gama.headless.product` application.
`gama.library`	The models library (examples, tutorials) and model tests shipped with GAMA.
`gama.documentation`	Tools that generate the GAML reference documentation. Not part of the products.

Extensions

gama.extension.* plugins add GAML vocabulary (operators, skills, species, types, file formats...) on top of the core. They usually depend on gama.core, gama.api and gama.dependencies:

Plugin	Contents
`gama.extension.batch`	Exploration and calibration methods for batch experiments
`gama.extension.bdi`	The BDI (Belief-Desire-Intention) architecture
`gama.extension.database`	SQL databases access
`gama.extension.dataframe`, `gama.extension.rds`	Data frames and R data files
`gama.extension.fipa`	FIPA communication between agents
`gama.extension.image`	The `image` type and image manipulation
`gama.extension.maths`	Differential equations and solvers
`gama.extension.network`	Network communication (TCP, UDP, MQTT, WebSockets, HTTP, serial)
`gama.extension.osm`, `gama.extension.gml`, `gama.extension.kml`, `gama.extension.dxf`, `gama.extension.geopackage`	Geographic file formats
`gama.extension.pedestrian`, `gama.extension.traffic`	Pedestrian and traffic skills
`gama.extension.physics`	Physics engine
`gama.extension.serialize`	Saving and restoring agents and simulations
`gama.extension.sound`	Sound
`gama.extension.stats`	Advanced statistics

Community plugins (R, Weka, Matlab, the graphical editor...) live in separate repositories, mostly in the gama-platform-plugins organization. They can be imported with GAMA > Install GAMA sources > Install community plugins... (see Installing the development version) or installed in a release (see Using extensions).

User interface

Plugin	Role
`gama.ui.application`	The Eclipse application (`gama.ui.application.Application`), workbench setup
`gama.ui.shared`	Shared UI components, preferences, dialogs, the `IGui` implementation (`gama.ui.shared.utils.SwtGui`)
`gama.ui.editor`	The GAML editor (Xtext UI)
`gama.ui.navigator`	The models navigator
`gama.ui.viewers`	Viewers for files (images, shapefiles, CSV, ...)
`gama.ui.experiment`	Experiment views: parameters, inspectors, consoles, monitors
`gama.ui.display.java2d`	2D displays
`gama.ui.display.opengl`, `gama.ui.display.opengl4`	3D displays (`opengl4` is the OpenGL 4.1 shader-based renderer)

Export, features and build

Project	Role
`gama.export`, `gama.ui.export`	Exporting models as stand-alone simulation launchers (see Exporting projects). `gama.export.DocumentApplication` is the application started by the desktop product: it opens documents and delegates to `gama.ui.application`.
`gama.feature.*`	The features (see below)
`gama.product`	The product definitions (`gama.product`, `gama.headless.product`), launcher icons and `plugin_customization.ini`
`gama.p2site`	The p2 update site (`category.xml`)
`gama.parent`	The Maven/Tycho parent POM. Its `<modules>` lists every project of the build. `gama.annotations` and `gama.processor` are built separately, before it (see Creating a release of GAMA).

Dependencies between the main plugins

The graph below is simplified from the Require-Bundle headers (Eclipse and third-party bundles are omitted, as well as most transitive edges).

graph BT
    annotations[gama.annotations]
    processor[gama.processor] --> annotations
    dev[gama.dev]
    dependencies[gama.dependencies] --> dev
    dependencies --> annotations
    api[gama.api] --> dependencies
    api --> processor
    compiler[gaml.compiler] --> api
    core[gama.core] --> api
    core --> compiler
    workspace[gama.workspace] --> api
    ext["gama.extension.*"] --> core
    headless[gama.headless] --> core
    headless -.-> ext
    uiapp[gama.ui.application] --> core
    uiapp --> workspace
    uishared[gama.ui.shared] --> uiapp
    editor[gama.ui.editor] --> uishared
    editor --> compiler
    navigator[gama.ui.navigator] --> uishared
    experiment[gama.ui.experiment] --> uishared
    displays["gama.ui.display.*"] --> experiment
    grammar[gaml.grammar] -. generates .-> compiler

Notes:

gama.api does not depend on gama.core. Plugins that only use interfaces and factories can depend on gama.api alone; plugins that subclass implementation classes (e.g. gama.core.population.AbstractPopulation, gama.core.object.GamlObject) also need gama.core.
gama.headless requires some extensions directly (gama.extension.traffic, maths, database, network).
Some UI plugins require extensions for their viewers (e.g. gama.ui.navigator requires gama.extension.osm and gama.extension.gml; gama.ui.display.java2d requires gama.extension.image).

Features and products

graph LR
    subgraph gui[gama.product]
        fcore[gama.feature.core]
        fdeps[gama.feature.dependencies]
        flib[gama.feature.library]
        fext[gama.feature.extensions]
        fimg[gama.feature.extension.image]
        fsnd[gama.feature.extension.sound]
        fstats[gama.feature.extension.stats]
        fui[gama.feature.ui]
        fuideps[gama.feature.ui.dependencies]
        fedit[gama.feature.ui.editor]
        fexp[gama.feature.ui.experiment]
        fexport[gama.feature.export]
    end
    subgraph headlessp[gama.headless.product]
        hcore[gama.feature.core]
        hdeps[gama.feature.dependencies]
        hlib[gama.feature.library]
        hext[gama.feature.extensions]
        himg[gama.feature.extension.image]
    end

Feature	Plugins
`gama.feature.core`	`gama.annotations`, `gama.processor`, `gama.dev`, `gama.dependencies`, `gama.api`, `gaml.compiler`, `gama.core`, `gama.workspace`, `gama.headless`, and the extensions `batch`, `maths`, `stats`, `traffic`, `network`, `database`, `osm`, `gml`, `kml`, `geopackage`, `dataframe`, `rds`
`gama.feature.dependencies`	`gama.dependencies` and the third-party bundles it needs
`gama.feature.extensions`	Standard extensions: `bdi`, `fipa`, `physics`, `pedestrian`, `serialize`, ...
`gama.feature.extension.image` / `.sound` / `.stats`	One extension each
`gama.feature.library`	`gama.library`
`gama.feature.ui`	`gama.ui.application`, `gama.ui.shared`
`gama.feature.ui.dependencies`	Eclipse UI bundles needed by GAMA
`gama.feature.ui.editor`	`gama.ui.editor`, `gama.ui.navigator`, `gama.ui.viewers`
`gama.feature.ui.experiment`	`gama.ui.experiment`, `gama.ui.display.java2d`, `gama.ui.display.opengl`, `gama.ui.display.opengl4`
`gama.feature.export`	`gama.export`, `gama.ui.export`
`gama.feature.copilot`	GitHub Copilot for Eclipse (published on the update site, not included in the product)

The feature files are the reference: check gama.feature.*/feature.xml for the exact current lists.

Minimal configuration

What is needed to run GAMA follows from the products:

Headless (gama.headless.product): the plugins of gama.feature.core, gama.feature.dependencies, gama.feature.extensions, gama.feature.extension.image and gama.feature.library. The strict minimum to compile and run a simple model is gama.dev, gama.annotations, gama.dependencies, gama.api, gaml.compiler, gama.core, gama.workspace and gama.headless together with the extensions it requires.
Desktop (gama.product): all the features listed above.

In a development workspace, start with GAMA > Get started... to check the environment, register JDK 25, install sources, build and configure a launch. The individual GAMA > Install GAMA sources > Install core plugins... command is also available. It imports the projects of gama.parent/pom.xml plus gama.annotations, gama.processor and gaml.grammar (required when missing). GAMA > Check workspace... reports projects or target-platform bundles missing for the desktop product. See Installing the development version.

How language extensions are loaded

A plugin contributes to GAML by declaring the gaml.extension extension point (defined in gama.api/plugin.xml) in its plugin.xml, e.g. gama.extension.stats/plugin.xml:

<plugin>
   <extension point="gama.standard.distribution">
   </extension>
   <extension point="gaml.extension">
   </extension>
</plugin>

(gama.standard.distribution marks plugins that are part of the standard GAMA distribution.)

At compile time, gama.processor generates, for a plugin whose symbolic name ends with <shortcut> (the last segment of the name), the class gaml.additions.<shortcut>.GamlAdditions in the gaml/ source folder (e.g. gama.extension.stats/gaml/gaml/additions/stats/GamlAdditions.java). This code registers every annotated operator, skill, species, type, statement... Never edit it: it is regenerated at each build (GAMA > Clean GAMA plugins deletes and regenerates all the gaml/ folders).

At startup, gama.core.CoreActivator initializes the factories, then calls GamaBundleLoader.buildContributions() (gama.api/src/gama/api/additions/GamaBundleLoader.java):

sequenceDiagram
    participant C as CoreActivator (gama.core)
    participant L as GamaBundleLoader (gama.api)
    participant R as Extension registry
    participant G as GamlAdditions
    C->>C: initializeFactories()
    C->>L: buildContributions()
    L->>R: plugins contributing to "gaml.extension"
    L->>G: loadGamlExtensions(gama.api), then (gama.core)
    loop other plugins, ordered by their dependencies
        L->>G: loadGamlExtensions(bundle): new gaml.additions.{shortcut}.GamlAdditions().initialize()
    end
    L->>R: delegates: gama.create, gama.save, gama.draw,<br/>gama.event_layer, gama.metadata, gama.server_command, ...

gama.api and gama.core are loaded first; if they fail, GAMA exits. A failing additional plugin is reported and skipped.
In headless mode, the display plugins are not loaded.
Other extension points declared by gama.api let plugins provide implementations of delegates: gama.create (create from new data sources), gama.save (new file formats for save), gama.draw, gama.event_layer, gama.display (display surfaces), gama.experiment, gama.constants, gama.metadata and gama.server_command.
Models placed in the models/ folder of a plugin are added to the library; tests in models/Tests are added to the tests.

The projects​

Language and core​

Extensions​

User interface​

Export, features and build​

Dependencies between the main plugins​

Features and products​

Minimal configuration​

How language extensions are loaded​