The "addin.xml" file contains the definition of the addin and is read by GooTool. It contains descriptions of the addin for the user, and also technical data used by GooTool. It must be located in the root directory of the goomod file.

The root XML element is addin and this has one required property, spec-version. This describes the version of this specification that the addin follows. This document describes version 1.1. This is not related to your addin version at all.

Then follow a number of required and optional elements.

id (required)
The globally-unique identifier of this addin. This must not change between different versions of your addin. It is used for the internal filename of the addin, for other addins to define dependencies, and to ensure previous versions of your addin are removed on upgrade.. It is never displayed to the user.

The format of the field is alphanumeric identifiers separated by periods. The field begins with your reversed domain name. This is your namespace and it is up to you to partition it as you wish. This is followed by any details needed to identify this particular addin. For example: com.mycompany.mods.mymod.

If you do not have a domain name, but you do have an account on goofans.com, you can use our domain and your username as your namespace: com.goofans.<yourname>. For example if your username is robert and you've made a level "Going Down", you might name the addin com.goofans.robert.levels.goingdown.

name (required)
The name of this addin, as shown to the user. It is used in various lists and displays and should be short, but should also be descriptive as to what your addin is or does. For example Going Down.
type (required)
This is either mod or level. Both kinds may merge and override files, but only level addins have a <level> entry in their manifest. Thus only level addins can have levels displayed in Chapter 1.
version (required)
The version of your addin. This is used for dependency and upgrade calculations so you should increment it on each new release.

The format is a sequence of between 1 and 4 version number components separated by periods. Each component consists of decimal digits, and within each component the version should be numerically comparable. For example, version 1.11 must be a newer version than 1.2. It is perfectly permissible to have only 1 component to the version number, in which case no periods are needed.

Examples of valid version numbers:
1
0.1
1.0.2
1.5.0.1

Note that any unused components are treated as zeros. So version "1" is equivalent to "1.0.0.0" in terms of comparison.

thumbnail (optional)
goomod 1.1+ only. An optional element specifying the screenshot displayed to the user in GooTool. The text content is the filename in the goomod file, and the element has the required attributes type, width and height giving the MIME-type, width and height of the thumbnail respectively. The only permitted MIME-types are image/jpeg and image/png. The recommended thumbnail size is 200x150 as larger images may be resized by GooTool giving poor quality results.
description (required)
The description of your addin as displayed when the user requests the properties dialog for your addin. You have two choices for the format.

The first choice is plain text, in which case any newlines in the description are preserved. CDATA is optional here.

The second choice is HTML, for which CDATA wrapping is required. HTML is identified by a description that begins with <html> and ends with </html>. You can use any basic HTML formatting allowed by Java within this description.

author (required)
Your name or handle. Should be fairly short.
dependencies (optional)
An optional element which may be omitted if your addin doesn't require any others to be installed first. GooTool inspects this when enabling your addin, to ensure that other addins you need have already been enabled. This also allows for a more modular approach to addin development. It is intended that eventually GooTool will be able to automatically download your dependencies from goofans.com

The format is a set of <depends> elements. Each of these elements has a required attribute ref, which is ths id of the addin you require. You can also specify optional min-version and max-version attributes, in which case your addin will not be enabled unless the other addin matches the versions you specify.

levels (required)
An element that is required for level addins, and prohibited for mod addins. It gives information about your level which will be added automatically to Chapter 1.

You should use this element rather than merge with chapter 1 yourself for several reasons. First, it allows GooTool to put your texts in text.xml automatically. Second, allowing GooTool to do it will ensure that multiple custom levels do not overlap each other on the display. And third, when World of Goo has better modding support, GooTool will add your mod to a custom chapter instead. If there are compelling reasons to still do overrides yourself, please contact the author so better support can be built into GooTool or this spec.

In goomod version 1.0, level was a direct child of addin. Goomod version 1.1 supports multiple levels, so level is now a child of levels, and there can be more than one of them present.

The level element has three required and three optional child elements.

dir (required)
Specifies the directory of your level under the levels directory.
name (required)
Specifies the name of your level in its text attribute. This is used on the chapter screen and as the title of your loading screen.
subtitle (required)
Specifies the subtitle displayed on the loading screen in its text attribute.
ocd (optional)
specifies the OCD requirements, e.g. balls,16. This element is optional; if omitted, the player will see "This one is mine -the Sign Painter".
skipeolsequence (optional)
goomod 1.1+ only. If this empty element is present, the end of level sequence (showing the scores and the draining balls) is skipped.
cutscene (optional)
goomod 1.1+ only. The cutscene to play when the level ends (if skipeolsequence is set) or when the score screen "continue" handle is clicked (if skipeolsequence is not set). Contains three strings separated by commas. First is the lead-in transition, second is the movie to play, third is the lead-out transition. Either transition may be "x" to cut directly. Example: gooTransition_in,wogcunlock,gooTransition_out or x,wogcunlock,gooTransition_out.

The name and subtitle elements may also be internationalized in the same way that existing goo levels are using two-letter language attributes.

Example Mod

Here is the manifest file for an example mod. This one is taken from the Merger test mod in GooTool's test suite:

<addin spec-version="1.1">
  <!-- The unique ID of this addin. Read the spec for uniqueness and format requirements. -->
  <id>net.davidc.test.merger</id>
 
  <!-- Short display name shown to user. -->
  <name>Merger Test</name>
 
  <!-- either "mod" or "level". For user display, and to determine whether to create a chapter 1 entry -->
  <type>mod</type>
 
  <!-- An optional thumbnail image of the mod (goomod 1.1+ only) -->
  <thumbnail type="image/jpeg" width="200" height="150">thumbnail.jpg</thumbnail>
 
  <!-- Version. Must be numerically comparable in each "."-delimited component. You could also do it without periods at all, e.g. 11281.-->
  <version>1.0</version>
 
  <!-- Description shown to user when mod is selected. Basic HTML is allowed if you put it in a CDATA and surround it with <html></html>. -->
  <description><![CDATA[
    <html>
    <p>This addin is a test of the merger. It has the following functions:</p>
 
    <ul>
      <li><b>GoingUp</b> - Changes unattached balls to UglyProduct, and turns on visual debug.</li>
      <li><b>SmallDivide</b> - Removes all black balls and adds a new structure of drip balls.</li>
    </ul>
 
    <p>N.B. This test addin modifies existing game levels. It is intended for test purposes only, so don't make
    any changes that could allow leaderboard fudging (e.g. changing to ivy balls would allow them to save more
    balls).</p>
    </html>
  ]]></description>
 
  <!-- Author shown to user. -->
  <author>davidc</author>
 
  <!-- No dependencies. -->
</addin>

Example Level

<addin spec-version="1.1">
  <id>net.davidc.gravitas</id>
  <name>Gravitas</name>
  <type>level</type>
  <thumbnail type="image/png" width="200" height="150">thumbnail.jpg</thumbnail>
  <version>0.5</version>
  <description>This is a lovely level you can play. It has awesome gravity!</description>
  <author>davidc</author>
 
  <!-- Other addins this one depends on. -->
  <dependencies>
    <depends ref="net.davidc.test.mynewball" min-version="1.0"/>
  </dependencies>
 
  <!-- Details about this level -->
  <levels>
    <level>
      <dir>Gravitas</dir>
      <name text="Gravitas" de="Schwerkraftas"/>
      <subtitle text="weighty matters" de="gewichtige Angelegenheiten"/>
      <ocd>balls,16</ocd>
    </level>
  </levels>
</addin>

Future

A future version of this spec may introduce a chapter addin type, if World of Goo ever supports this.