Package Format

A mod is a folder under <game-install>\mods\. The loader scans it once at core boot.

mods/
└── my-mod/
    ├── mod.toml     # required manifest
    └── init.luau    # entry script (path set by `entry`)

mod.toml — every field

Strict parsing: unknown fields are rejected (typos become errors, not silent no-ops).

id (required)

Unique package identity. Used as the console log prefix and must follow the console-name charset: 1–64 chars of [a-z0-9_.-], starting with a letter or digit. Duplicate ids across packages are a discovery error — the second package is skipped with a log line.

id = "portal-timer"

name (required)

Human-readable display name, 1–128 characters. Exposed to scripts as usems.mod_name.

name = "Portal Speedrun Timer"

version (required)

Free-form string, 1–128 characters. SemVer recommended but not enforced.

version = "1.2.0"

author (required)

Free-form string, 1–128 characters.

author = "PoZo"

language (required)

Runtime for the entry script. Currently supported: luau. Others (csharp, native, rust, python, gml, asm) are parsed but skipped with a log line until their bridges land.

language = "luau"

entry (required)

Path to the entry file, relative to the package root. Must be a normalized relative path (no .., no absolute paths, no drive letters) and resolve inside the package — traversal is a hard error. For language = "luau" the file must end in .luau. Max size 4 MB.

entry = "init.luau"           # fine
# entry = "scripts/main.luau" # fine — subdirectories allowed
# entry = "../shared.lua"     # REJECTED at discovery
# entry = "C:/x/init.luau"    # REJECTED at discovery

enabled (optional, default true)

Set false to keep a mod installed but unloaded — the launcher’s enable/ disable toggle writes exactly this field (Phase 5).

enabled = false

Complete example manifest

id = "portal-timer"
name = "Portal Speedrun Timer"
version = "1.2.0"
author = "PoZo"
language = "luau"
entry = "init.luau"
enabled = true

Discovery rules

Rule	Behavior
Scan root	<game-install>\mods\ — or USEMS_MODS_DIR env override (absolute, or relative to the game root)
Package	Any direct child directory containing mod.toml (max 64 KB)
Order	Alphabetical by folder name (lowercased) — deterministic load order
Bad package	Skipped; reason logged (mods: <path>: <error>)
Disabled	Logged as skipped, not an error

Dev workflow without touching the game folder

Point the env override at your repo while iterating:

$env:USEMS_MODS_DIR = "F:\PoZoUSMS\mods\portal"
# then start Portal and inject — packages load straight from the repo