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.
-- 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 = 5andmaxVisibleTouch = 3toasts on screen;maxQueued = 10waiting 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'szonesandmode("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"), thestatsshown as columns, their pace, and the custom list's corner, sort and keys. The player list's stats moved here fromConfig/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, wherelune run initputs 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 -- syncapplies through Open Cloud's Universe API (universe:write):devices(desktop, mobile, tablet, console, vr),voiceChat,privateServerPriceandsocialLinks. 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 doctorwarns 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.
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:
showcaseneedsmainMenu,marketBoardneedsplatform,giftsneedsshop,tradingneedsinventory, andclientPerfneedsadmin(.lune/lib/featureRules.luau).lune run catalogandlune run modules, both part oflune 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 -- syncskips 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 switchesswitchesFeatures.<switch>, a boolean.falseturns the system off in every server;trueleaves 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) andevents(the event and any preview end at once).Valuesvalues<Module>.<setting>, a top-level value of a shared Config module, with bounds (a number needsminandmax).LeaderboardServicehonoursLeaderboards.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.
Adopt the Template and configure the first game.
The Template's platform service
Enable the game key, market reads and feedback.
Updated