Game Pack Schema

Definitions for Game Pack metadata and its nested fields. See Creating a Game Pack for an introduction to what these are and what you need to make one.

GamePack

Holds all the information for a game and how it connects to Crowd Control. A game must have at least 1 game pack, and may have more if for instance the game has multiple popular versions. meta describes the bulk of the game and setup metadata, effects holds everything a viewer can invoke in the game, and the two optional fields relate effects to one another.

›scaleGroups?string[][]

›links?Record<string, string[]>

GamePackMetadata

meta describes what the game is, how it connects to Crowd Control, and what information is displayed about it in the desktop app.

›platformGamePackPlatform

›connectorGamePackConnector[]

›releaseDatestring

›guidestring

›description?string

›note?string

›new?boolean

›image?string

›preferredCore?string

›emulator?'bizhawk' | 'cemu' | 'cemucc' | 'dolphin' | 'pcsx2' | 'project64'

Emulators this pack can run on. meta.emulator stays the default/primary (older app builds only read that field) and must be listed here. More than one entry enables the emulator picker in the desktop app.

›shuffler?boolean

Offers the BizHawk Shuffler as a user toggle. When the user enables it, the ROM path step is replaced by the shuffler games folder and the emulator launches with the shuffler script; effects in the shuffler group are only shown while it is enabled.

›firmware?string

›executable?string

›allowCustomEffects?boolean

›requireAuthCode?boolean

›initiateFromCrowdControl?boolean

›skipProcessArgCheck?boolean

Log, crash dump, and save paths for admin support uploads and crash log collection.

›ignoreExitCodes?number[]

Exit codes that are treated as a normal quit (no crash record, logs, or session crash count).

›process?string | string[]

Executable name(s) that mean the game is running: a single name, or several when the game ships more than one unrelated executable. Glob syntax, not regex — * matches any run of characters, | separates alternatives, and everything else (. included) is literal. "r5apex*.exe", "bg3.exe|bg4.exe", or the equivalent list ["bg3.exe", "bg4.exe"].

›extraArgs?string[]

›patch?boolean

›proExclusive?boolean

›guideCheck?boolean

When set, checklist shows .NET Desktop Runtime install step.

When set, checklist shows Microsoft Visual C++ 2015–2022 Redistributable install step.

›tags?GamePackTags[]

›dynamic?boolean

›recommended?boolean

›earlyAccess?boolean

›disabled?boolean

›newUpdate?boolean

›warningMessage?string

›warningTitle?string

Overrides the title of the warning modal. Defaults to a title derived from visibility.

›sessionReadyBadge?'hidden' | 'processReady'

Live session dashboard pack-ready pill (native client games). Omit = pack gameStateChanged telemetry.

›gamestateGuide?boolean

Loads gamestate/guide.json for the in-app game ready status walkthrough. Bump updatedAt when the file changes.

›prelaunch?boolean

›updatedAt?string

›hypeTrain?boolean

Blocks game path selection and/or launch unless the named files report an acceptable embedded version (Windows VS_VERSIONINFO, i.e. what Explorer shows under Properties → Details). Files that carry no version resource are treated as unknown and never block.

›lastStepMessage?string

›skipPack?boolean

›suggestions?string[]

IDs of entries in the games bucket suggestions.json, shown as post-session "you might also like" suggestions.

GameEffect

The values of the effects.game record, keyed by its effect ID. Disrupt effects (image/audio/etc) live under their own keys in effects and take a different shape.

›pricenumber

›note?string

›description?string

›image?string

›inactive?boolean

Streamer set, doesn't show up in menu

Hides this effect from the Twitch extension while keeping it on the Interact link.

›paid?boolean

›sessionCooldown?number

›sessionMax?number

›unpoolable?boolean

›userCooldown?number

›admin?boolean

Set when this effect is a streamer-created alias of another effect. The alias is a separate menu entry (own price/cooldowns/attachments) but is dispatched to the game under the source effect's effectID. Aliases are never redeemable via integration triggers (channel points, TikTok gifts, etc.), and each source effect keeps at least one paid-coins-only alias — further aliases may be free. Both rules are enforced when the menu is built.

›category?string[]

›custom?boolean

User/game-created dynamic effect, stored outside the base game pack.

›disabled?boolean

Effect is available only to CC staff, not shown publicly to viewers or streamers

›external?boolean

›group?string[]

›hidden?boolean

Used primarily by effectReport to hide/unhide effects dynamically. Technically available to be set by the pack by default.

›new?boolean

›payback?boolean

Opt-OUT flag for the streamer "payback" pool (disrupts played against a viewer in the Twitch extension). Absent = eligible; set payback: false to exclude an effect. Live effects are additionally gated on the extension having a ported renderer for their alias — see PAYBACK_EXTENSION_LIVE_ALIASES.

›args?Record<string, any>

›queueWarningLimit?number

›tags?string[]

Like groups but more intended for backend usage, like __cc_ global tags, as opposed to by the game pack.

›incompatibleConnectors?GamePackConnector[]

›emulators?('bizhawk' | 'cemu' | 'cemucc' | 'dolphin' | 'pcsx2' | 'project64')[]

Emulators this effect works on — entries must appear in meta.emulators. Absent = works on every emulator the pack lists. The desktop app hides the effect from viewer menus while an unlisted emulator is selected.

Supporting types

Types the shapes above are built from.

GamePackConnector

'BinaryGameSocket' | 'Bizhawk' | 'BizhawkTCP' | 'Cemu' | 'CemuTCP' | 'CompactInject' | 'Dolphin' | 'DolphinTCP' | 'EmulatorInject' | 'EverDriveN8Pro' | 'ExternalSetup' | 'ExternalUnity' | 'Failure' | 'File' | 'GBLink' | 'Gecko' | 'HID' | 'Human' | 'DisruptOnly' | 'Inject' | 'IRCClient' | 'IRCServer' | 'LogReader' | 'Lua' | 'MemoryBuffer' | 'NamedPipeClient' | 'NamedPipeDuplex' | 'NamedPipeServer' | 'Null' | 'PCSX2' | 'Pipeline' | 'Project64' | 'RCON' | 'REST' | 'sd2snes' | 'SimpleHTTPServer' | 'SimpleTCPClient' | 'SimpleTCPServer' | 'SimpleWebsocketClient' | 'SimpleWebsocketServer' | 'Success'

GamePackDetails

›connectorGamePackConnector[]

›gamePackIDstring

GamePackEffectMetadata

›variables?GamePackEffectMetadataVariables

GamePackEffectMetadataVariables

Mapping of a metadata's ID to its value. For instance, in Super Mario 64 you might have: {"stars":120,"level":"wf","lives":14}

Record<string, any>

GamePackEffectsCatalogDefinition

GamePackEpicConfig

›NamespaceIdstring

›ItemIdstring

›ArtifactIdstring

›storeUrl?string

Public Epic Games Store product page URL for this pack.

›executable?string

›args?string[]

›force?boolean

GamePackGogConfig

›storeUrlstring

Public GOG store product page URL for this pack.

GamePackPlatform

'GB' | 'GBA' | 'GCN' | 'GEN' | 'GG' | 'IOT' | 'N64' | 'NDS' | 'NES' | 'Other' | 'PC' | 'PS1' | 'PS2' | 'SNES' | 'Wii' | 'WiiU'

GamePackRecord

A Game Pack Record is used to store a summary of a game pack. Used to avoid having to store the full game pack.

›gamePackIDGamePackID

›platformGamePackPlatform

›namestring

›proExclusive?boolean

›image?string

GamePackSteamConfig

›idnumber

›action?'run' | 'launch'

›args?string[]

›force?boolean

›workshopMod?number

›branch?string

›buildid?number

Known-good Steam buildid (from appmanifest AppState.buildid) the pack was tested against.

Steam DLC the pack requires. Detected from the parent game's appmanifest: a DLC counts as installed when one of AppState.InstalledDepots carries its appid as dlcappid. Optional (opt-in) DLC that the streamer owns but has unchecked in Steam's DLC tab is not installed, which is the case we catch.

GamePackSupportFiles

Log, crash dump, and save paths for support uploads (separate from mod install config).

›logPath?string | string[]

›crashDumpPaths?string | string[]

Directories searched recursively for crash/support uploads.

›saveFilePath?string | string[]

Directories collected for admin save uploads (e.g. save games).

GamePackTags

'Multiplayer: Good' | 'Multiplayer: Partial' | 'Mod Compatibility: Good' | 'Mod Compatibility: Partial' | 'Mod Compatibility: Bad' | 'Hype Train' | 'Mod Required' | 'Randomizer Supported' | 'Built-in Support' | 'Multiple Version Support' | 'Old Version Only' | 'Automatic Setup: Full' | 'Automatic Setup: Partial' | 'Manual Setup' | 'Auto Uninstaller' | 'Variable Names' | 'Local Multiplayer' | 'Hardware Support' | 'Thunderstore Integration' | 'Offline Only'

GamePackThunderStoreConfig

›name?string

›url?string

›handlerURL?string

›modName?string

›modPath?string

›incompatibleMods?string[]

›launchArgs?string[]