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.
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.
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:
Note that any unused components are treated as zeros. So version "1" is equivalent to "184.108.40.206" in terms of comparison.
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.
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.
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.
The name and subtitle elements may also be internationalized in the same way that existing goo levels are using two-letter language attributes.
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>
<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>
A future version of this spec may introduce a chapter addin type, if World of Goo ever supports this.