Spice manifest

Generated from docs/spice-1.schema.json (https://melange.dev/schema/spice-1.json). The guide is spice.md.

Top level

Property	Type	Required	Default	Description
spiceVersion	integer	Yes		Manifest schema version. Thumper refuses a manifest with a spiceVersion it doesn’t know, rather than guessing. Must be 1.
id	string	Yes		Globally unique, lowercase, stable forever. Must equal the Mods/<id>/ folder name. Pattern: ^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$.
version	string	Yes		Semver of this mod. Pattern: ^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$.
name	string	Yes		Display name. 1 to 80 characters.
authors	array of string		[]	Items: 1 to 80 characters.
description	string		""	At most 400 characters.
website	string		""	Format: uri.
melange	object	Yes
kind	string	Yes		client-only: never affects simulated state, the wire format, or Data/Tweak/*; no online handshake needed. content: does at least one of those; every peer in an online match must have a matching content hash. One of: "client-only", "content".
dependencies	array of depString		[]	Items: A mod id, optionally followed by a semver comparator, e.g. ‘thumper-extras >= 1.2.0’.
optional	array of depString		[]	Items: A mod id, optionally followed by a semver comparator, e.g. ‘thumper-extras >= 1.2.0’.
conflicts	array of depString		[]	Items: A mod id, optionally followed by a semver comparator, e.g. ‘thumper-extras >= 1.2.0’.
loadAfter	array of string		[]
permissions	object		{}
entry	object	Yes
assets	object		{}
contentHash	object		{}
messages	array of string			Engine message names this mod registers (content mods only). Checked against the live vanilla registry at start-up, not against a fixed list here; a name that collides is skipped and logged. At most 16 items. Items: Pattern: ^[A-Z][A-Za-z0-9]*(\.[A-Za-z0-9_]+){1,5}$.
weapons	array of object			Weapon clones (content mods only). At most 3 across all enabled mods, in the free panel cells. At most 3 items.
weaponText	object of object			New panel name and help text for vanilla weapons (content mods only). Display only: the simulation is untouched. A key may not be a clone name declared by any mod, and a weapon renamed by an earlier mod refuses the later mod. Applies only in a live content match that every peer has with the same text. At most 64 properties. Values: At least 1 propertie.
weaponIcons	object of object			New panel and/or HUD icon for vanilla weapons (content mods only). Presentation only: the simulation is untouched. A key may not be a clone name declared by any mod, and a weapon an earlier mod already has icons for refuses the later mod. Applies only in a live content match that every peer has with the same rules. At most 64 properties. Values: At least 1 propertie.
vehicleMeshes	object			The mesh the Airstrike helicopter and the Super Airstrike’s are drawn with (content mods only; the mod must also list the bank in “meshes”). The value is a “<modId>.<Name>” mesh from one of the mod’s banks. Presentation only: the simulation is untouched. A vehicle an earlier mod already sets refuses the later mod. Applies only in a live content match that every peer has with the same rules. The mesh must keep the vanilla mesh’s node names (rear_rotor, top_rotor, trail1, trail2) and animation channels. See docs/meshes.md.
levels	array of object			Map pack levels (content mods only). Built files live in assets/levels/ as <prefix>_<slug>.*, where the prefix is the mod id with ‘-’ replaced by ‘_’. At most 128 levels across all enabled mods. At most 32 items.
schemes	array of object			Game styles (the Game Style list in the local modes), allowed for client-only mods. Each file is a scheme: key, title, base, lock, fields and weapons. At most 32 across all enabled mods. At most 8 items.
factoryWeapons	array of object			Custom-weapon presets for the team editor, allowed for client-only mods. Each file is a preset: key, title, base, stock, weapon and cluster. At most 64 across all enabled mods. At most 16 items.
music	array of object			MP3 tracks for a music slot, allowed for client-only mods (the music is local). Only the suddenDeath slot exists. MPEG-1/2 Layer II or III; all tracks of a slot need the same sample rate and channel count. At most 64 across all enabled mods. The plugin author must hold the rights to the audio. At most 16 items.
meshes	array of object			Mesh banks (.xom, built with xomtool convert –bundle) loaded into the game’s graphical resource manager at the main menu, so a weapon clone’s set or wum.sim.weapon():set can name a mesh as “<modId>.<Name>”. kind: content only. Every resource name in a bank must start with “<modId>.”. Each file must be under the mod’s assets root, so it is part of the content hash. See docs/meshes.md. At most 64 items.
settings	array of object		[]	Drives wum.config and the Mods page’s per-mod settings widgets.
defaultEnabled	boolean		true	Honoured only the first time Thumper sees this mod id. Shipped samples set this to false.

melange

Property	Type	Required	Default	Description
range	string	Yes		npm/Cargo-style semver range, e.g. ‘>=0.2.0 <0.3.0’.

permissions

Property	Type	Required	Default	Description
unsafe	boolean		false	Deep Desert: raw memory read/write and calling game functions from wum.unsafe.*, client VM only. Shown to the user on enable.
filesystem	string		"none"	One of: "none", "own-folder", "own-folder-write".
network	boolean		false	Reserved for a later milestone (Oasis). Accepted and ignored, with a warning, by this build’s Thumper.

entry

Property	Type	Required	Default	Description
client	string			Path, relative to the mod folder, loaded into the always-on Sandbox VM.
sim	string			Path registered into the match VM at match start. Requires kind: “content”.

assets

Property	Type	Required	Default	Description
root	string		"assets"
shaders	string		"shaders"
effects	string		"effects"

contentHash

Property	Type	Required	Default	Description
include	array of string		["entry.sim","assets/**","*.spice.json"]	Glob list of files that feed the online content hash. Never computed for a client-only mod.

weapons[]

Property	Type	Required	Default	Description
name	string	Yes		Resource name of the clone; not a vanilla name, not kWeaponCluster* or kWeaponFactory*. Pattern: ^kWeapon[A-Z][A-Za-z0-9]{2,40}$.
base	string	Yes		One of: "kWeaponBazooka", "kWeaponGrenade", "kWeaponHolyHandGrenade", "kWeaponBananaBomb", "kWeaponGasCanister".
cell	integer			Panel cell; default: the first free cell. One of: 29, 39, 40.
bank	string			A .xom bank under assets/data/ holding a container named name.
set	object of number or boolean or string			Container fields by schema name, with values of the field’s type.
panelIcon	string			A 64x64 RGBA PNG under assets/.
hudIcon	string			A .tga in assets/loose/ named <id>.*.
text	object

weaponText.*

At least 1 propertie.

Property	Type	Required	Default	Description
name	string			The panel name (printable ASCII). Pattern: ^[ -~]+$. 1 to 24 characters.
help	string			The panel help text (printable ASCII); one line. Pattern: ^[ -~]*$. At most 160 characters.

weaponIcons.*

At least 1 propertie.

Property	Type	Required	Default	Description
panelIcon	string			A square PNG (side a multiple of 64, up to 4096) under the assets root, relative with no ‘..’. Written over the weapon’s own panel sub-icon. Pattern: \.[pP][nN][gG]$. 1 to 120 characters.
hudIcon	string			A .tga file name in assets/loose/ named <id>.*; loaded in place of the weapon’s vanilla HUD icon. Pattern: ^[^/\\:]+\.[tT][gG][aA]$. 1 to 120 characters.

vehicleMeshes

The mesh the Airstrike helicopter and the Super Airstrike’s are drawn with (content mods only; the mod must also list the bank in “meshes”). The value is a “<modId>.<Name>” mesh from one of the mod’s banks. Presentation only: the simulation is untouched. A vehicle an earlier mod already sets refuses the later mod. Applies only in a live content match that every peer has with the same rules. The mesh must keep the vanilla mesh’s node names (rear_rotor, top_rotor, trail1, trail2) and animation channels. See docs/meshes.md.

Property	Type	Required	Default	Description
BomberHelicopter	string			The mesh the Airstrike’s helicopter is drawn with. Pattern: ^[A-Za-z0-9._-]+\.[A-Za-z0-9._-]+$. 3 to 96 characters.
SuperAirstrike	string			The mesh the Super Airstrike’s helicopter is drawn with. Pattern: ^[A-Za-z0-9._-]+\.[A-Za-z0-9._-]+$. 3 to 96 characters.

levels[]

Property	Type	Required	Default	Description
slug	string	Yes		Unique in the mod; the level stem is <prefix>_<slug>. Pattern: ^[a-z0-9]{1,24}$.
title	string	Yes		The name shown in the level list (printable ASCII). Pattern: ^[ -~]+$. 1 to 40 characters.
type	string		"multi"	Multiplayer (Versus) levels only in this version. One of: "multi".
chunk	boolean		false	True when the pack ships assets/levels/<stem>.lub; the level’s scripts become stdvs,wormpot,<stem>.
source	string			The erg-patch file the level was built from, relative to the mod folder.
survivor	boolean		false	Also list the level as a Survivor copy (Multi.<stem>.S: type 3, unlocked, in the Prebuilt section, running Survivor and the level’s chunk).
sim	string			The level’s sandboxed script (sim/<name>.lua, at most 256 KB, UTF-8 without a BOM). It runs only on this level, as a sim mod does. Pattern: ^sim/[!-~]+\.lua$. At most 200 characters.

schemes[]

Property	Type	Required	Default	Description
file	string	Yes		A .json path relative to the mod folder, inside it (no ‘..’). Pattern: ^[^/\\:][^:]*\.json$. At most 200 characters.

factoryWeapons[]

Property	Type	Required	Default	Description
file	string	Yes		A .json path relative to the mod folder, inside it (no ‘..’). Pattern: ^[^/\\:][^:]*\.json$. At most 200 characters.

music[]

Property	Type	Required	Default	Description
slot	string	Yes		The music slot to play the track in. One of: "suddenDeath".
file	string	Yes		An .mp3 path relative to the mod folder, inside it (no ‘..’), at most 24 MiB. Pattern: ^[^/\\:][^:]*\.[mM][pP]3$. At most 200 characters.
title	string	Yes		Printable ASCII, shown in the log. Pattern: ^[ -~]+$. 1 to 48 characters.
credit	string			The original title or author, shown in the log only. At most 96 characters.

meshes[]

Property	Type	Required	Default	Description
file	string	Yes		A .xom path relative to the mod folder, under the assets root (default “assets/”; no ‘..’). Pattern: ^[^/\\:][^:]*\.[xX][oO][mM]$. At most 200 characters.

settings[]

Property	Type	Required	Default	Description
key	string	Yes		At least 1 character.
type	string	Yes		One of: "bool", "int", "float", "string", "enum".
default	any
min	number
max	number
options	array of string
label	string

weapons[].text

Property	Type	Required	Default	Description
name	string			At most 48 characters.
help	string			At most 400 characters.

Definitions

Definition: depString

A mod id, optionally followed by a semver comparator, e.g. ‘thumper-extras >= 1.2.0’. Type: string. Pattern: ^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?(\s*(=|>=|<=|>|<|\^|~)\s*\d+\.\d+\.\d+)?$.