The Template's architecture

The Roblox Template's source tree in place slices and sides, how the Loader starts services and controllers, the one direction of dependency, and the boundary rules lint-boundaries enforces.

Roblox Template / The Roblox Template

The Template is one source tree in slices and sides, one direction of dependency and one authority. A slice is a folder named after what it is built into: src/core/ goes into every place of the experience, src/main/ into the start place, src/<place>/ into another place. Every slice has the same sides, so "where does this run?" is answered by the path alone. The full text is the Template's ARCHITECTURE.md and src/README.md; why each choice was made is one line in ARCHITECTURE.md's Decisions list.

The source tree

  • src/
    • core/built into every place
      • bootstrap/ReplicatedFirst: the loading screen, before anything replicates
      • admin/ServerStorage.AdminSuite: the admin panel and console, cloned only to those who may use them
      • shared/ReplicatedStorage.Shared: the contract both sides read
        • Loader.luauinit() and start() for services and controllers
        • Remotes.luauevery remote in the game, each guarded
        • SharedState.luauCharm atoms replicated to every client
        • PlayerData.luausaved data per save slot: type, template, schema version, migrations
        • AccountData.luausaved data per account, beside the save slots
        • Types.luautypes that cross a boundary with no single owner
        • assets.luaugenerated by Asphalt, every uploaded asset by name
        • Config/balance values and Roblox ids, pure and frozen: the Template's defaults
          • Overrides/the game's own settings, merged over each module's defaults
        • Rules/pure formulas over config, tested in Lune
        • Util/pure helpers: Result, Format, RateLimiter, Retry, Pool and more
        • Roblox/helpers over Roblox APIs both sides use: RemoteGuard, Observers, Place, Lifetime
      • server/ServerScriptService.Server
        • init.server.luauloads Services/ and the place's own services
        • Config/server-only config, never sent to clients; the game's own in Overrides/
        • Roblox/wrappers over engine services with no lifecycle, never loaded by the Loader: Http, MemoryStore, MessagingBus
        • Services/one module per domain: the authority; a large one is a folder with private parts
      • client/StarterPlayerScripts.Client
        • init.client.luauloads Controllers/ and the place's own controllers
        • ClientState.luauclient-only atoms
        • Device.luauthe device: input in use, VR, ten-foot, interface scale
        • Controllers/client modules: sync, loading, sound, input, camera
        • UI/App, Theme, Menu, Topbar, Components/ (charts in Charts/), Screens/, Util/
    • main/the start place: the same shared/, server/ and client/ sides
  • tests/specs in a tree that mirrors src/: core/shared, core/server, core/client, plus lib/ (helpers), tools/ (the .lune scripts) and main/ (the game's own)
  • .lune/the project scripts, run with lune run
  • .agents/skills, review briefs and hooks every coding agent reads
  • docs/the vault: product, engineering, systems, decisions, the board
  • default.project.jsonmaps the core and the start place
  • rokit.tomlevery tool, pinned
  • wally.tomlthe ten packages

Packages/ and ServerPackages/ are Wally's output, generated and ignored. Every folder has a README.md saying what belongs there and its rules.

What each side of a slice becomes in the place

SideBecomes (core)Becomes (a place)Holds
bootstrap/ReplicatedFirst(core only)The loading screen
admin/ServerStorage.AdminSuite(core only)The admin panel and console
shared/ReplicatedStorage.SharedReplicatedStorage.PlaceRemotes, state, data shape, Config, Rules, Util
server/ServerScriptService.ServerServer.PlaceServices/, and the core's server-only Config/
client/StarterPlayerScripts.ClientClient.PlaceControllers/, UI/

A place's instance is always called Place, whatever the place is called, so place code is written the same in every slice: a place service reaches a core service with script.Parent.Parent.Parent.Services.DataService, and its own config with ReplicatedStorage.Place.Config.Match. Each project file declares its place's name in ReplicatedStorage.PlaceName, a StringValue that Roblox/Place.name() reads.

Places and project files

A game is one Roblox experience with one or more places. Every place is listed in Config/Game.places with its display name, its live and testing ids, its access (public or reserved) and whether a client may ask to go there (requestable). Config/Game.startPlace is the one players join first.

The start place

Built by default.project.json into build/game.rbxl. It also builds two things into Workspace: the demo's DemoLeaderboard and ShowcaseMenuCamera, the persistent part the main menu looks through; $ignoreUnknownInstances leaves the rest of the place's Workspace alone. Its Workspace entry also sets the streaming and simulation baseline (below).

Any other place

Its own <name>.project.json at the root, the same tree mapping its own slice, built into build/game-<name>.rbxl. lune run new -- place <Name> writes it and the slice with its READMEs.

Place names

Lowercase letters and digits (main, training, arena2): a name is a file, a folder, an instance and a key. Rules/Places holds every file-name rule, so scripts and game agree.

Core or a place's slice?

  • Every place runs it: src/core/. A currency, the shop, the HUD kit.

  • Some places run it: src/core/, with the module exporting places = { "arena", "training" }. The Loader skips it elsewhere, exactly like a switched-off feature.

  • One place runs it: src/<place>/. A match loop, a lobby's matchmaking.

  • It is the contract: src/core/shared/ always. Remotes, SharedState, PlayerData, AccountData and Types have no per-place copies; a place declares its remotes in the core's Remotes.luau under its own namespace and handles them in its own service.

  • It is a value one place tunes: that place's shared/Config/.

Code that runs everywhere and branches asks Roblox/Place: Place.is("training"), Place.definition(), Place.tier(). Only TravelService sends players to another place.

Streaming

Every place streams its world, with every streaming and simulation property set explicitly in its project file's Workspace $properties. Roblox lets these be set only in Studio or a place file, never by a script, and documents several of their Default values as subject to change, so the Template pins them. lune run new -- place copies them into a new place.

PropertyValueWhy
StreamingEnabledtrueJoin time and memory on phones
StreamingIntegrityModePauseOutsideLoadedAreaRoblox's recommendation: the character pauses only when it reaches unloaded space
StreamingMinRadius64Roblox's default, which the engine can shrink on low-end devices
StreamingTargetRadius512Half Roblox's 1024 default, a quarter of the area: less server work and client memory, still well above the minimum
StreamOutBehaviorOpportunisticRoblox's recommendation against out-of-memory crashes
ModelStreamingBehaviorImprovedModels stream with their parts instead of all arriving at join
SignalBehaviorImmediatePinned before Roblox switches Default to Deferred; moving to Deferred waits for a Studio pass
PlayerCharacterDestroyBehaviorEnabledOld characters and leaving players are destroyed, so their connections cannot leak
PhysicsSteppingMethodAdaptiveWhat Default means today, pinned: assemblies step at 240, 120 or 60 Hz as needed

A game that needs other radii or modes changes its project file and records why in its Game Overview. Sources: Instance streaming, Workspace.

Moving players

Every server move goes through AntiCheatService.teleport. A destination farther than Config/Streaming.streamAroundBeyondStuds (64) is streamed to the player first with Roblox/Streaming.streamAround(player, position, timeout?), which calls Player:RequestStreamAroundAsync with a timeout (2 seconds by default), so the move yields up to that long. A timeout is not a failure: the move goes ahead.

Waiting on the client

Roblox/Streaming.waitForStreamed("Lobby/Door", timeout?, root?) waits for each name of a path under Workspace within one timeout and returns a Result: the instance, or timeout. Use it, or Observers.observeTag for things that come and go, instead of a bare path.

Model streaming modes

A model code finds by tag declares its ModelStreamingMode: Atomic when it must arrive whole (NPC rigs are), Nonatomic for big containers. Persistent and PersistentPerPlayer models never stream out, so each needs a StreamingReason string attribute and they share Config/Streaming.persistentBudget (4).

The build check

lune run build audits every built place: a persistent model over the budget or without a reason, a tagged model left on Default, or a target radius not above the minimum fails the build, and so publish. It prints Streaming: <n> of <budget> persistent models per place.

How the Loader starts services and controllers

src/core/shared/Loader.luau is the whole framework. The server's init.server.luau passes it Services/ and the place's Place/Services; the client's init.client.luau passes Controllers/ and Place/Controllers. There is no registry and no injection: modules use each other with a plain require(script.Parent.OtherService).

A service that outgrows one file becomes a folder: Services/<Name>/init.luau, private parts beside it, and a README.md naming them. The Loader sees only the folder's module, and requires of it are unchanged. The Template's own are AdminService/, AntiCheatService/, DataService/, MonetizationService/, NpcService/ and PlatformService/, and on the client Controllers/DiagnosticsController/. A pure module can do the same: Rules/Platform/ is required as Rules/Platform, its init.luau re-exporting its parts.

  1. Require the modules

    Every ModuleScript directly inside those folders is required, sorted by name across both folders. Two modules with the same name (a stale copy saved in the place) load once, with a warning naming both. In one folder the copy kept is the one script.Parent.<Name> reaches (the folder's first child of that name), because every other module requires that one: it must be the copy whose init and start ran. Delete the copy the warning names.

  2. Check feature and place metadata

    A module exporting feature = "<switch>" is skipped while that switch in Config/Features is off; one exporting places is skipped in every place it does not list. Skipped means no init or start. Modules were still required to read metadata.

  3. Initialize without yielding

    Every remaining module's init runs one at a time in name order. It sets up state and connects events and remotes; the Loader warns when it yields or takes over 50 ms.

  4. Start each thread

    After every init has finished, each module's start runs in its own thread. It may yield and use other modules freely. The MicroProfiler shows <Module>.init and the part of <Module>.start before its first yield.

A module that errors is reported with its traceback and the rest keep loading; one whose init() errors is not started. More on writing a service.

How the Loader starts a server. The server entry point hands the Loader the core's Services folder and the place's own. The Loader requires every module, sorted by name, and skips any whose feature switch is off or whose places list leaves this place out. Then it runs every init, one at a time in name order, without yielding. Only after all of them have finished does it run every start, each in its own thread, where waiting is allowed.

Which side may require which

Dependencies go one way. The server and the client both require shared; shared requires neither; the server and the client never require each other.

  • bootstrap requires only shared/Config/Brand, Config/Loading, Config/Game (with the overrides they merge) and shared/assets, through WaitForChild, because it runs before anything else has replicated.

  • Inside shared: Config requires nothing but Util and its own game-owned Overrides/<Name>, which it merges over its defaults with Util/Overrides (Config and features); nothing else requires an overrides file; Rules require Util and take config as arguments; PlayerData requires Config and Util, AccountData only Util.

  • A place requires the core; the core never requires a place (it knows only Config/Game.places, not the slices). A place's pure module never requires the core's: a string require out of the slice resolves in Lune but not in the game, so what it needs comes in as an argument.

  • Services require each other in one direction. Alphabetical loading order is not a dependency order; a Signal breaks a cycle.

  • Controllers never require screens, except UIController mounting UI/App.

Which side may require which. The client and the server both require the shared side, and never each other. The bootstrap loading screen requires only a few shared config modules and the asset list. A place's slice requires the core, and the core never requires a place. Inside shared, Rules and Config are pure and require only Util.

The five core rules

  1. The server is the authority. Clients ask; the server decides. See Remotes and server authority.

  2. State lives in Charm atoms and flows one way: server atoms, CharmSync, client atoms, Fusion. Clients send intents through Remo remotes, never state.

  3. Data is immutable. Clone, change the clone, set the clone. Charm freezes tables in Studio, so a mutation throws at once.

  4. One module, one job. A service or controller owns one domain and its state.

  5. Pure where possible. Formulas, config, formatting and data shape are pure modules with specs; Roblox glue is thin and lives in services, controllers and Roblox/.

No frameworks, dependency injection containers, event buses, ECS, base classes or "manager" layers: services and controllers are plain modules with init() and start().

The boundaries lint-boundaries enforces

lune run lint-boundaries (part of lune run check) fails the build when code crosses one of these lines. Each Roblox API has one owner:

Only hereMay use
server/Services/DataServiceDataStoreService (ordered stores included), ProfileStore
server/Roblox/HttpRequestAsync, HttpService:GetAsync and PostAsync, GetSecret: every request budgeted, retried and counted; its callers are PlatformService and ExperienceNotificationService
server/Roblox/MemoryStoreMemoryStoreService, for every user: PlatformService's shared read cache, ExperienceNotificationService's schedule and limit, ReservedServerService's record of reserved servers
server/Roblox/MessagingBusMessagingService, through topics declared with a payload check and a publish rate
server/Services/MonetizationServiceMarketplaceService
client/Controllers/MonetizationControllerMarketplaceService, to prompt and look up prices
server/Services/AnalyticsServiceRoblox AnalyticsService
server/Services/TextFilterServiceFilterStringAsync
server/Services/RegionPolicyServicePolicyService
shared/Remotes.luauRemo.createRemotes, and Remo.remote only in the guarded constructors
client/UI/Topbar.luauTopbarPlus
AdminService/Commands/Moderation, AntiCheatServicePlayers:BanAsync and UnbanAsync
server/Services/TravelServiceTeleportService to another place
client/UI/Components/ScreenScreenGui
client/UI/Theme.luauColor3 literals, and the pixel values of padding and gaps (Theme.spacing) in the interface and the admin suite
client/UI/Util/motion (and presence)Fusion springs: they sleep once settled
shared/assets.luaurbxassetid:// strings
nowhereInstance.new("RemoteEvent") and kin

It also fails when client or shared code reaches ServerScriptService or ServerStorage, when an interface file requires Rules or a server service, shows a literal string instead of Localize.text("key"), or names a string key that does not exist, when a pure module touches game or uses an instance require, when a file lacks --!strict, when a server handler of a query (or an unthrottled intent) has no rate limit, when a handler on a per-frame RunService event (or BindToRenderStep) is not wrapped in Util/FrameBudget.wrap(label, handler) (the loading screen is exempt), when a Config module lacks its overrides file or another module requires one, when the loading screen's attribution is missing, and when a slice is missing a side or its project file, or a project file or src/ folder is orphaned.

Why the boundaries are enforced by a script and not by review

Each boundary keeps one dangerous API in one place: saves can only be written by the module that session-locks them, Robux only granted where receipts are recorded, and every remote passes the guard that knows its sender. A reviewer can miss a stray DataStoreService call; the lint cannot. ARCHITECTURE.md records it under Decisions: rules only reviewers knew were broken unnoticed and then copied.

Where state lives

Kind of stateLives in
Saved per save slotPlayerData, written through DataService.update
Saved per accountAccountData, written through DataService.updateAccount; a reward claimed once per account through ClaimService.claim
Saved for the whole gameDataService.getShared and updateShared
Rankings across every serverOrdered stores, through DataService.setOrdered and getOrderedTop
Per player, not savedAn atom in the owning service, synced under a per-player key
Server-wide, everyone sees itSharedState
Client-onlyClientState, or a local Fusion Value

See Data and saving and The interface.

The platform service in this architecture

PlatformService is an optional core service like any other: switched by Config/Features.platform, configured in the server-only Config/Platform.luau, with its pure rules in Rules/Platform/ (a folder module: Requests, Responses, Summaries and Cache, required as Rules/Platform). The service is a folder too: PlatformService/ with init, Connection, Reads, Writes and Status. It sends through server/Roblox/Http and caches through server/Roblox/MemoryStore. Its layers and lease are on Inside the Template's platform service; using it is on The Template's platform service.

Updated