Engine reference

AGENTS.md says never to guess a Roblox API from memory. 0.9.0 ships what makes that practical offline: tools/engine-api.json, a pinned snapshot of the official Engine API reference; tools/engine.py, which looks things up in it; nine domain guides under docs/agents/Engine/ for behavior the signatures do not tell you; and directives CK014 and CK015, which reject deprecated, nonexistent and plugin-only names during the check. The snapshot is pinned on purpose: every machine and every CI run sees the same reference, and a lookup never changes under you until someone refreshes it deliberately.

The snapshot

tools/engine-api.json is generated from the content/en-us/reference/engine folder of the Roblox/creator-docs repository at the commit recorded in its source entry (0b817b5c at 0.9.0; the domain guides date the snapshot 2026-09-26). It holds:

Kind	Count
Classes	625
Enums	507
Datatypes	49
Libraries	11
Globals	2

Each class records its one-sentence summary (capped at 240 characters), any deprecation message, its full inheritance chain nearest first, its tags (Service, NotCreatable, NotReplicated, …) and its members. Each member records its kind, a signature, a summary, its flags and any deprecation message. Enums record every item with its value and deprecation message, in declaration order. The file is about 1.4 MB, one line per entry, so a refresh reads as a reviewable diff.

Flags follow the reference:

Flag	Meaning
Yields	The call can suspend the thread. Never call it in frame callbacks, Scheduler jobs or grant handlers without task.spawn and a busy flag.
thread=Safe, thread=Unsafe	Callable, or not, from a desynchronized (parallel) thread. No flag means read-safe.
ReadOnly, NotReplicated, Hidden, NotScriptable	Cannot be written; does not cross the network; not shown in Studio; not reachable from scripts.
CustomLuaState	An engine tag the reference lists but does not describe.
PluginSecurity, RobloxScriptSecurity, …	The minimum script identity. Game scripts run with none.
caps=...	The script capability sandboxed code needs for the member.
cat=...	The property’s category in the Properties window.

Looking things up

python tools/engine.py Workspace                  # class: ancestry, tags, its own members with flags
python tools/engine.py Workspace --inherited      # plus every inherited member
python tools/engine.py Workspace:Raycast          # one member (also Workspace.Gravity, Humanoid.Died)
python tools/engine.py Enum.RaycastFilterType     # enum items with values, in declaration order
python tools/engine.py buffer.writeu32            # library, global or datatype member
python tools/engine.py Players:BanAsync Players:UnbanAsync   # several queries in one call
python tools/engine.py --search stream around     # names and summaries containing every word
python tools/engine.py --deprecated Humanoid      # deprecated items and their replacements
python tools/engine.py --full Players:BanAsync    # the complete reference entry

The Enum. prefix is optional when no class, datatype, library or global has the same name. A member lookup walks the class’s ancestry, so Part:GetMass finds the member on BasePart and prints the owner. The first line of a result is the signature and its flags, the next line is the summary, and a deprecated member adds a DEPRECATED: line with the replacement the reference names:

$ python tools/engine.py Players:BanAsync
Players:BanAsync(config: Dictionary) -> ()  [Yields; thread=Unsafe; caps=Players,Consequences]

--search lower-cases the words and keeps any class, member or enum whose name and summary contain all of them. --deprecated without a name lists every deprecated class, member and enum item in the snapshot.

--full prints the reference entry the snapshot summarizes. The first request for a class downloads its YAML from raw.githubusercontent.com at the pinned commit and caches it in .tools/engine-cache/<commit>/<kind>/<Name>.yaml; later requests read the cache and need no network. With a member, it prints that member’s block, walking the ancestry the same way. It honors SSL_CERT_FILE and REQUESTS_CA_BUNDLE for proxies with their own certificates.

The exit status is 0 when every query was found, 1 when one was not (or a search matched nothing), and 2 with no query.

Typo suggestions

A miss prints the closest names instead of a bare failure:

$ python tools/engine.py Humanoid:LoadAnimaton
engine: Humanoid:LoadAnimaton is not in the reference snapshot; did you mean: Humanoid.LoadAnimation, Humanoid.loadAnimation

For a member of a known class, suggestions come from that class’s own and inherited members at a similarity cutoff of 0.6. Anything else is matched against every class, member and enum item name at a cutoff of 0.75. At most 6 suggestions print. A suggestion can itself be deprecated (Humanoid.LoadAnimation is), so look up the suggestion before using it.

Domain guides

docs/agents/Engine.md indexes nine guides distilled from the same snapshot. They record what the reference states (behavior, ordering, limits, security, thread safety, deprecations and replacements) and say so where the reference is silent. Most end with the same sections: limits and numbers, deprecated APIs with their replacements, newer or easily missed APIs, and the events that replace polling.

Guide	Covers
Runtime.md	The instance model and DataModel, RunService frame order, signals and deferral, task and the Luau libraries, parallel Luau, attributes and tags, HttpService and EncodingService, core datatypes.
Network.md	Remotes and their limits, replication order, instance streaming, network ownership and server authority, Players and Player, teams, MessagingService, bans and moderation.
Platform.md	DataStores, MemoryStores, MarketplaceService and receipts, teleports, ConfigService and MatchmakingService, badges, policy, social, analytics, text filtering and chat, localization, assets.
Physics.md	Workspace and WorldRoot queries, parts and models, constraints and movers, joints, collision groups, terrain, pathfinding, CSG and editable geometry.
Character.md	Humanoid and its states, rigs and joints (including AnimationConstraint from the Avatar Joint Upgrade), Animator and tracks, IK, controllers, HumanoidDescription, accessories and layered clothing, tools.
Input.md	UserInputService, ContextActionService, the Input Action System, camera, mouse and touch, gamepads and haptics, VR, prompts and detectors, GuiService.
UI.md	GuiObjects, ScreenGui and 3D surfaces, layouts and UI components, the styling system, text and rich text, adornments and handles.
Media.md	The audio graph and the legacy Sound system, particles, beams and trails, lighting and post effects, materials, tweens, video, content preloading.
Studio.md	Studio and plugin APIs, test and profiling services, engine-internal services, and every legacy or deprecated class with its modern replacement.

The order to use them in: --search or the guide to find an API for a job, a plain lookup for the exact signature and flags before calling it, then the guide and --full when ordering, replication, errors or limits matter.

CK014 and CK015

The directive linter reads the same file. CK014 fails the check for a deprecated or nonexistent engine class, service, enum or enum item, method, event or global, for a legacy class at creation (Instance.new("Motor")), and for a member deprecated only on the class a receiver is named after (humanoid:LoadAnimation). CK015 fails it for plugin-only services, whose every method needs Plugin security, and for settings() in game code. Both name the replacement in their message. tools/test_engine.py checks that the data file is pinned and complete, that every ancestor exists, and that lookups, searches, suggestions and --full member extraction behave; it runs in the tooling step of the check.

Refreshing the snapshot

git clone --depth 1 --filter=blob:none --sparse https://github.com/Roblox/creator-docs.git /tmp/creator-docs
git -C /tmp/creator-docs sparse-checkout set content/en-us/reference/engine
python tools/engine.py --refresh /tmp/creator-docs   # needs PyYAML
python tools/check.py                               # CK014 now reflects the new deprecations

--refresh rewrites tools/engine-api.json from the checkout, records its commit, and prints the new counts. Review the diff for newly deprecated members the framework uses, and update the domain guides where the behavior they describe changed.

Gotchas

Caution

The snapshot is a point in time. An API Roblox added after it reads as “not in the reference snapshot”, and CK014 rejects it as nonexistent. Refresh the snapshot in its own change before adopting a new API; do not suppress CK014.

Note

--full needs network access the first time it sees a class, and it writes into .tools/engine-cache. The lookups, search and the linter never touch the network.