-
-
Notifications
You must be signed in to change notification settings - Fork 1
addon.json Specifications
Based on https://lerppu.net/db64/#Addon-Descriptor-Specification-v1-0
This page lists all available tokens for version 1.0 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.
Token values are case-insensitive (e.g. duke3d = Duke3D)
Required, 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"
Required, 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 -.
It's recommended to use a prefix that identifies the supported game, separated by a dash, then followed by an abbreviation of the title of the addon.
Example usage: "id": "duke3d-exampleaddon"
Required, object
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.
name (required) Takes string and specifies the name of the game, which includes all versions of this game.
version Takes string and specifies the version. For example, if mod requires 20th Anniversary Edition (duke3d-wt), it won't work with Duke 1.3D or Atomic versions.
crc 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 targeted, such as "World Tour" for Duke3D.
Recognized values:
all
duke3d (works with any version of the game)
duke3d_13d (release)
duke3d_atomic (atomic)
duke3d_wt (world tour)
duke64
nam
ww2gi
fury
fury_10
fury_20
fury_as (aftershock)
blood
blood_10 (release)
blood_111 (plasma pak)
blood_121 (ouwb)
wang
slave
redneck
ridesagain
witchaven
witchaven2
tekwar
paladins
standalone
Example usage:
"game":
{
"name": "Duke3D",
"version": "Duke3D_13D",
"crc": "0x982AFE4A"
},
Required, 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"
Required, 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
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).
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)"
Optional, string Duke3D, Redneck Rampage, Ion Fury only
Specifies the path to the CON script that replaces main GAME.CON. Path must be relative from the addon package base folder/archive.
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.
Example usage: "con_main": "MAIN.CON"
Optional, string[] Duke3D, Redneck Rampage, Ion Fury only
Array of path to the additional CON scripts. Paths must be relative from the addon package base folder/archive.
The specified CON scripts 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_modules": [ "MODULE.CON", "MODULE2.CON" ]
Optional, string
Used exactly like the "con_main" token, but instead loads DEF file that's loaded instead of duke3d.def/blood.def etc .
Optional, string[]
Used exactly like the "con_modules" token, but instead loads DEF files.
Optional, string Duke3D, Redneck Rampage
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_main": "ADDON.RFF"
Optional, string, Blood only
Specifies .RFF file that will be loaded instead of the default SOUNDS.RFF.
Example Usage: "rff_sound": "NEWSND.RFF"
Optional, object
Expects array of addon objects, features array or both.
Each addon 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.
features array contains a list of features that the port needs to support in order to run the addon.
- dukevaca Duke Nukem: Life's a Beach
- dukenw Duke Nukem: Nuclear Winter
- dukedc Duke it out in D.C.
- bloodcp Blood: Cryptic Passage
- wanton Shadow Warrior: Wanton Destruction
- twindragon Shadow Warrior: Twin Dragon
- route66 Redneck Rampage: Route 66
- EDuke32_CON
- Hightile
- Models
- Sloped_Sprites
- TROR
- Wall_Rotate_Cstat
- Dynamic_Lighting,
- Modern_Types
- SndInfo
Example Usage:
"dependencies":
{
"addons":
[
{ "id": "Addon1" },
{ "id": "Addon2", "version": "1.0" }
],
"features":
[
"eduke32_con",
"tror"
],
}
Optional, object
Expects an array of addons objects. Uses the same format as dependencies, except for features token, 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":
{
"addons":
[
{ "id": "IncompatibleAddon1" },
{ "id": "IncompatibleAddon2", "version": "1.1" }
]
}
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, object
Expects a single object containing two key-value pairs, where the key is the name of the OS (Windows and Linux values are allowed) and the value is the name of the executable for that OS.
Example Usage:
"executables": {
"Windows": "eduke32.exe",
"Linux": "eduke32"
}
1.0a - Added type, ports, RFF, SND, INI tokens
1.0b - Added features token, extended game with different versions, removed ports
1.0c - Made all tokens lowercase
1.0d - Additional games and features, proposed changes
1.0e - Updated to the specs currently used by the BuildLauncher
1.0f - Replaced - with _ in game versions enums
1.0g - Added executables token
1.0h - Renamed shadowwarrior -> wang, exhumed -> slave, added SndInfo feature