This page is a practical tour of the Java API of GAMA for developers who write plugins or contribute to the platform: where the interfaces are, how to create GAMA values (lists, maps, points, geometries...), how to cast between types, how to manipulate agents and populations, and how to find the Java code behind a GAML keyword.

The API was deeply reorganized in GAMA 2026. If you are porting code written for an earlier version, read the GAMA 2026 migration guide, which lists every renamed or moved class. The overall organization of the plugins is described in Architecture of GAMA.

Write your code against the interfaces of gama.api and create values with its factories: implementation classes can change without notice. The factories of gama.api delegate to builders installed by gama.core at startup (gama.core.CoreActivator.initializeFactories()).

The main packages of gama.api are:

The annotations used to declare GAML elements (@operator, @skill, @action, @doc...) are in gama.annotations, and the GAML keywords constants in gama.annotations.constants.IKeyword.

Do not instantiate GAMA values with new: use the static factories of gama.api. They attach the right GAML type to the value and work whatever the implementation.

Check the exact signatures in the factory classes (gama.api/src/gama/api/types/...).

Containers are typed: the content type (one of the constants of Types) is given at creation, and the create(...) methods convert the elements to this type. Use createWithoutCasting when the elements are known to have the right type already.

IList<Double> distribution = GamaListFactory.create(Types.FLOAT);
IMap<String, IList<?>> data = GamaMapFactory.create(Types.STRING, Types.LIST);
IPoint p = GamaPointFactory.create(10.0, 20.0);
IShape disk = GamaShapeFactory.buildCircle(5.0, p);

Maps created by GamaMapFactory.create() are ordered (insertion order), which keeps simulations reproducible: avoid unordered Java hash sets and maps whenever their iteration order can influence the results.

GAMA containers can be streamed with StreamEx (IContainer.stream(scope)), and collected back into a GAMA list:

IList<IAgent> alive = agents.stream(scope).filter(a -> !a.dead()).collect(GamaListFactory.toGamaList());

Every GAML type is represented by an IType (gama.api.gaml.types). The built-in ones are available as constants of Types (Types.INT, Types.FLOAT, Types.BOOL, Types.STRING, Types.POINT, Types.GEOMETRY, Types.COLOR, Types.LIST, Types.MAP, Types.MATRIX, Types.PAIR, Types.GRAPH, Types.FILE, Types.AGENT, Types.NO_TYPE...), or by id or Java class with Types.get(IType.FLOAT), Types.get("float"), Types.get(Double.class).

Casting is done by the types themselves, with IType.cast(scope, object, param, copy):

IPoint pt = Types.POINT.cast(scope, value, null, false);
IList list = Types.LIST.cast(scope, value, null, false);
IList<IColor> colors = Types.LIST.cast(scope, value, null, Types.INT, Types.COLOR, false); // with key and content types

param is an optional parameter (usually null); copy asks for a copy even if value already has the right type. The Cast class only keeps the conversions to Java primitive types and a few helpers: Cast.asInt, Cast.asFloat, Cast.asBool, Cast.asString, Cast.asAgent, Cast.asSpecies, Cast.as(scope, value, type).

Use type.createDefaultValue(scope) to initialize a variable that has no initial value (a new empty container for lists and maps), and type.getDefault() for the fallback value of the type (which is null for containers).

Typical code (adapted from gama.core/src/gama/core/util/graph/GamaGraph.java and gama.api/src/gama/api/kernel/serialization/SerialisedAgent.java):

IPopulation<? extends IAgent> pop = scope.getSimulation().getPopulationFor(species);
IList<? extends IAgent> created = pop.createAgents(scope, 1, initialValues, false, true, null);

Agents must not be modified through their container interface: read and write their attributes with getDirectVarValue / setDirectVarValue or by evaluating expressions in their context (scope.evaluate(expression, agent)). New population implementations should extend gama.core.population.AbstractPopulation.

Almost every method of the API takes an IScope (gama.api.runtime.scope.IScope) as first argument. It represents the current execution context (current agent, local variables, random generator, clock...) and must be passed along, never replaced by null. Its use, and the rules for copying it, are described in IScope.

IAgent agent = scope.getAgent();
double r = scope.getRandom().between(0.0, 1.0);
int cycle = scope.getClock().getCycle();

gama.api.GAMA gives static access to the platform. The most useful methods are:

Runtime errors are GamaRuntimeExceptions (gama.api.exceptions), always created with the scope:

if (data == null) throw GamaRuntimeException.error("auto_correlation requires non-nil data", scope);
...
} catch (final Exception e) {
    throw GamaRuntimeException.create(e, scope);
}

GamaRuntimeException.warning(message, scope) creates a warning. See IScope for how errors are reported.

gama.dev.DEBUG (plugin gama.dev) replaces System.out:

• DEBUG.LOG(message) always prints; DEBUG.OUT(object) and DEBUG.ERR(message) only print when debugging is turned on for the calling class. Turn it on or off for a class with DEBUG.ON() / DEBUG.OFF(), usually in a static initializer: static { DEBUG.OFF(); }.
• DEBUG.TIMER(...) measures and logs the duration of an operation.
• Debug messages can be globally disabled with the enable_debug system property, and logging with enable_logging (see gama.dev.FLAGS and Using GAMA flags).

Java elements are documented and tested through their annotations, e.g. in gama.extension.stats/src/gama/extension/stats/Stats.java:

@doc (value = "Returns the auto-correlation of a data sequence given some lag",
      examples = { @example (value = "auto_correlation([1,0,1,0,1,0],2)", equals = "1") })
@tests ({ @test ("list<float> series <- [1.0, 2.0, 3.0, 4.0, 5.0]; auto_correlation(series, 1) = 0.5") })
public static Double opAutoCorrelation(final IScope scope, final IContainer data, final Integer lag) { ... }

The annotation processor turns them into the GAML documentation and test models, and warns about undocumented elements and untested operators. See Index of annotations and Writing tests.

The built-in vocabulary is spread over many classes: most operators are in gama.core/src/gama/gaml/operators (Maths, Strings, Containers, Graphs, spatial/Spatial*...), statements in gama.core/src/gama/gaml/statements, skills in gama.core/src/gama/gaml/skills, some operators are declared directly on the interfaces of gama.api (IContainer, IMap, IPoint...), and the rest is in the extensions.

The quickest way to find one is the developer tools command GAMA > Search GAML keyword... (Ctrl/Cmd+Shift+Alt+K). It lists the GAML keywords declared in the Java sources of the workspace (operators, statements, skills, species, types, actions and their arguments, attributes with their getters and setters, facets, constants...) and opens the Java element that implements the selected one. The pattern matches the beginning of the names; prefix it with a kind to restrict the search (op:+, statement:draw, facet:speed, action:go, attr:location). Invoked with the caret on a word, in the GAML editor or any other editor, it searches for that word. See the developer tools guide.