Config and features

Where a Template game sets its identity, values and feature switches, what disabling a system means, and how a new game chooses which systems run.

Roblox Template / The Roblox Template

A game changes its identity and content through Config, rather than editing values inside services or screens. Shared configuration is pure, typed and frozen. Private server configuration stays under src/core/server/Config/; formulas belong in Rules and receive config as arguments.

Game settings in overrides

Each Config module holds the Template's defaults, and a game never edits it. A game writes only the keys it changes in src/core/shared/Config/Overrides/<Name>.luau beside the module (server config: src/core/server/Config/Overrides/<Name>.luau). The module merges them over its defaults as it loads, so every other module reads the game's values as before, and lune run template-update never conflicts with them: the overrides folders are the game's, the defaults the Template's.

Luau
-- src/core/shared/Config/Overrides/Features.luaureturn { shop = true, demo = false }

Nested tables merge key by key and may gain entries (a product, a code, a board); a list replaces the default list whole; false over an entry removes it, such as a Template example. A misspelled top-level key or a value of another type fails at load, naming its path, so lune run check and lune run catalog stop on it. Config/Currencies is the one module whose top level is a map of ids, so it merges one level down: a game's Overrides/Currencies.luau may add a currency (return { gems = { ... } }, every field written), a misspelled id there is a new currency rather than a load error, and lune run catalog still checks each entry's fields. Config/Brand and Config/Permissions have no overrides: they are the same in every game. lune run init, new-game and products -- sync write the overrides, never the defaults. A game's version lives in its overrides too: lune run init writes version = "0.0.0" with release-please's x-release-please-version marker into Config/Overrides/Game.luau and points release-please-config.json there, so release automation bumps the game's line and Template updates never touch it (the Template's own version stays in Config/Game.luau). The lint rule config-overrides fails when anything but a module reads its overrides file.

Shared config replicates to every client. A setting a client would gain by reading (how a detection is judged, an anti-abuse rule, a secret's name, a code not yet announced) lives in src/core/server/Config/ instead: Admin (the staff guard's staffGuard.limits), AntiCheat (every threshold, weight, tolerance and message, and the watchlist size), Codes, Referrals (maxRewardedFriends, minAccountAgeDays, qualifyingSeconds, requireFriends, newPlayerSeconds) and Platform. AntiCheat, Admin and Referrals each keep a shared half for what the client needs to draw or send. The service that reads a server module merges its overrides from src/core/server/Config/Overrides/. tests/core/shared/Config/ServerOnly.spec.luau lists every server-only setting and fails when one appears in a shared module or a game's shared override. Request throttles a service keeps for its own remote stay in shared config beside the remote they limit.

Newer shared modules a game may tune:

  • Config/Notifications: defaultSeconds = 4, how long a toast stays; maxVisible = 5 and maxVisibleTouch = 3 toasts on screen; maxQueued = 10 waiting for room.

  • Config/Overhead: the billboard over each character's head (see the systems catalogue).

  • Config/Layout: the HUD's widgets (each one's default region and order, locked, priority, resizable, allowed), the game's zones and mode ("free" or "strict"), and the bounds of a saved layout. A game places its own HUD piece by adding a widget here (the HUD layout).

  • Config/Chat: mode ("roblox", "custom" or "none"), the window's place and size, the custom window and the bubbles.

  • Config/PlayerList: mode ("roblox", "custom" or "none"), the stats shown as columns, their pace, and the custom list's corner, sort and keys. The player list's stats moved here from Config/Leaderboards.

Labels in Config/Inventory and other display names are Config/Strings keys, and Config/Inventory.sources.rewards is the inventory source rewards are granted under.

Identity and Roblox ids in Config/Game

src/core/shared/Config/Game.luau holds identity and place declarations, not staff permissions or balance values. A game sets them in Config/Overrides/Game.luau.

Game configuration

namestring
The game's name, filled by lune run init and shown on loading and in logs.
versionstring
Owned by release-please, shown in the top bar; never hand-edit it. A game's is in Config/Overrides/Game.luau, where lune run init puts it.
universeIdnumber
The experience id; zero means not configured.
placesmap of Place
Each place's displayName, live and testing ids, access and requestable flag.
startPlacestring
The place built by default.project.json and joined first.
gameGroupIdnumber
This game's optional group, for member perks only; zero means none.
experiencetable
The experience's settings lune run experience -- sync applies through Open Cloud's Universe API (universe:write): devices (desktop, mobile, tablet, console, vr), voiceChat, privateServerPrice and socialLinks. Only what is named is managed and nothing is cleared; changing an existing private server price needs --yes, since Roblox cancels every subscription. lune run doctor warns about any setting that differs. Visibility, age rating, icon and thumbnails stay in the Creator Dashboard.

A place's access is public or reserved; requestable controls whether a client may ask TravelService to go there. Staff powers always come from the Blockout Games group in Config/Permissions. See Architecture.

What switching a system off does

src/core/shared/Config/Features.luau, with the game's Config/Overrides/Features.luau merged over it, is the source of truth. The Loader reads a module's feature metadata and skips its init() and start() while false. Its screen module is never required, commands and tabs are not registered and feature-specific assets are not preloaded. Public functions must return harmlessly or refuse.

Loader modules (services and controllers) are still required to read metadata, so disabling their lifecycle does not remove source or package metadata from memory or the place build. Remote declarations remain and their argument guards still exist; skipped handlers answer nothing. Existing save fields stay intact.

How a feature switch gates work. Config/Features supplies the switch. The Loader requires a module to read its metadata, then skips init and start while the switch is off. The same switch gates screens, commands, tabs and feature asset preload. Public APIs return harmless values or refusals, while saved data and declared remotes remain.

Saving, state sync, currency, purchases, permissions, settings, shared input, notifications, sounds, loading and the interface foundation are core and have no feature switch. An unknown switch warns and prevents lifecycle startup; it is never silently treated as enabled.

Default optional systems and dependencies

The checked Template configuration enables admin, client performance reports (which need admin), anti-cheat, effects, leaderboards, test mode, server migration, analytics, error reports, daily rewards, codes, live config, titles, referrals, community (its prompts and group reward stay off in Config/Community), badges, travel, haptics, screenshot capture, quests, shop, events, inventory (with sample items, and a starter set from the demo), trading (which needs inventory), the HUD layout editor (layoutEditor; off, the HUD keeps Config/Layout's defaults and saved layouts are kept but not applied) and demo. It disables experience notifications, experience subscriptions, Premium perks, gifts (which need shop), rewarded ads, avatar prompts and emotes, playtime rewards, season pass, tutorial, main menu, showcase (which needs main menu), release notes, platform, market board (which needs platform), native camera profiles, camera transitions, touch actions, interactions, progression, boosts, NPC navigation and offline production.

NPC navigation and offline production

NPC navigation needs no other switch. Turning it off spawns, queues and animates nothing, and nothing of it is saved. Offline production needs no other switch; turning it off claims and stamps nothing and preserves PlayerData.offline.

Admin and test mode

With admin off, nobody has the in-game tools to switch test mode. Check TestMode.alwaysRoles too: a listed role can still start on a copy without the tools.

Switch rules

Five switches need another on: showcase needs mainMenu, marketBoard needs platform, gifts needs shop, trading needs inventory, and clientPerf needs admin (.lune/lib/featureRules.luau). lune run catalog and lune run modules, both part of lune run check, fail a selection that breaks one.

Disabled products

Keep a product id at zero when its disabled feature never registers a handler, otherwise its receipt waits for that handler. lune run products -- sync skips and lists a product only a switched-off feature sells.

Platform

The platform switch turns on PlatformService, the Feedback window and its Feedback button in Roblox's top bar, beside Settings; off by default. Enabling needs the Roblox secret BlockoutApiKey and Allow HTTP Requests; see the developer guide.

Experience notifications

Off by default and needs no other switch. Enabling needs the Roblox secret NotificationsApiKey (a key with only user.user-notification:write), Allow HTTP Requests and the game's kinds; see Template analytics and in-game notifications.

docs/engineering/Feature Switches.md lists the precise effects for every switch. Defaults describe this Template checkout, not a game's installed configuration.

Choosing the systems of a new game

The Template ships no genre presets: it is a foundation, and nothing in it is specific to one kind of game. A new game turns on the systems it uses in its own Config/Overrides/Features.luau and leaves the rest off. lune run modules -- --enable <name> previews a selection without writing anything and checks its camera and control ownership and source dependencies; lune run catalog, part of lune run check, fails on a broken switch rule or two camera owners. Genre starter presets were considered and rejected, so there is no preset file or command. Then reconnect Rojo and restart Play.

To turn one kit off, set its switch false; no other kit has to be switched on. Saved fields stay. Plots and building are a game's own: the Template has no building kits. Source removal is described below.

Live config and kill switches

Some values and switches can change in every running server without a build. They live in Roblox's experience configs (ConfigService), edited in Creator Hub > Configs or Studio's File > Open Configs, and LiveConfigService is the only module that reads them. The liveConfig switch is on by default: it costs one config load per server and a refresh when Roblox has newer values, and nothing per player unless game code asks for a player's value.

Only keys listed in Config/LiveConfig are live, named <Module>.<setting> (in Creator Hub the dot is an underscore, so Features.codes is Features_codes). The Template lists no key, so a new game reads nothing from ConfigService: a game opts in by listing keys in Config/Overrides/LiveConfig.luau and creating the same keys in Creator Hub together, since Roblox warns at every server start about a listed key that does not exist there. Every value is checked against the build: the build value's type and the allowlist's bounds, or it is ignored with a warning and the build's value is used.

Live keys

Kill switchesswitches
Features.<switch>, a boolean. false turns the system off in every server; true leaves the build's value. A system off in the build stays off, because it was never loaded. The Template's systems that honour one once a game lists it: codes (redeeming paused), dailyRewards (claims paused, streaks kept) and events (the event and any preview end at once).
Valuesvalues
<Module>.<setting>, a top-level value of a shared Config module, with bounds (a number needs min and max). LeaderboardService honours Leaderboards.writeSeconds (60 to 900, integer = true) once listed, to slow score writes during an incident.
A/B testsexperiments
A Roblox experiment on an allowlisted value, read per player with LiveConfigService.forPlayer(player, key, build) where the feature is used. Roblox assigns the variant and reports its metrics.

Code reads a live key where it acts: LiveConfigService.enabled("codes"), LiveConfigService.value("Leaderboards.writeSeconds", Leaderboards.writeSeconds), and LiveConfigService.changed(key) to react at once. A published change reaches servers in about 15 seconds to 5 minutes. A server that cannot load the configs plays on the build's values and tries again. The values are mirrored to clients in SharedState.liveConfig, so never make a secret live. In the overrides, switches replaces the list whole, values merges by key and false removes one. Staff see every key with the live command; developers try a value in one server with livetest. Source note: docs/systems/Live Config.md.

Tuning and removing a system

New features may introduce their needed config. Tuning existing balance values belongs in a separate balance: commit on a balance/ branch, using the balance skill. Never bury a price or reward change inside a feature.

Disabling is the safe default for unused systems. Complete source removal is a separate change: inspect lune run modules -- --remove <name> where supported, follow the source note's exact removal list, retain or migrate saved fields, then run check and build. The modules command prints a read-only manifest; it never deletes files.

Updated