Roblox Api

roblox-api

When to Use

Use this skill when the task is mainly about identifying or confirming the correct Roblox engine surface:

• Finding which class or service owns a capability.
• Checking whether a member is a property, method, event, or callback.
• Confirming datatype constructors, properties, methods, constants, or math behavior.
• Choosing the correct enum family and item for a property or parameter.
• Looking up globals such as game, workspace, script, plugin, or Enum.
• Confirming built-in library behavior such as task, math, string, table, os, or vector.
• Verifying exact parameter shapes, return values, and deprecation status before writing code.

Do not use this skill when the task is mainly about:

• Overall Roblox project structure, code placement, or client-server responsibility.
• Remote security, replication architecture, persistence design, or Open Cloud workflows.
• Broader system design where API lookup is secondary to structural decisions.

Decision Rules

• Use this skill if the main question is "what engine API should I call or read here?"
• Use this skill when a known problem needs the correct class, member, datatype, enum, global, or library surface.
• Start with the narrowest surface that matches the question:
• Class or service for engine objects and services.
• Datatype for value objects such as Vector3, CFrame, RaycastParams, or TweenInfo.
• Enum for preset values such as Enum.RaycastFilterType.Exclude.
• Global for always-available names like game, workspace, script, or Enum.
• Library for free functions under tables like task, math, table, or string.
• If the task is really about where code belongs, which side owns state, or how systems should be arranged, hand off to roblox-core.
• If the task centers on remotes, trust boundaries, replication correctness, or server authority, hand off to roblox-networking.
• If the task centers on persistent storage, quotas, save design, or cross-server state, hand off to roblox-data.
• If the task centers on Open Cloud, OAuth, or external integrations, hand off to roblox-cloud or roblox-oauth.
• If a request mixes referential lookup with out-of-scope design, answer only the engine-reference portion and explicitly exclude the rest.

Instructions

1. Identify the missing fact before searching:

• Which engine object or service is responsible?
• Which member kind is needed?
• Which datatype or enum is expected by the API?
• Which global or library helper fits the job?

2. Choose the correct reference file first:

• references/engine-overview.md for surface selection.
• references/classes-reference.md for class, service, and member lookup.
• references/datatypes-reference.md for value types and their usage.
• references/enums-reference.md for enum families and items.
• references/globals-reference.md for Luau and Roblox globals.
• references/engine-library-yaml-files.md for built-in libraries.
• references/datatype-yaml-files.md for interpreting datatype YAML shape and overloads.

3. Confirm the exact API contract before coding:

• Member name.
• Member kind.
• Parameter order and types.
• Return type.
• Property type.
• Enum family and item names.
• Deprecation or other tags.

4. Prefer the documented modern surface when an older global or legacy form also exists:

• Prefer task.wait() over wait().
• Prefer task.delay() over delay().
• Prefer game:GetService() for service access when clarity matters.

5. When a datatype or library page shows overloads, read all overloads before choosing a call pattern. 6. When a parameter or property type points to another datatype or enum, follow that dependency and confirm it separately. 7. Keep the answer referential and implementation-facing:

• Name the correct surface.
• State the relevant signature or property type.
• Mention any important enum values, tags, or constraints.
• Do not drift into architecture, persistence, or security-system design.

Using References

• Open references/engine-overview.md first when the user only knows the problem and not the engine surface.
• Open references/classes-reference.md when the question is about classes, services, or member discovery.
• Open references/datatypes-reference.md when a value object or helper container is involved.
• Open references/enums-reference.md when an API expects a preset constant.
• Open references/globals-reference.md when the question involves built-in names available in scripts.
• Open references/engine-library-yaml-files.md when the needed API lives under task, math, string, table, os, utf8, coroutine, debug, buffer, bit32, or vector.
• Open references/datatype-yaml-files.md when constructor overloads, mutable-vs-immutable behavior, constants, or member lists need careful interpretation.

Checklist

• The missing fact is identified as class, member, datatype, enum, global, or library lookup.
• The chosen engine surface is the narrowest one that matches the problem.
• Member kind, parameter order, return type, and property type are confirmed before use.
• Required enum family and item names are spelled exactly.
• Datatype constructors or methods match the documented overload.
• Deprecated globals or legacy forms are not recommended unless necessary for compatibility.
• The response stays referential and does not drift into project architecture, persistence, or cloud workflows.
• Out-of-scope systems are handed off to the proper Roblox skill when needed.

Common Mistakes

• Using roblox-api for project structure questions that belong to roblox-core.
• Guessing a member name without confirming whether it is a property, method, event, or callback.
• Passing raw numbers where an enum item is expected.
• Treating a datatype like an Instance class, or vice versa.
• Missing constructor overloads and choosing the wrong parameter order.
• Recommending deprecated globals like wait() or delay() when task equivalents are the modern surface.
• Assuming a global exists in every context, especially plugin.
• Expanding a simple API lookup into networking, data, or cloud-system design.

Examples

Choose the right surface for a raycast

• Class or service: Workspace (via WorldRoot behavior)
• Method: Workspace:Raycast(origin, direction, raycastParams)
• Datatype: RaycastParams
• Enum: Enum.RaycastFilterType
• Result datatype: RaycastResult

Confirm a tween API call

• Class or service: TweenService
• Method: TweenService:Create(instance, tweenInfo, propertyTable)
• Datatype: TweenInfo
• Enums often involved: Enum.EasingStyle, Enum.EasingDirection

Distinguish global, datatype, and enum usage

local Workspace = game:GetService("Workspace")

local params = RaycastParams.new()
params.FilterType = Enum.RaycastFilterType.Exclude

local cf = CFrame.lookAt(Vector3.new(0, 5, 10), Vector3.zero)

• game is a Roblox global.
• RaycastParams, CFrame, and Vector3 are datatypes.
• Enum.RaycastFilterType.Exclude is an enum item.

Classes Reference

Key Concepts

• Classes are engine objects and services exposed by Roblox.
• Class members fall into four main kinds: properties, methods, events, and callbacks.
• Service classes are commonly acquired with game:GetService("ServiceName").
• Docs often express class references as Class.Name and member references as Class.Name.Member.
• API lookup for classes is about finding the owner of a capability and then confirming the exact member contract.

Rules

• Identify the owning class before choosing a member.
• Distinguish service access from instance access:
• Services come from game:GetService().
• Child instances come from hierarchy references such as workspace.Part.
• Confirm whether a member is read or write state, an action, an event signal, or a callback hook.
• Do not turn class lookup into architecture advice about where scripts belong or which side should own the system.
• If the target class belongs to networking, persistence, or cloud workflows as the main topic, hand off to the corresponding skill instead of expanding it here.

Patterns

Find the right owner

• World and spatial queries usually point to Workspace or WorldRoot behavior.
• Player lifecycle and player containers usually point to Players or Player.
• Animation and tween creation usually point to TweenService.
• Frame-step and runtime loop hooks usually point to RunService.
• Collision-group operations usually point to PhysicsService.

Confirm member kind before use

• Property: read or assign state, such as Camera.CameraType.
• Method: call an action, such as Workspace:Raycast().
• Event: connect to a signal, such as Players.PlayerAdded.
• Callback: assign a handler when the API exposes a callback member instead of an event.

Read signatures literally

• Methods need exact parameter order and types.
• Properties need exact value type, often a datatype or enum item.
• Events and callbacks need the correct handler argument list.

Examples

Spatial query

local Workspace = game:GetService("Workspace")
local result = Workspace:Raycast(origin, direction, params)

• Owning class: Workspace
• Member kind: method
• Related datatype: RaycastParams

Player lifecycle

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
  print(player.Name)
end)

• Owning class: Players
• Member kind: event

Tween creation

local TweenService = game:GetService("TweenService")
local tween = TweenService:Create(part, tweenInfo, {Transparency = 1})

• Owning class: TweenService
• Member kind: method
• Related datatype: TweenInfo

Datatype YAML Files

Key Concepts

• Datatype YAML files are the most detailed source for Roblox value-type lookup in this repository.
• A datatype file usually includes:
• name, type, summary, and description
• constructors
• constants
• properties
• methods
• functions
• math_operations
• tags
• deprecation_message
• These files define both what a datatype is and how it must be used.

Rules

• Read all constructor overloads before choosing a call shape.
• Use constants when they provide canonical values such as Vector3.zero.
• Check property types carefully; they often lead to other datatypes or enum families.
• Use methods for operations tied to a datatype instance.
• Read math_operations when operator support matters.
• Respect tags and deprecation_message exactly.
• Note mutability:
• Helper containers like RaycastParams can be mutated after construction.
• Many spatial and scalar datatypes are immutable and require creating new values.

Patterns

Read by question type

• "How do I construct it?" -> constructors
• "Does it have a built-in constant?" -> constants
• "What fields can I read?" -> properties
• "What can I call on it?" -> methods
• "Can I use operators with it?" -> math_operations

Follow linked types

• RaycastParams.FilterType points to RaycastFilterType, so validate the enum item too.
• CFrame methods and constructors often depend on Vector3.
• EnumItem.EnumType points back to Enum.

Examples

Mutable configuration datatype

local params = RaycastParams.new()
params.FilterDescendantsInstances = {character}
params.FilterType = Enum.RaycastFilterType.Exclude

• Constructor comes from constructors.
• Editable fields come from properties.

Overloaded constructor datatype

local cf = CFrame.new(0, 5, 0)
local look = CFrame.lookAt(Vector3.new(0, 5, 10), Vector3.zero)

• CFrame has multiple constructor shapes.
• The correct overload depends on the exact inputs you already have.

Datatypes Reference

Key Concepts

• Datatypes are Roblox value objects and helper containers, not Instance classes.
• Common datatypes include spatial values like Vector3 and CFrame, colors like Color3, UI values like UDim2, helper containers like RaycastParams and OverlapParams, and timing or config objects like TweenInfo and DateTime.
• Datatypes can expose constructors, constants, properties, methods, and math operations.
• Some datatypes are immutable value types, while others are mutable containers whose properties can be edited after construction.

Rules

• Use datatype constructors and methods exactly as documented; overloads matter.
• Do not confuse datatypes with services or Instances.
• Follow the type exactly when a class member expects a datatype.
• Treat helper containers such as RaycastParams and OverlapParams as configuration objects that must be populated before use.
• Prefer documented constructors or static helpers over guessed field assignments.
• When a datatype property type points to an enum, confirm the enum item separately.

Patterns

Pick the datatype by job

• Position, size, direction, velocity: Vector2, Vector3, Vector2int16, Vector3int16
• Position plus orientation: CFrame
• Color values: Color3, BrickColor, ColorSequence
• UI size and position: UDim, UDim2
• Ray or overlap configuration: RaycastParams, OverlapParams
• Tween configuration: TweenInfo
• Time and timestamps: DateTime
• Randomness: Random

Know the mutable helpers

• RaycastParams is mutable after RaycastParams.new().
• OverlapParams is mutable after OverlapParams.new().
• Many numeric and vector-like datatypes are immutable; build new values instead of trying to mutate components directly.

Read all available members

• Constructors define creation patterns.
• Constants expose reusable values like Vector3.zero.
• Properties expose components or state.
• Methods expose operations such as CFrame:ToWorldSpace() or Vector3:Dot().
• Math operations describe valid operators and result types.

Examples

Configure a raycast

local params = RaycastParams.new()
params.FilterDescendantsInstances = {script.Parent}
params.FilterType = Enum.RaycastFilterType.Exclude
params.IgnoreWater = true

Build a facing transform

local cf = CFrame.lookAt(Vector3.new(0, 5, 10), Vector3.zero)

Configure a tween

local info = TweenInfo.new(0.4, Enum.EasingStyle.Quad, Enum.EasingDirection.Out)

Engine Library YAML Files

Key Concepts

• Built-in engine and Luau libraries are documented as YAML records with a consistent shape.
• Common library files describe tables such as task, math, string, table, os, utf8, coroutine, debug, buffer, bit32, and vector.
• Library YAML files usually expose:
• name and type
• summary and description
• properties
• functions
• parameters
• returns
• tags
• deprecation_message

Rules

• Read library files as free-function documentation, not class-member documentation.
• Check properties for constants such as math.pi or vector.zero.
• Check functions for callable helpers such as task.delay() or math.clamp().
• Treat tags and deprecation_message as authoritative when choosing modern APIs.
• When a deprecated global has a modern library replacement, recommend the library.

Patterns

Interpret the YAML shape

• properties describe values on the library table.
• functions describe callable helpers on the library table.
• parameters define ordered arguments and types.
• returns define result types and count.

Pick the right library

• Scheduling and yielding: task
• Numeric helpers: math
• Text operations: string and utf8
• Table manipulation: table
• Time and environment helpers: os
• Coroutines: coroutine
• Bitwise helpers: bit32
• Buffer operations: buffer
• Low-level debugging helpers: debug
• Vector primitive helpers: vector

Examples

task.delay(0.25, function()
  print("later")
end)

local alpha = math.clamp(rawAlpha, 0, 1)

• task.delay() is the modern scheduled-call surface.
• math.clamp() is a library function with ordered numeric parameters.

Engine Overview

Key Concepts

• Roblox engine API lookup usually lands on one of five surfaces: classes, datatypes, enums, globals, or built-in libraries.
• Classes represent engine objects and services. Their members are properties, methods, events, and callbacks.
• Datatypes represent value objects and helper containers such as Vector3, CFrame, Color3, RaycastParams, TweenInfo, and DateTime.
• Enums provide named constant families such as Enum.RaycastFilterType, Enum.CameraType, or Enum.EasingStyle.
• Globals are built-in names available in script contexts, including Luau globals and Roblox globals.
• Libraries are tables of functions and constants such as task, math, string, table, os, utf8, coroutine, debug, buffer, bit32, and vector.

Rules

• Start with the smallest surface that answers the question.
• Use a class or service when the capability belongs to an engine object.
• Use a datatype when the API needs a value object, helper container, or result object.
• Use an enum when an API expects a preset choice rather than a free-form value.
• Use a global only when the symbol is actually built into the runtime context.
• Use a library when the behavior is a free function rather than a class or datatype member.
• Confirm member kind, parameter order, return type, and deprecation status before writing code.

Patterns

Map the question to a surface

• "What service owns this behavior?" -> class or service lookup.
• "What object do I pass here?" -> datatype lookup.
• "What value should this property be set to?" -> enum lookup.
• "Can I call this name directly in a script?" -> global lookup.
• "Is this helper under task, math, or string?" -> library lookup.

Follow type dependencies

• If a method parameter is typed as a datatype, open the datatype reference next.
• If a property or parameter is typed as an enum family, confirm the correct enum item before coding.
• If a deprecated global points to a library replacement, prefer the library.

Examples

Raycast selection

• World query surface: class Workspace
• Configuration surface: datatype RaycastParams
• Choice surface: enum Enum.RaycastFilterType
• Result surface: datatype RaycastResult

Tween selection

• Engine owner: class TweenService
• Configuration object: datatype TweenInfo
• Preset values: Enum.EasingStyle and Enum.EasingDirection

Global versus library

• game is a Roblox global.
• Enum is a Roblox global that exposes enum families.
• task.wait() is a library call, not a global.

Enums Reference

Key Concepts

• Enums are named families of preset constants used by Roblox APIs.
• Access enum items through Enum.EnumName.ItemName.
• Enum is exposed through a Roblox global, while the underlying datatype system also includes Enums, Enum, and EnumItem.
• Enum values should usually be passed as named items, not as raw integers.

Rules

• Match the exact enum family required by the property or parameter type.
• Use the named enum item instead of guessing the backing numeric value.
• Confirm spelling and capitalization exactly.
• When an API says a property type is an enum family such as RaycastFilterType, use Enum.RaycastFilterType.<Item>.
• Use enum helpers only when needed:
• Enum:GetEnumItems() to inspect all items in a family.
• Enum:FromName() or Enum:FromValue() when converting dynamically.

Patterns

Common enum usage

• Filtering choice: Enum.RaycastFilterType.Exclude
• Camera mode: Enum.CameraType.Scriptable
• Easing style: Enum.EasingStyle.Quad
• Easing direction: Enum.EasingDirection.Out

Connect enum lookup to API types

• If a property type is an enum family, pick an item from that family only.
• If a datatype property points to an enum family, validate both the datatype and the enum item.
• If a constructor or method accepts multiple enum parameters, confirm each family independently.

Examples

params.FilterType = Enum.RaycastFilterType.Exclude
camera.CameraType = Enum.CameraType.Scriptable
local info = TweenInfo.new(0.25, Enum.EasingStyle.Quad, Enum.EasingDirection.Out)

• Enum.RaycastFilterType.Exclude is an enum item used by RaycastParams.FilterType.
• Enum.CameraType.Scriptable is an enum item used by Camera.CameraType.
• TweenInfo.new() commonly combines more than one enum family.

Globals Reference

Key Concepts

• Roblox scripts expose both Luau globals and Roblox-specific globals.
• Luau globals include core functions such as assert, error, ipairs, pairs, pcall, type, and shared tables like _G.
• Roblox globals include engine-specific names such as game, workspace, script, shared, plugin, and Enum.
• Some older Roblox globals are deprecated in favor of modern library APIs.

Rules

• Confirm that the symbol is truly global before using it without qualification.
• Prefer Roblox globals for canonical engine entry points:
• game for the DataModel
• workspace for the Workspace service
• script for the currently running source container
• Enum for enum families
• Treat plugin as context-specific; it exists only in Studio plugin execution.
• Prefer task.wait() and task.delay() over deprecated global wait() and delay().
• Keep global lookup referential; do not turn _G or shared into broader architecture guidance.

Patterns

Common Roblox globals

• game:GetService("Players")
• workspace.CurrentCamera
• script.Parent
• Enum.RaycastFilterType.Exclude

Luau global utility

• assert(condition, message) for invariant checks
• pcall(fn) for protected calls
• type(value) or typeof(value) when validating values in Roblox code

Context-sensitive global

• plugin should be used only when code is executing as a Studio plugin.

Examples

local Players = game:GetService("Players")
local camera = workspace.CurrentCamera

assert(camera ~= nil, "Expected a current camera")
task.wait()

• game and workspace are Roblox globals.
• assert is a Luau global.
• task.wait() is preferred over deprecated global wait().