Skip to content

XML File Format

Jump to bottom Edit New page
Isaac Brown edited this page Aug 4, 2025 · 15 revisions

This page details the XML file format (.nlogox/.nlogox3d) first introduced in NetLogo 7.0.0.

Note: all TEXT sections referenced in this page are conditionally modified to escape instances of reserved XML characters before saving. If a section includes <, >, or &, it will be wrapped in a CDATA tag, and any instances of the closing CDATA tag ]]> will be escaped. If it does not contain any of these characters, it will be stored as plain text.

File Format

The NetLogo XML file format is a standard XML document, using UTF-8 encoding and conforming to the XML 1.0 standard. The root element is model, which is defined as follows:

<model>
  attributes
    version    :: String
    snapToGrid :: Boolean
  children
    <code>
    <widgets>
    <info>
    <turtleShapes>
    <linkShapes>
    <previewCommands>
    <experiments>
    <hubNetClient>
    <systemDynamics>
    <resources>

The model element can have any number of children, but if a section is specified more than once, only the last occurrence in the file will be used to load the model.

Code

The code element contains the text from the Code Tab, and is defined as follows:

<code>
  attributes
    None
  children
    source :: TEXT

Widgets

The widgets element contains the widgets on the Interface Tab, and is defined as follows:

<widgets>
  attributes
    None
  children
    <button>
    <slider>
    <view>
    <view3d>
    <monitor>
    <switch>
    <plot>
    <chooser>
    <output>
    <input>
    <note>

The widgets element must contain at least a view or view3d widget, but it can have any number of other widgets with any number of repetitions. The widget elements are defined as follows:

Button

<button>
  attributes
    x                    :: Integer
    y                    :: Integer
    width                :: Integer
    height               :: Integer
    forever              :: Boolean
    kind                 :: "observer" | "turtle" | "patch" | "link"
    disableUntilTicks    :: Boolean
    (optional) display   :: String
    (optional) actionKey :: Char
  children
    source :: TEXT

Slider

<slider>
  attributes
    x                       :: Integer
    y                       :: Integer
    width                   :: Integer
    height                  :: Integer
    min                     :: String
    max                     :: String
    default                 :: Double
    step                    :: String
    direction               :: "horizontal" | "vertical"
    (optional) display      :: String
    (optional) variable     :: String
    (optional) units        :: String
    (optional) sizeVersion  :: Integer
  children
    None

View

<view>
  attributes
    x                           :: Integer
    y                           :: Integer
    width                       :: Integer
    height                      :: Integer
    minPxcor                    :: Integer
    maxPxcor                    :: Integer
    minPycor                    :: Integer
    maxPycor                    :: Integer
    patchSize                   :: Double
    wrappingAllowedX            :: Boolean
    wrappingAllowedY            :: Boolean
    fontSize                    :: Integer
    updateMode                  :: Integer
    showTickCounter             :: Boolean
    frameRate                   :: Double
    (optional) tickCounterLabel :: String
  children
    None

3D View

<view3d>
  attributes
    x                           :: Integer
    y                           :: Integer
    width                       :: Integer
    height                      :: Integer
    minPxcor                    :: Integer
    maxPxcor                    :: Integer
    minPycor                    :: Integer
    maxPycor                    :: Integer
    minPzcor                    :: Integer
    maxPzcor                    :: Integer
    patchSize                   :: Double
    wrappingAllowedX            :: Boolean
    wrappingAllowedY            :: Boolean
    wrappingAllowedZ            :: Boolean
    fontSize                    :: Integer
    updateMode                  :: Integer
    showTickCounter             :: Boolean
    frameRate                   :: Double
    (optional) tickCounterLabel :: String
  children
    None

Monitor

<monitor>
  attributes
    x                      :: Integer
    y                      :: Integer
    width                  :: Integer
    height                 :: Integer
    precision              :: Integer
    fontSize               :: Integer
    (optional) display     :: String
    (optional) sizeVersion :: Integer
  children
    None

Switch

<switch>
  attributes
    x                       :: Integer
    y                       :: Integer
    width                   :: Integer
    height                  :: Integer
    on                      :: Boolean
    (optional) display      :: String
    (optional) variable     :: String
    (optional) sizeVersion  :: Integer
  children
    None

Plot

<plot>
  attributes
    x                      :: Integer
    y                      :: Integer
    width                  :: Integer
    height                 :: Integer
    xMin                   :: Double
    xMax                   :: Double
    yMin                   :: Double
    yMax                   :: Double
    autoPlotX              :: Boolean
    autoPlotY              :: Boolean
    legend                 :: Boolean
    (optional) display     :: String
    (optional) xAxis       :: String
    (optional) yAxis       :: String
    (optional) sizeVersion :: Integer
  children
    <setupCode>
    <updateCode>
    <pen>

<setupCode>
  attributes
    None
  children
    source :: TEXT

<updateCode>
  attributes
    None
  children
    source :: TEXT

<pen>
  attributes
    display  :: String
    interval :: Double
    mode     :: Integer
    color    :: Integer
    legend   :: Boolean
  children
    <setupCode>
    <updateCode>

Chooser

<chooser>
  attributes
    x                       :: Integer
    y                       :: Integer
    width                   :: Integer
    height                  :: Integer
    current                 :: Integer
    (optional) display      :: String
    (optional) variable     :: String
    (optional) sizeVersion  :: Integer
  children
    <choice>

<choice>
  attributes
    type  :: String
    value :: Any
  children
    None

<choice> (if type == "list")
  attributes
    type :: "list"
  children
    value :: TEXT

<value>
  attributes
    value :: Any
  children
    None

Output

<output>
  attributes
    x        :: Integer
    y        :: Integer
    width    :: Integer
    height   :: Integer
    fontSize :: Integer
  children
    None

Input

<input>
  attributes
    x                       :: Integer
    y                       :: Integer
    width                   :: Integer
    height                  :: Integer
    multiline               :: Boolean
    type                    :: String
    (optional) variable     :: String
    (optional) sizeVersion  :: Integer
  children
    value :: TEXT

Note

<note>
  attributes
    x               :: Integer
    y               :: Integer
    width           :: Integer
    height          :: Integer
    fontSize        :: Integer
    textColorLight  :: Integer
    textColorDark   :: Integer
    backgroundLight :: Integer
    backgroundDark  :: Integer
    markdown        :: Boolean
  children
    text :: TEXT

Info

The info element contains the text from the Info Tab, and is defined as follows:

<info>
  attributes
    None
  children
    text :: TEXT

Turtle Shapes

The turtleShapes element contains the shapes created in the Turtle Shapes Editor, and is defined as follows:

<turtleShapes>
  attributes
    None
  children
    <shape>

<shape>
  attributes
    name               :: String
    rotatable          :: Boolean
    editableColorIndex :: Integer
  children
    <circle>
    <line>
    <polygon>
    <rectangle>

Each compound shape can contain any number of simpler shapes, which are defined as follows:

Circle

<circle>
  attributes
    color    :: 32-bit packed RGBA
    filled   :: Boolean
    marked   :: Boolean
    x        :: Integer
    y        :: Integer
    diameter :: Integer
  children
    None

Line

<line>
  attributes
    color  :: 32-bit packed RGBA
    marked :: Boolean
    startX :: Integer
    startY :: Integer
    endX   :: Integer
    endY   :: Integer
  children
    None

Polygon

<polygon>
  attributes
    color  :: 32-bit packed RGBA
    filled :: Boolean
    marked :: Boolean
  children
    <point>

<point>
  attributes
    x :: Integer
    y :: Integer
  children
    None

Rectangle

<rectangle>
  attributes
    color  :: 32-bit packed RGBA
    filled :: Boolean
    marked :: Boolean
    startX :: Integer
    startY :: Integer
    endX   :: Integer
    endY   :: Integer
  children
    None

Link Shapes

The linkShapes element contains the shapes created in the Link Shapes Editor, and is defined as follows:

<linkShapes>
  attributes
    None
  children
    <shape>

<shape>
  attributes
    name      :: String
    curviness :: Double
  children
    <line>
    <indicator>

<line>
  attributes
    x       :: Double
    visible :: Boolean
  children
    <dash>

<dash>
  attributes
    value :: Float
  children
    None

<indicator>
  attributes
    None
  children
    <shape> ; this refers to a turtle shape, see section "Turtle Shapes"

Preview Commands

The previewCommands element contains the text from the Preview Commands Editor, and is defined as follows:

<previewCommands>
  attributes
    None
  children
    text :: TEXT

BehaviorSpace Experiments

The experiments element contains the BehaviorSpace experiments created in the model, and is defined as follows:

<experiments>
  attributes
    None
  children
    <experiment>

<experiment>
  attributes
    name                 :: String
    repetitions          :: Integer
    sequentialRunOrder   :: Boolean
    runMetricsEveryStep  :: Boolean
    (optional) timeLimit :: Integer
  children
    <preExperiment>
    <setup>
    <go>
    <postRun>
    <postExperiment>
    <exitCondition>
    <runMetricsCondition>
    <metrics>
    <constants>
    <subExperiments>

The experiment element can contain any number of children, but if an element is specified more than once, only the last occurrence in the file will be used to load the experiment.

Pre-experiment Commands

<preExperiment>
  attributes
    None
  children
    source :: TEXT

Setup Commands

<setup>
  attributes
    None
  children
    source :: TEXT

Go Commands

<go>
  attributes
    None
  children
    source :: TEXT

Post-run Commands

<postRun>
  attributes
    None
  children
    source :: TEXT

Post-experiment Commands

<postExperiment>
  attributes
    None
  children
    source :: TEXT

Exit Condition

<exitCondition>
  attributes
    None
  children
    source :: TEXT

Run Metrics Condition

<runMetricsCondition>
  attributes
    None
  children
    source :: TEXT

Metrics

<metrics>
  attributes
    None
  children
    <metric>

<metric>
  attributes
    None
  children
    source :: TEXT

Constants

<constants>
  attributes
    None
  children
    <steppedValueSet>
    <enumeratedValueSet>

<steppedValueSet>
  attributes
    variable :: String
    first    :: Decimal
    step     :: Decimal
    last     :: Decimal
  children
    None

<enumeratedValueSet
  attributes
    variable :: String
  children
    <value>

<value>
  attributes
    value :: Any
  children
    None

Sub-experiments

<subExperiments>
  attributes
    None
  children
    <subExperiment>

<subExperiment>
  attributes
    None
  children
    <steppedValueSet>
    <enumeratedValueSet>

HubNet Client

The hubNetClient element contains the widgets created in the HubNet Client Editor, and is defined as follows:

<hubNetClient>
  attributes
    None
  children
    <button>
    <slider>
    <view>
    <view3d>
    <monitor>
    <switch>
    <plot>
    <chooser>
    <output>
    <input>
    <note>

System Dynamics

The systemDynamics element contains the figures created in the System Dynamics Modeler, and is defined as follows:

<systemDynamics>
  attributes
    dt :: Double
  children
    <stock>
    <converter>
    <reservoir>
    <binding>
    <rate>

The systemDynamics element can contain any number of figures, which are defined as follows:

Stock

<stock>
  attributes
    name          :: String
    allowNegative :: Boolean
    x             :: Integer
    y             :: Integer
  children
    initialValue :: TEXT

Converter

<converter>
  attributes
    name :: String
    x    :: Integer
    y    :: Integer
  children
    expression :: TEXT

Reservoir

<reservoir>
  attributes
    x :: Integer
    y :: Integer
  children
    None

Binding Connection

<binding>
  attributes
    startFigure :: Integer
    endFigure   :: Integer
  children
    None

Rate Connection

<rate>
  attributes
    name        :: String
    bivalent    :: Boolean
    startFigure :: Integer
    endFigure   :: Integer
  children
    expression :: TEXT

Resources

The resources element contains the external files bundled with a model, and is defined as follows:

<resources>
  attributes
    None
  children
    <resource>

<resource>
  attributes
    name      :: String
    extension :: String
  children
    data :: TEXT

Resource data that can be interpreted as plain text will be stored as such. All other resource data will be stored as Base64-encoded strings.

Add a custom footer

Home

Advanced Users

Contributors

Internal Home

NetLogo Web

Wiki Issues, Questions, Comments

Licenses

Known Issues

Clone this wiki locally