Skip to main content

Addon

An addon changes or extends the game itself: models, textures, vehicles, peds, weapons, map data or the game's data files. Unlike a resource, an addon contains no scripts. Players download it before they join, and the game loads it once while it starts.

How It Works​

  1. The server reads the meta file of every addon listed in settings.xml when it starts. Files listed with <file> are packed into one archive, files listed with <stream> are offered as they are.
  2. When a player connects, the launcher downloads every file that is missing or has changed. Files are kept in the player's cache, so the next visit only downloads what changed.
  3. The game starts and loads the addons in the order they are listed in settings.xml.
info

Addons cannot be added, removed or changed while the game runs. If the addons of a server change, players who are still in the game cannot reconnect from there. They get the message This server requires new additional content and have to connect again through the launcher.

Structure​

Every addon is a folder inside the addons directory of the server. It contains the meta file (meta.xml), the files listed with <file> (anywhere in the folder, subfolders are fine) and, if the addon has any, a stream folder for the stream files.

Server Folder
HappinessMP.Server.exe
addons/
├── my-addon-01/
│	├── stream/
│	│   ├── policenew.wft
│	│   └── policenew.wtd
│	├── content.dat
│	├── items.ide
│	└── meta.xml
├── my-addon-02/
│	├── meta.xml
│	└── ...
resources/
settings.xml
settings.xml
<addon>my-addon-01</addon>
<addon>my-addon-02</addon>

Category Folders​

Like resources, addons may be grouped into subfolders. The path below addons/ becomes part of the addon's name:

settings.xml
<addon>vehicles/police</addon>
caution

Inside the game the category is flattened with an underscore, so paths in the content file use vehicles_police, not vehicles/police:

content.dat
IDE addons:/vehicles_police/items.ide

Meta File​

The meta file lists what belongs to the addon. Nothing that is not listed here is sent to the players.

meta.xml
<meta>
  <file type="content" src="content.dat"/>
  <file src="items.ide"/>

  <stream src="*.wft"/>
  <stream src="*.wtd"/>

  <siren carmodel="policenew" lights="1"/>
</meta>

<file>​

A file the game reads through the content file, for example .ide, .dat or .xml files.

  • src is relative to the addon folder. Subfolders are allowed, the glob patterns *, ? and ** too.
  • type="content" marks a content file (.dat). The game reads it while it starts, it tells the game what to do with the other files.
  • type="audio" marks an audio data file (.xml), loaded after the audio data of the episode.
  • Without type the file is only made available to the game. A content file has to refer to it, otherwise it is never used.

Inside the game every file of the addon is reachable as addons:/<addon name>/<path>, for example addons:/my-addon-01/items.ide or addons:/my-addon-01/data/handling.dat.

<stream>​

A file the game streams in when it is needed, such as models, textures or collisions.

  • src is relative to the stream folder of the addon. Subfolders are not allowed, all stream files of an addon lie directly in stream/. Glob patterns like *.wft work.
  • The file name without extension is the name the game knows the asset by. A file with the name of a file of the game (for example police.wft) replaces it, a new name adds a new asset. See Replacing and Adding.
  • File names may contain letters, digits, _, -, . and @.
  • Supported formats:
FormatContent
wdrModel
wddModel dictionary
wftFragment model (vehicles, breakable objects)
wtdTexture dictionary
wadAnimation dictionary
wbn, wbdCollisions
nodPath nodes, has to be named nodes<number>.nod like the game's own files
scoCompiled game script
rrrVehicle recording
cutCutscene
wnv, wpl, ipl, wbs, lod, nthFurther formats of the game (map, navigation and other data)

Any other extension makes the addon fail to load.

<siren>​

Gives a vehicle model a siren. Useful for added emergency vehicles, which the game does not know as such.

<siren carmodel="policenew" lights="1"/>
  • carmodel is the model name of the vehicle, as defined in its .ide file.
  • lights chooses the light pattern. Without lights (or with 0) the vehicle only gets the siren sound, without flashing lights.
lightsPattern
0No lights, siren sound only
1Police
2Ambulance
3Fire truck
4 - 7Further patterns of the game, try them out

Each model may have one siren.

Names​

  • File names are not case-sensitive. Two files whose names only differ in case (Car.wft and car.wft) are an error.
  • Names of <file> files may only use plain ASCII characters (no umlauts or other special characters).
  • A single <file> may be up to 1 GB, all <file> files of an addon together up to 2 GB.

Content File​

A content file (type="content") tells the game what to load and what to replace. It works like the content.dat of the episodes: one entry per line, a tag followed by the path of the file. Lines starting with # are comments.

content.dat
# New vehicle definitions
IDE addons:/my-addon-01/items.ide
caution

Every file a content file refers to has to be listed with <file> in the meta file. A path to a file that is not part of the addon does not work.

All tags
TagFile
IDE, DELAYED_IDE.ide
IPL.ipl
IMG.img
IMGLIST, EPISODEVERSION.txt
ANIMGRP, CARCOLS, CARGRP, PEDGRP, PEDVARS, HANDLING, TIMECYCLE, VEHICLEEXTRAS, PEDPERSONALITY, EXPLOSIONFX, PLSETTINGSMALE, PLSETTINGSFEMALE, PLSETTINGSLIGHT, RADIO, RADIOLOGOS, CREDITS, HUDCOLOR, SCROLLBAR, VISUALSETTINGS, MELEEANIMS, WEAPONFX, WATER, FONTDAT, FONTDATR, HUDDAT.dat
FONTTXD, FONTTXDR, FONTSTRTXD, HUDTXD, RADARBLIPS, FTXDFILE, LBICONSFILE, TICKBOXFILE.wtd
FMENUFILE, WEAPONINFO, THROWNWEAPONINFO, LBDATAFILE.xml
VEHOFF, ACTIONTABLE.csv
SAVEICON.png
PLAYER.rpf
RMPTFX.wpfl
DISABLE_FILE

Replacing and Adding​

Replacing a model or texture of the game only needs stream files. Name them like the game's files and they are used instead of the originals:

addons/better-police
stream/
├── police.wft
└── police.wtd
meta.xml
meta.xml
<meta>
  <stream src="*"/>
</meta>

Adding something new needs its stream files plus a definition the game reads through a content file. For a new vehicle that is a line in an .ide file. The easiest way is to copy the line of a similar vehicle from the game's vehicles.ide and change the names.

The vehicle can use the handling and colors of an existing one, or bring its own. HANDLING and CARCOLS files add their entries to the game's data, so they only contain the lines of the new vehicle:

addons/policenew
stream/
├── policenew.wft
└── policenew.wtd
carcols.dat
content.dat
handling.dat
policenew.ide
meta.xml
meta.xml
<meta>
  <file type="content" src="content.dat"/>
  <file src="policenew.ide"/>
  <file src="handling.dat"/>
  <file src="carcols.dat"/>

  <stream src="policenew.*"/>

  <siren carmodel="policenew" lights="1"/>
</meta>
content.dat
IDE addons:/policenew/policenew.ide
HANDLING addons:/policenew/handling.dat
CARCOLS addons:/policenew/carcols.dat

Load Order​

Addons are loaded in the order of settings.xml, after the content of the episode. When two addons change the same thing, the later one wins. This also applies to stream files: if two addons contain a stream file with the same name, the one of the later addon is used, and the server writes a warning to its log:

[AddonManager] Stream file police.wft of addon pack-b replaces the one of addon pack-a.

Changing an Addon​

The server reads its addons only when it starts. After changing, adding or removing an addon, stop the server and start it again. The restart command is not enough, it keeps the addons that were loaded.

The first start after a change can take a moment for large addons, because the files are packed again. Unchanged addons are reused. The server's cache folder can be deleted at any time, it is created again on the next start.

Troubleshooting​

An addon with an error is not loaded, the server still starts. The reason is in the server log:

[AddonMeta] my-addon-01 - Parse Error: stream file 'policenew.wft' doesn't exist.
MessageFix
file '...' doesn't exist / stream file '...' doesn't existCheck the path. <file> paths start at the addon folder, <stream> paths at the stream folder.
subfolders not allowed for stream filesMove the file directly into stream/.
invalid stream file nameRename the file, only letters, digits, _, -, . and @ are allowed.
invalid stream fileThe format is not supported, see <stream>. Files like .ide or .dat belong in <file>.
path node file ... must be named nodes<number>.nodUse the game's naming, for example nodes12.nod.
... only differ in caseTwo files have the same name in different case, remove one.
invalid file path / is outside of the addonPaths have to stay inside the addon folder.
Failed to add addon ... (directory doesn't exist)The name in settings.xml does not match a folder below addons/.

On the player's side, an addon that fails to load ends the game with Addon ... failed to load. See logs for more details. The details are in logs/core.log in the HappinessMP folder, download problems in logs/launcher.log. The player's cache folder can be deleted safely, everything is downloaded again on the next connect. Stream files that no server needed for 30 days are removed from it automatically.