Resource Packages

Resource Packages

Mods, maps, gamemodes and server resources are all packages: a folder (or a .zip of one) with a resource.toml at its root and the files it names. The same package can be installed as a mod in a player's game and run as a resource on a server.

resource.toml

The file is read strictly: an unknown table or key is an error with its line and column, and the file may be at most 256 KiB.

[resource]
name = "neon-pack"            # also the namespace of everything it adds: neon-pack:board/neon
version = "1.0.0"
title = "Neon boards"
authors = ["Your Name"]
description = "Glowing boards and an aurora sky"
api = 1                       # the script API level it needs
type = "mod"                  # mod | map | gamemode | script | library
priority = 0                  # among a player's mods: higher wins on the same id

[add]                         # new content, in this package's namespace
"texture/neon_board" = "textures/neon_board.png"

[override]                    # replace existing content, any namespace
"ssx:texture/character/textures/alex_board_00_diffuse" = "textures/neon_board.png"

[patch]                       # change fields of a data record
"ssx:tuning/characterpropertiesasset/cp_max" = "data/tuck.toml"

[scripts]
client = ["client/*.luau"]
server = ["server/*.luau"]
shared = ["shared/*.luau"]

[files]
include = ["ui/*.png"]        # sent to players before the client scripts start
lazy = []                     # sent when a script asks for them
server_only = ["server/data/**"]   # never sent to players

[dependencies]
require = ["scores >= 1.0, < 2"]
provide = []

[permissions]
request = ["function.kickPlayer"]

[settings]
countdown_s = 5

[resource]

Key	Required	Rule
name	yes	a-z 0-9 _ . -, 1 to 64 characters; not ssx or ava. It is the package's namespace and, on a server, the folder or zip name
version	yes	MAJOR.MINOR.PATCH, numbers without leading zeros
api	yes	1 or more: the script API level the package needs (this release offers 1)
title	no	one line, at most 256 bytes
authors	no	at most 1 024 names, each one line of 1 to 256 bytes
description	no	at most 4 096 bytes; line breaks and tabs allowed
type	no	mod (default), map, gamemode, script or library
priority	no	an integer, 0 by default: among a player's mods, a higher priority wins on the same id (Load Order and Priorities)

[add], [override], [patch]

Each line maps a content id to a file of the package (a path from the package root):

• [add] keys are <kind>/<path> without a namespace: the package's name is put in front ("texture/neon_board" adds neon-pack:texture/neon_board).
• [override] keys are full ids of content that exists: the disc's (ssx:), the game's own (ava:) or another package's. The package's own content goes in [add].
• [patch] keys are full ids of data records; the file is a .toml whose tables merge into the record field by field (tables merge, numbers, strings and arrays are replaced). Patches of several packages to the same record all apply, in load order.
• An entry may name one file, or files by role: "board/neon" = { model = "models/neon.glb", data = "data/neon.toml" }.
• A file's extension must be one of the kind's formats (Content IDs and Kinds).
• At most 16 384 entries in each of the three tables.

[scripts] and [files]

Lists of path patterns (at most 1 024 each): * any characters within a folder name, ** as a whole segment any number of folders, ? one character, [abc] or [a-z] one of a set. Script patterns must end in .luau.

Key	What
[scripts] server	server scripts; never sent to players
[scripts] client	client scripts
[scripts] shared	both sides, loaded first
[files] include	files the client scripts need; sent before they start
[files] lazy	files sent only when a script asks for them
[files] server_only	files never sent to players

A server sends players every file of the package except [scripts] server and [files] server_only.

[dependencies]

Key	What
require	packages that must be present and start first: "name" or "name <range>", a range being comparisons joined by ,: >=, >, <=, <, = ("scores >= 1.0, < 2", "lib =1.2.3")
provide	other names this package stands in for. A require without a range is met by a package that provides the name; a require with a range needs the real name

A requirement that is missing or out of range, a name provided by two packages, or a cycle keeps the package from loading, with the reason.

[permissions]

request: the server rights the package's server scripts ask for, at most 1 024 names of A-Z a-z 0-9 _ . -. See Script Permissions.

[settings]

Any TOML values (nested at most 32 deep), read by scripts with get(name).

Paths

Package paths are relative, use /, and each part is made of A-Z a-z 0-9 _ . + -; no . or .. part, no part ending in ., no Windows device name (con, nul, com1 …), at most 512 bytes. Two paths that differ only in case are refused (they are one file on Windows). Links, devices and other special files are refused.

Package types

Type	Is	Where it is used
mod	content and client scripts for the player's game	the launcher's Mods page; a server can also send one
map	a map (Making a Map)	the game's Maps page; a server's [game] map
gamemode	rules and scripts for maps (Making a Gamemode)	the Maps page; a server's [game] gamemode
script	scripts, usually for a server	a server's resources
library	code or content other packages require	as a requirement

Limits of a package

See Mod Limits.