-
-
Notifications
You must be signed in to change notification settings - Fork 3
addon.json Specifications
Based on https://lerppu.net/db64/#Addon-Descriptor-Specification-v1-0
This page lists all available tokens for version 1.1 of the addon descriptor, as well as their meaning.
New tokens may be added in future versions based on requirements and user feedback.
The specifications were extended to support every Build Engine game and port.
Json itself is port-agnostic and only specifies games, their versions and features that the port should support to launch the addon without specifying ports names. It's up to the port to decide if it meets the prerequisites.
Mandatory, string
Type of the addon. Recognized values are:
tc
map
mod
tc replaces main game files like the main CON for Duke 3D, INI for Blood etc. Only one TC can be loaded at the same time.
Map includes single map as well as optional resources and, upon loading, starts the map specified in startmap. Only one map can be loaded at the same time.
Mod includes additional resources and scripts that don't replace main files. Multiple mods can be enabled simultaneously.
Example usage: "type": "tc"
Mandatory, string
The id token is a creator-specified value that is supposed to uniquely identify the addon, such that other addons are able to refer to it through the dependencies and incompatibles tokens.
The specified value must be a string. Only alphabetical and numerical characters are allowed, as well as the characters +, -, _ and -.
To ensure that this value is as unique as possible, try to use a prefix that is unique to you as an author, separated by a dash, then followed by an abbreviation of the title of the addon.
Example usage: "id": "db64-exampleaddon"
Mandatory, string, string[]
Takes either a string, or an array of strings as value. Specifies the game in general or a specific version of the game for which this addon can be used. For instance, if the specified gametype is "duke3d", the addon will not appear in the menu if Ion Fury is currently running.
If multiple strings are specified, the addon will show up for all of the specified games.
Recognized values are:
all
duke3d (includes every version of the game)
duke3d-13 (release)
duke3d-15 (atomic)
duke3d-wt (world tour)
nam
ww2gi
fury
blood
blood-10 (release)
blood-111 (plasma pak)
blood-121 (ouwb)
wang
exhumed
redneck
redneckra
witchaven
witchaven2
tekwar
paladins
Example usage: "game": ["nam", "ww2gi"]
Optional, string, int, object[]
Takes either a hex string starting with 0x, an integer, or an array of hex strings or integers as value. Each value is the CRC32 checksum of the GRP that must be found in the dependency chain of the currently selected game package. Like the "game" token, this token restricts which game types the addon will show up for. If at least one CRC matches for at least one GRP in the dependency chain, the addon will appear in the menu.
This value can be used to achieve more fine-grained exclusion where the "game" token does not suffice. This is useful if the game dependency should be based on a custom grpinfo file, or if a specific version of a game is targetted, such as "World Tour" for Duke3D.
Example usage: "gamecrc": "0x982AFE4A"
Or alternatively, as a signed integer: "gamecrc": -1742012854
It can also be an array of hex string or integer CRCs. If any is fulfilled, the addon will be shown: "gamecrc": [ "0xdeadbeef", -1742012854 ],
Optional, string
Expects a string as value. This is the name of the addon as displayed in the menu, and is used purely as visual information for the user. If omitted, the game will instead display the package or subfolder name. If the title exceeds the boundaries of the screen, it will be truncated.
Example Usage: "title": "Duke Nukem 4D"
Optional, string
Takes a single string value which specifies the version of the addon. This value is used by dependencies to refer to a specific required version of an addon. If the string is omitted, the dependency will always match.
The version string must be a sequence of number segments separated by periods. The string may end with a dash, followed by an arbitrary ASCII character sequence. Dependencies will typically assume a running numbering system, i.e. =>1.4 is 1.4 or newer. Thus it's required that you stick to x.y version labels with optional text as -z at the end.
While this token is optional, it is still recommended to specify a version for each released addon package.
Example Usage: "version": "3.14-RC2"
Other examples: { "1.0", "2.0.0.0", "3.4-alpha", "0.1.20" }
Optional, string
Name of the author and/or possible contributors, which will be displayed in the info box on the menu. If omitted, will not display any authors.
If the string length exceeds the screen boundaries, the text will wrap. Therefore, you can specify as many authors as needed.
Example Usage: "author": "Bob Bobbington and the musketeers"
Optional, string, object
Expects either a single string, or an object that contains the path to a description file. This defines the addon description shown to the user, which can include a brief of your addon, story, further credits, links and other bits. You can format the string using newline characters ("\n"), as well as color palette sequences (e.g. "^12" for palette 12).
If a filepath is specified, then this path should be relative to a subfolder contained within the package. There is no length limitation imposed currently. If omitted, will not display a description.
Example usage: "description": "^2Example addon continues!\n\n^0Aliens are at it again and have created an example addon to cause further mayhem!\n\nStory and conception by Bob Bobbington and maps by The musketeers! (Dank Dave & Steve Jobs)"
Or, if referring to a separate file for better formatting: "description": { "path": "path/to/desc.txt" }
Optional, string
Expects a string as value, which represents the relative path to an image file contained within the package. If the image is successfully imported, will display a preview while the addon is under the cursor in the menu. Accepts .PNG, .JPG, .GIF, .BMP and .PCX files.
Animations are not supported, and the dimensions of the image are restricted to 320x200px.
Example usage: "preview": "path/to/preview.png"
Optional, string, string[]
Accepts either a string or an array of strings as value. Defines a list of relative paths to GRP or ZIP archives contained within the package. These will be loaded together with the remaining addon content once the addon is activated.
Example usage: "grp": "path/to/package.grp"
or "grp": [ "package1.grp", "package2.zip" ]
Optional, object, object[]
Accepts either a single object, or an array of objects as value. Within each object you specify the path to the CON script, as well as the type of the script. Paths must be relative from the addon package base folder.
There are currently two types of scripts:
"main": The specified CON script will be loaded as a replacement for "GAME.CON". In other words, this script acts as a total replacement for the game's CON files. Specifying one such script automatically designates your addon as a Total Conversion. Only one main script is allowed.
"module": The specified CON script will be appended to the existing scripts, and will be loaded together. This is useful, for instance, to load scripts that define new level, episode and music slots, or new actors, but which otherwise preserve the behavior of the base game.
Note that there is limited support for overriding existing CON definitions at this time. It is however possible to override level, music and episode definitions, for instance. More may be introduced later on in development.
Example usage: "con": { "type": "main", "path": "path/to/game.con"}
or as a module: "con": [ { "type": "module", "path": "moduleA.con"}, { "type": "module", "path": "moduleB.con"} ]
Optional, object, object[]
Accepts either a single object, or an array of objects as value. Used exactly like the "CON" script token, but instead loads DEF files. Paths must be relative from the addon package.
Also supports two types of scripts:
"main": The specified DEF script will be loaded as a replacement for "DUKE3D.DEF". In other words, this script acts as a total replacement for the game's main DEF file. Specifying one such script automatically designates your addon as a total conversion. Only one main script is allowed.
"module": The specified DEF script will be appended to the existing scripts, and will be loaded together. Allows overriding of existing DEF commands as well.
Example usage: "def": { "type": "main", "path": "path/to/duke3d.def"}
or as a module: "def": [ { "type": "module", "path": "moduleA.def"}, { "type": "module", "path": "moduleB.def"} ]
Optional, string
Expects a single string, which describes the relative path of the RTS wad file to load. RTS files contain the sounds used for the "Remote Ridicule" taunts, and are structured like WAD files from Doom.
Example usage: "rts": "path/to/game.rts"
Optional, string, Blood only
Specifies .INI file that will be loaded instead of the default BLOOD.INI.
Example Usage: "ini": "DW.INI"
Optional, string, Blood only
Specifies .RFF file that will be loaded instead of the default BLOOD.RFF.
Example Usage: "rff": "ADDON.RFF"
Optional, string, Blood only
Specifies .RFF file that will be loaded instead of the default SOUNDS.RFF.
Example Usage: "snd": "NEWSND.RFF"
Optional, object, object[]
Expects either a single object, or an array of objects as value. Each object contains at least the identity ("id") of the required addon, and optionally also a version dependency.
For example you can require an official addon as a base and then supply additional maps or art as an addon to it. This makes it possible to, for instance, create maps explicitly for "Duke Nukem: Life's a Beach" without needing to integrate the maps into the dependency itself.
Version dependencies accept the following strings as prefix ">=", "<=", "==", ">" or "<". If the prefix is omitted, exact equality is assumed. If the version is omitted, compatibility with all versions is assumed.
Note that version strings are compared per segment, until a difference in value is detected. Characters after the dash are compared using lexical order.
Example Usage: "dependencies": [ {"id": "dukevaca" }, {"id": "vacaplus", "version": ">=1.2.2" } ]
- dukevaca Duke Nukem: Life's a Beach
- dukenw Duke Nukem: Nuclear Winter
- dukedc Duke it out in D.C.
- dukezone DukeZone 2
- dukeawo Duke Nukem 3D Alien World Order Campaign
- bloodcp Blood: Cryptic Passage
- wangwd Shadow Warrior: Wanton Destruction
- wangtd Shadow Warrior: Twin Dragon
- redneckr66 Redneck Rampage: Route 66
Optional, object, object[]
Expects either an object, or an array of objects. Uses the same format as dependencies, and prevents activating the selected addon with any of the ones listed within this token.
In case your mod is known to break or otherwise is incompatible with some known addons, you may list said incompatible addons using this token, to prevent users from launching them together.
Example Usage: "incompatibles": {"id": "brutal-duke", "version": "<2.0" }
Optional, string, string[]
Expects either a single string, or an array of strings. Each string represents one supported renderer. If omitted, all modes are implicitly assumed to be supported.
If your addon requires a certain renderer to be used, then you can specify them using this token. For example, a HRP+Model pack should boot into polymost/polymer, and conversely, some maps may only look correct in classic mode.
If the user currently has an incompatible rendermode selected, the game will automatically switch to the lowest supported mode after reboot (e.g. if "Classic" is not supported, the game switches to the "Polymost" renderer if available).
Supported values are:
classic
polymost
polymer
opengl
OpenGL stands for either "polymost" or "polymer".
Example Usage: "rendmodes": [ "classic", "polymost" ]
Optional, object
Expects a single object, which either specifies the relative path to a map file as a string, or integers pointing to a specific map slot. Can load both usermaps as well as levels defined in a specific episode slot.
The "volume" token is the "episode" slot, while the "level" token is the level slot.
Allows you to auto-start a map after the addon was activated and the game has rebooted. The player will be displayed the skill select menu before the level is started. The player is able to abort starting the level as well, which will return him back to the main menu.
Example Usage: "startmap": { "file": "path/to/file.map" }
or "startmap": { "volume": 0, "level": 3 }
Optional, string, string[]
Expects either a single string, or an array of strings. Each string represents a feature supported by the port.
Addons will not show up for the ports that don't support required feature.
Accepted values are:
eduke32cons
customdude
Example Usage: "features": "eduke32cons"
1.1a - Added type, ports, RFF, SND, INI tokens
1.1b - Added features token, extended game with different versions, removed ports