API Settings

API: Settings

Settings.luau is the framework's static configuration table. It exports a plain mutable table; there are no setter functions or metatable helpers.

Important

Docs audit note (2026-05): This page was re-audited against FSM/Orchestrator/Core/Settings.luau and the code paths that consume it.

---

🎯 Overview

Source of truth:

local Settings = require(FSM.Orchestrator.Core.Settings)

After bootstrap, the same table is also exposed through the Orchestrator (FSM.Orchestrator.Settings) and shared bootstrap state used elsewhere in the framework.

The current file returns this shape:

return {
    Scheduler = { FrameBudget = 0.015 },
    Logger = { DebuggingEnabled = true, MinimumLoggingLevel = 3 },
    DataStore = {
        ResetAccessCountIntervalInSeconds = 60,
        DataStoreName = "EntityPersistence",
        KeyPrefix = "Entity",
        PersistenceEnabled = true,
    },
    FSMSettings = { Debug = true, LogLevel = 1 },
    Orchestrator = { MaxSanitizationDepth = 8 },
    StaticStrings = {
        Instance = {
            OrchestratorEventName = "OrchestratorEvent",
            OrchestratorFunctionName = "OrchestratorFunction",
            EntityUpdateEventName = "EntityUpdateEvent",
            EntityCommandEventName = "EntityCommandEvent",
            ResetDataStoreAccessCountTaskName = "ResetDataStoreAccessCount",
        },
        Error = { ... },
    },
    ServiceManager = { Enabled = true },
}

---

🔧 Settings tree

Scheduler

Key	Type	Default	Used by
FrameBudget	number	0.015	scheduler frame-budget execution

Logger

Key	Type	Default	Used by
DebuggingEnabled	boolean	true	master console-output switch
MinimumLoggingLevel	number	3	Logger console severity gate

Logger gate mapping in the current source:

• 1 => print ERROR
• 2 => print WARN + ERROR
• 3 => print INFO + WARN + ERROR
• 4 => print DEBUG + everything above

DataStore

Key	Type	Default	Notes
ResetAccessCountIntervalInSeconds	number	60	scheduler interval for access-count reset
DataStoreName	string	"EntityPersistence"	default root store name
KeyPrefix	string	"Entity"	prefixed onto persistence keys
PersistenceEnabled	boolean	true	master persistence toggle

FSMSettings

Key	Type	Default	Notes
Debug	boolean	true	FSM debug toggle
LogLevel	number	1	source comment: “minimum logging level for FSM”

Note

FSMSettings.LogLevel is not the same scale as Logger.MinimumLoggingLevel. The source only documents it as the FSM subsystem's own minimum log level with default 1.

Orchestrator

Key	Type	Default	Used by
MaxSanitizationDepth	number	8	orchestrator-side table sanitization before client replication

StaticStrings.Instance

Key	Default	Meaning
OrchestratorEventName	"OrchestratorEvent"	async client→server request remote
OrchestratorFunctionName	"OrchestratorFunction"	sync client→server request remote
EntityUpdateEventName	"EntityUpdateEvent"	server→client entity delta remote
EntityCommandEventName	"EntityCommandEvent"	bidirectional entity-command remote
ResetDataStoreAccessCountTaskName	"ResetDataStoreAccessCount"	scheduled DataStore reset task name

StaticStrings.Error

These are internal message templates used by framework assertions / logs.

Key	Default string
RemoteNotFoundErrorMessage	"CreateRemote called without a %s"
FSMAlreadyFoundErrorMessage	"FSM already registered"
UnresolvableConstructorErrorMessage	"%s called with nil/unresolvable %s"
EntityRequiresInstanceErrorMessage	"Entity '%s' requires an 'Instance' in its context."
AlreadyExistsErrorMessage	"%s '%s' already exists. Returning existing instance."
InstantializationFailureErrorMessage	"Failed to instantiate %s '%s': %s"
AttachServiceSingletonErrorMessage	"AttachServiceManager can only be called on the client"
ServiceManagerDisabledErrorMessage	"ServiceManager is disabled in settings"
ServiceManagerInitializationFailureErrorMessage	"Failed to initialize ServiceManager: %s"
MissingServiceManagerChildErrorMessage	"Missing child 'ServiceManager' under Orchestrator module"
FailedToCreateErrorMessage	"Failed to create %s '%s'."
AsyncRequestFailureErrorMessage	"Failed to handle async request '%s': %s"
ServerRequestErrorMessage	"This API is inaccessible on the client."
ClientRequestErrorMessage	"This API is inaccessible on the server."

ServiceManager

Key	Type	Default	Current effect
Enabled	boolean	true	gates code paths that explicitly consult ServiceManager settings

In current audited code, the most visible direct gate is the extra server-side FSM state-change broadcast hook in Core/Factory/init.luau.

---

🛠️ Usage patterns

Example 1: Override before bootstrap

local Settings = require(FSM.Orchestrator.Core.Settings)
Settings.Logger.MinimumLoggingLevel = 4
Settings.ServiceManager.Enabled = false

FSM.Orchestrator:RegisterComponents()

Example 2: Rename remotes before NetworkManager starts

local Settings = require(FSM.Orchestrator.Core.Settings)
Settings.StaticStrings.Instance.OrchestratorEventName = "MyGame_OrchestratorEvent"
Settings.StaticStrings.Instance.OrchestratorFunctionName = "MyGame_OrchestratorFunction"

FSM.Orchestrator:RegisterComponents()

Example 3: Tighten scheduler budget

local Settings = require(FSM.Orchestrator.Core.Settings)
Settings.Scheduler.FrameBudget = 0.008

FSM.Orchestrator:RegisterComponents()

---

⚠️ Edge cases and pitfalls

1. Remote names must be changed before bootstrap. NetworkManager.Initialize(...) resolves / creates the remotes once.

2. Settings are mutable at runtime, but consumers vary. Logger gates react immediately; bootstrap-created remotes do not.

3. ServiceManager.Enabled is not a universal kill-switch. Only code that explicitly checks it is affected.

4. StaticStrings.Error is internal API. Changing message templates can desynchronize tests or error parsing.

5. There is no table.freeze. Any script holding a reference can mutate the settings table.

---

🔗 See also

• API-Logger
• API-NetworkManager
• API-ServiceManager
• Production-Readiness