Experimental: Extensions

Extensions provide a way for NetLogo code to use functionality not provided by the core NetLogo primitives. Very often this involves interacting with external software and services, or performing specialized calculations that are difficult or tedious to implement in NetLogo. More information can be found in the NetLogo desktop documentation for extensions and the list of extensions for desktop. Very few extensions are supported in NetLogo Web at this time.

In NetLogo Web the target for an extension must be Javascript, and at the moment the only way to include an extension is by bundling it with the NetLogo Web code itself. This is all experimental, and we may change the definition file format or the way extensions are loaded as needed for future work. Longer-term the NetLogo team has plans to provide a mechanism to allow inclusion of third party extensions that are external to the NetLogo Web site, but that work is not yet complete.

Creating an extension requires providing at least two items to the Tortoise compiler and engine. First is a definition file that explains the syntax of the commands the extension provides. This must be read at NetLogo code compile time, since extensions involve statements in NetLogo code that will need to be parsed by the compiler. Second is the Javascript code that will actually run the commands during execution by the engine. See the definition and the code for the logging extension as examples.

Format for Defining Extensions

The following describes the grammar for defining an extension's .json defs file.

type ArgType = "unit" ('void' type; only appears in return type; indicates that this is a command, not a reporter) | "agentset" | "agent" | "booleanblock" | "boolean" | "bracketed" | "codeblock" | "commandblock" | "command" | "linkset" | "link" | "list" | "nobody" | "numberblock" | "number" | "optional" | "otherblock" | "patchset" | "patch" | "readable" | "reference" | "reporterblock" | "reporter" | "string" | "symbol" | "turtleset" | "turtle" | "wildcard"

type PrimDef =
  {
    name: string (name in NetLogo)
  , actionName: string (name of property in the `prims` field of the object exported by the extension in JavaScript)
  , argTypes: array[ArgType | { type: ArgType, isRepeatable: boolean (default: false) }] (default: [])
  , returnType: ArgType (default: "unit")
  , isInfix: boolean (default: false)
  , precedenceOffset: number (default: 0)
  }

type ExtDef =
  {
    name: string
  , prims: array[PrimDef]
  }

Building, Testing, and Packaging

Firstly, note that there is a Scala macro for the extension definition reader in the macros project, and that macro will not detect changes to the JSON files automatically. When you update your extension's JSON file you'll need to manually clean the compiled macros code to get them to regenerate. You do not need to clean the macros when you change the extension's code, only the JSON definitions.

In an sbt console you can do this with the clean command for the JS and JVM versions of the project:

; macrosJS/clean ; macrosJVM/clean

You can test your extension with NetLogo language tests. It's often faster to develop your extension using language tests (if possible), then complete interactive tests after. Just add a text file with the tests in resources/main/test/commands then you can run in an sbt console (where Extension would match the name of the text file):

netLogoWeb/testOnly *TestCommands -- -z Extension

Once you're ready to publish your changes to test them out in a real environment, like Galapagos or your own project, you can locally publish the NetLogo JVM compiler (publishLocalVersioned compilerJVM) or the Javascript compiler and engine (publishLocalVersioned netLogoWeb) for use. More info on that in the Galapagos wiki.

Bundled Extensions

Some extensions are already bundled with NetLogo Web. These extensions are all experiemental and subject to change:

• HTTP Req Extension - for sending HTTP requests.
• CODAP Extension - for interacting with the CODAP service.
• NLMAP Extension - a basic map or dictionary data type.
• Experimental: Logging Extension - for logging model data to strings.
• Experimental: Mini CSV Extension - for creating or splitting CSV strings.
• Array* - A simple array data structure for models
• Fetch* - for getting data into NetLogo Web from external sources, like files and URLs.
• Dialog* - various dialogs to interact with the user of a model.
• ExportThe* - for converting NetLogo data into strings.
• ImportA* - for reading imported data back into NetLogo.
• Matrix* - matrix data type and related mathematical operations
• SendTo* - for sending data from NetLogo Web to a local file of the user's choosing.
• Store* - for a persistent data store between model loads.
• Table* - a key/value data structure for models

Info and links to docs for many of these extensions is in the NetLogo Web release notes.

A * indicates the extension has a compatible NetLogo desktop version.