GAMA extensions describe their GAML elements (operators, statements, skills, species, types, files...) with Java annotations. All the annotations are in the package gama.annotations of the plugin gama.annotations (gama.annotations/src/gama/annotations/). The annotation processor gama.processor reads them when the plugin is compiled. It:

• checks them and reports errors and warnings in the Eclipse Problems view;
• generates the class gaml.additions.<shortcut>.GamlAdditions in the gaml/ folder of the plugin, which registers the elements in GAMA when the plugin is loaded. Never edit the gaml/ folder by hand;
• generates GAML test models from @test and @example (and fuzz tests for operators) in gaml/models/Tests/Generated From <Plugin>/models/;
• collects the documentation used to build the GAML reference.

For the set-up of a plugin, see Developing Plugins. For tutorials, see Developing Operators, Developing Statements, Developing Skills, Developing Species, Developing Types and Developing Control Architectures.

In the tables below, "(required)" means that the attribute has no default value. "Type id" means an int that is either an IType constant (IType.INT, IType.LIST...) or, where it makes sense, an ITypeProvider constant. "Doc" means the documentation of the element, written with @doc.

Summary

Three more annotations are defined in gama.api (package gama.api.annotations): @validator, @serializer and @depends_on.

@Target(METHOD). Defines an action of a skill, an architecture, a species (agent class) or a GAML class. The method must take an IScope as its only parameter. It reads the arguments from the scope (e.g. scope.getArg("other", IType.AGENT)), and its Java return type gives the return type of the action (void for actions that return nothing). See Developing Skills.

The processor reports an error if two arguments have the same name, and a warning if an argument is named name, keyword or returns (such an action cannot be called with facets, like do action arg1: val1).

Used inside @action(args = {...}). Describes an argument of an action.

@Target(FIELD). Defines a constant or a unit, used in GAML with # (e.g. #pi, #km). It is placed on a static field, whose value is the value of the constant. Constants are not registered by GamlAdditions: a class implementing gama.api.additions.delegates.IConstantsSupplier, contributed through the extension point gama.constants, browses the annotated fields. See gama.extension.maths/src/gama/extension/maths/ode/MathConstants.java and MathConstantSupplier.java:

@constant (
        value = "rk4",
        category = { IConstantCategory.MATH },
        concept = { IConcept.EQUATION, IConcept.CONSTANT },
        doc = @doc ("rk4 solver")) String rk4 = "rk4";

@Target(TYPE), inherited. Defines a type of display (the value of type: in display my_display type: ...). The class must implement gama.api.ui.displays.IDisplaySurface and have a constructor (IOutput.Display output, Object uiComponent). Examples: Java2DDisplaySurface (java2d, 2d) in gama.ui.display.java2d, SWTOpenGLDisplaySurface (opengl) in gama.ui.display.opengl.

@Target({TYPE, METHOD}), and used in the doc attribute of most annotations. Documents a GAML element. The documentation of GAML is generated from it, and the processor reports a warning ("documentation missing") for each element without it.

Can only be used inside @doc(examples = ...) and @usage(examples = ...). An example is a line of GAML code. If it has equals, isNot or raises, it is also turned into a test.

@Target(TYPE), inherited. Defines a type of experiment (the value of type: in experiment my_exp type: ...). The class must implement gama.api.kernel.simulation.IExperimentAgent (usually by extending gama.core.experiment.ExperimentAgent) and have a constructor (IPopulation<? extends IAgent>, int). Examples: ExperimentAgent (gui), TestAgent (test) in gama.core, BatchAgent (batch) in gama.extension.batch.

Used inside @facets(value = {...}). Describes a facet of a statement. See Developing Statements.

For example, @facet(name = IKeyword.RETURNS, declares_new_temp = true, type = IType.LIST, of = IType.FLOAT, optional = true) declares a list<float>, as used by benchmark. See Declaring temporary variables for contextual types, runtime scope handling, and migration from the old marker.

@Target(TYPE), inherited. Lists the facets of a statement (a class annotated with @symbol).

@Target(TYPE), inherited. Defines a type of file. The class must implement gama.api.types.file.IGamaFile and have at least one constructor (IScope, String). The processor generates:

• the operator <name>_file, with one variant for each public constructor whose first parameter is an IScope (e.g. dxf_file(path) and dxf_file(path, unit));
• the operator is_<name>, which tests if a file is of this type.

Example: gama.extension.dxf/src/gama/extension/dxf/GamaDXFFile.java:

@file (
        name = "dxf",
        extensions = { "dxf" },
        buffer_type = IType.LIST,
        buffer_content = IType.GEOMETRY,
        buffer_index = IType.INT,
        concept = { "dxf", IConcept.FILE },
        doc = @doc ("DXF files are 2D geometrical files. The internal representation is a list of geometries"))

@Target(TYPE). Defines a built-in GAML class: a type of structured objects that are not agents (see Developing Species and the migration guide). The class must be public (top-level or static nested), implement gama.api.kernel.object.IObject (usually by extending gama.core.object.GamlObject), and have a public constructor (IScope, IClass). Agents cannot use this annotation (use @species). The GAML parent is the nearest Java superclass that is also annotated with @gaml_class, otherwise object. Example: gama.core/src/gama/core/util/CommandContext.java (class context).

@Target(METHOD). Marks the method that returns the value of an attribute declared with @variable.

The parameters of the method depend on the class that declares the attribute:

• in a skill or an architecture (one instance for all the agents): (IAgent agent), optionally preceded by an IScope;
• in an agent class, a GAML class or a value class: no parameter, or only an IScope.

@Target(TYPE), inherited. Placed on a statement (a class annotated with @symbol), it says where the statement can be used. The processor warns if a @symbol has no @inside.

@Target(METHOD). Marks a method that is called each time the value of an attribute changes. The attribute can be defined elsewhere, for example in another skill (e.g. @listener(IKeyword.LOCATION) in gama.extension.physics/src/gama/extension/physics/gaml/StaticBodySkill.java). If the attribute does not exist, the listener has no effect. The method receives the new value as last parameter, optionally preceded by an IScope and, in a skill, by the IAgent.

@Target({METHOD, TYPE}), source retention. Fuzz tests call every operator at compile time with extreme values (0, -1, infinities, NaN, empty containers, nil) and check that they do not crash GAMA. This annotation excludes an operator (or all the operators of a class) from these tests: use it for operators that act on the outside world (files, network, user interface) or that can hang or use all the memory. Operators annotated with @no_test are not fuzz tested either.

Source retention. Marks an operator that does not need a test: the warning "operator '...' is not tested" is not reported.

@Target({METHOD, TYPE}). Defines an operator. See Developing Operators.

• With a static method, the operands are the parameters of the method.
• With an instance method, the object that declares the method is the first operand, and the parameters are the next operands.
• In both cases, if the first parameter is an IScope, it is given by GAMA and is not an operand.

The processor reports errors if the method is not public, returns void, uses Java arrays, or (static methods) has no operand.

@Target(METHOD). Marks the method that changes the value of an attribute declared with @variable. The method must have at least one parameter: the new value, as last parameter. It can be preceded by an IScope and, in a skill or an architecture, by the IAgent.

@Target(TYPE). Defines a skill. The class must implement gama.api.kernel.skill.ISkill (usually by extending gama.api.kernel.skill.Skill). A class that also implements IArchitecture defines a control architecture (see Developing Control Architectures). See Developing Skills.

@Target(TYPE). Defines a built-in species. The class must implement gama.api.kernel.agent.IAgent (usually by extending gama.core.agent.GamlAgent) and have a constructor (IPopulation<? extends IAgent>, int). See Developing Species.

@Target(TYPE). Defines a statement, or another kind of symbol (layer, output, batch method...). The class must implement gama.api.gaml.symbols.ISymbol (usually through a statement base class) and have a constructor taking an IDescription. See Developing Statements.

Repeatable (grouped in @tests). Placed on an element (usually an operator), it defines a GAML test. The tests of a plugin are written in one test experiment in gaml/models/Tests/Generated From <Plugin>/models/<Plugin> Tests.gaml.

@tests ({ @test ("sqrt(4.0) = 2.0"), @test ("is_error(sqrt(-1.0))") })

The container of repeated @test annotations. You can write @tests({...}), or repeat @test.

@Target(TYPE), inherited. Defines a data type. The class must implement IType (usually by extending gama.api.gaml.types.GamaType) and have a constructor (ITypesManager). Every type gets a casting operator with its name. See Developing Types.

@Target({TYPE, METHOD}), and used in @doc(usages = ...). Describes a particular way of using an element (e.g. one variant of an overloaded operator). A usage can also be used as a code template in the GAML editor.

Can only be used inside @vars(...). Declares an attribute.

The value is read and written by the methods annotated with @getter and @setter. The processor reports an error if an attribute is declared twice in the same class.

Placed on a skill, an agent class, a GAML class, or a value class (or interface) of a type. Lists its attributes. On a value class, the attributes are read with the . operator (e.g. my_color.red, declared in gama.api/src/gama/api/types/color/IColor.java).

These annotations are in the package gama.api.annotations of the plugin gama.api, because they refer to classes of this plugin.

@Target({METHOD, TYPE}), inherited. Gives a class that checks a statement (or an operator) at compile time, in addition to the checks made from the annotations. Example: @validator(StateValidator.class) on FsmStateStatement.

@Target(TYPE), inherited. Gives a class that writes a statement back as GAML code.

@Target(METHOD). Placed on an operator, lists the attributes of the model that must be initialized before the operator is used (for example, the shape of the world).

The package gama.annotations.support contains the constants used as values of the annotations.

An enum giving the kinds of symbols, used in @symbol(kind = ...), @inside(kinds = ...) and @type(kind = ...). Each value has a code:

NUMBER and REGULAR are the kinds of variables and types. (Older documentation used constants such as ISymbolKind.Variable.NUMBER; they no longer exist.)

Constants that compute a type from the operands of an operator (or from the owner of an attribute). They are used in type, content_type, index_type and similar attributes. For the ..._AT_INDEX constants, add the 1-based index of the operand (e.g. ITypeProvider.CONTENT_TYPE_AT_INDEX + 1).

STATEMENT_TYPE and INFERRED_TYPE are supported in type, of, and index of @facet(declares_new_temp = true), not as general operator providers. Other negative provider IDs are not supported on these facets. OWNER_TYPE is not a substitute for STATEMENT_TYPE: it describes the owning species/operand, not the statement's computed type.

FIRST_TYPE, SECOND_TYPE, FIRST_CONTENT_TYPE, SECOND_CONTENT_TYPE, FIRST_KEY_TYPE and SECOND_KEY_TYPE are deprecated: use the ..._AT_INDEX + n constants.

String constants for @operator(category = ...). They are the sections of the operators documentation: ARITHMETIC, LOGIC, RANDOM, STATISTICAL, COMPARISON, CASTING, COLOR, SYSTEM, EDP, SPATIAL, SHAPE, THREED, SP_STATISTICAL, SP_QUERIES, SP_PROPERTIES, SP_RELATIONS, SP_TRANSFORMATIONS, ITERATOR, CONTAINER, MATRIX, STRING, LIST, MAP, GRAPH, FILE, SPECIES, GRID, PATH, DATE, TYPE, POINT, WATER, FIPA, MAP_COMPARAISON, USER_CONTROL, TIME, DEPRECATED, DRIVING, GENSTAR, SPARQL.

About 140 String constants for the concept attributes (IConcept.ACTION, IConcept.ARCHITECTURE, IConcept.GRAPH, IConcept.MATH, IConcept.TYPE...). They are keywords used by the search of the documentation website. Use the existing constants when possible.

String constants for @constant(category = ...): LENGTH, TIME, VOLUME, WEIGHT, SURFACE, GRAPHIC, CONSTANT, MATH, COLOR_CSS, and PREFIX_CONSTANT ("#").

An enum used by @no_test:

The package gama.annotations.constants contains:

• IKeyword: the GAML keywords as String constants (IKeyword.NAME, IKeyword.REFLEX, IKeyword.FSM, IKeyword.LOCATION, IKeyword.CONTROL, IKeyword.CLASS...). Use them in annotations instead of literal strings;
• XMLElements: the names of the elements of the XML documentation generated by the processor;
• ColorCSS: the CSS colours available in GAML (#red, #aliceblue...).

The GAMA developer tools help you find and complete missing annotations:

• GAMA > Report > Missing annotations (or GAMA > Report missing annotations... in the context menu of a plugin) builds a Markdown report from the warnings of the processor. It lists the undocumented GAML elements and the untested operators of each plugin.
• GAMA > Repair GAMA plugins > Generate missing tests writes models/Tests/Untested Operators.gaml in each selected plugin (or in all of them). The file contains one test stub for each operator reported as not tested, with its Java signature. Stubs already in the file are kept.
• Quick fixes (Ctrl+1 / Cmd+1, in the Java editor or the Problems view):
  • on "GAML: documentation missing for ...": add a @doc skeleton (for attributes, arguments and facets, the doc goes into the @variable, @arg or @facet);
  • on "GAML: operator '...' is not tested": add a failing @test("false /* TODO ... */"), mark the operator with @no_test(Reason.ALREADY_TESTED) or @no_test(Reason.IMPOSSIBLE_TO_TEST), or generate a GAML test stub.
• GAMA > Search GAML keyword... (Ctrl+Shift+Alt+K / Cmd+Shift+Alt+K) finds the Java annotation that defines a GAML keyword. Prefix the pattern to restrict the search: op:, facet:, action:, attr:, statement:.
• GAMA > Repair GAMA plugins > Rebuild annotation processor regenerates gama.processor/gama.processor.jar. Use it after you modify gama.annotations or gama.processor.