instances
Provides functions to manipulate instances.
Types
TouchType
Typetype
TouchType =
1
|
0
Describes a TouchType for the firetouchinterest function.
1
stands for Touch
, while 0
stands for TouchEnded
.
Functions
cloneref
Clones a reference of the given instance and returns it.
Usage
By cloning references to instances, you can bypass weak table-style attacks, which is a way of detecting references to objects which should not have references.
compareinstances
instances.
compareinstances
(
) →
boolean
--
If true, both references point to the same instance, else false.
Compares the underlying instances of two object references.
Usage
instances.cloneref
allows you to clone a reference to an object, this breaks the normal way Roblox performs equality checks.
This function allows you to compare the actual thing the two references point to, allowing you to know if they reference the same instance!
invalidatereference
Invalidates the reference of the given instance.
Usage
Invalidating the reference to an instance allows you to make subsequent calls to certain functions return a different pointer instead of the one you have. This also makes the reference you hold unique to you up to that point.
Errors
Type | Description |
---|---|
The reference cannot be invalidated (not in cache) | The reference you provided cannot be invalidated, this is due to it not being on the instance cache. |
isreferencevalid
instances.
isreferencevalid
(
) →
boolean
--
If true, the reference to the instance is still valid.
Checks if the reference to the given instance is still valid.
Usage
This function is used to check if an instance is still valid after the reference is invalidated using instances.invalidatereference
.
replacereference
instances.
replacereference
(
) →
(
)
Makes all references that point to object1
point to what object2
is referencing instead.
Usage
You can use this function to replace references to an instance all throughout the game. i.e.: replacing a Value instance and affecting all already obtained references to it.
Remarks
Some instances, such as the DataModel (aka game
), are not affected by this function.
Errors
Type | Description |
---|---|
The reference cannot be modified (not in cache) | The reference you provided cannot be modified, this is due to it not being on the instance cache. |
getplaceversion
instances.
getplaceversion
(
) →
number
--
The version of the place.
Gets the version of the place you are in.
Usage
This function can be used to guarantee features work only on a version deemed 'safe' of the game. Useful for premium scripts.
getcallbackvalue
instances.
getcallbackvalue
(
prop:
string
--
The name of the callback property.
) →
(
T...
)
→
U...
|
nil
--
The callback that the instance contains at the given property.
Returns the callback value of the given instance and property.
Errors
Type | Description |
---|---|
property with name '%s' does not exist. | The given property (named %s) does not exist on the given instance. |
gethiddenproperty
instances.
gethiddenproperty
(
prop:
string
--
The property to get.
) →
(
U
,
--
The value of the property.
boolean
--
True if the property was hidden, false if it was not.
)
Returns the property of the given instance.
Remarks
You must support pushing unserializable properties such as 'SharedString
' and 'SystemAddress
'.
Implementation
You are supposed to obtain the property using the RBX::Instance::getProperty
/ RBX::Instance::setProperty
methods. You must not set the property public or scriptable.
Errors
Type | Description |
---|---|
property with name '%s' does not exist. | The given property (named %s) does not exist on the given instance. |
getsignalargumentnames
instances.
getsignalargumentnames
(
) →
{
string
}
--
An array-like table containing the names of the arguments.
Returns the names of the arguments that a signal's OnConnect
callback receives.
Errors
Type | Description |
---|---|
Expected RBXScriptSignal | The provided argument was not an `RBXScriptSignal`. |
getsignalargumenttypes
instances.
getsignalargumenttypes
(
) →
{
string
}
--
An array-like table containing the type or class names of the arguments.
Retrieves the type(s) (or class name(s) for Instances) of the arguments that a signal's OnConnect
callback receives.
Errors
Type | Description |
---|---|
Expected RBXScriptSignal | The provided argument was not an `RBXScriptSignal`. |
getscriptbytecode
instances.
getscriptbytecode
(
) →
string
--
The bytecode of the script.
Retrieves the raw Luau bytecode of the given LuaSourceContainer
(Script, LocalScript, ModuleScript).
Team Create
Fetching bytecode for Server Scripts in Team Create sessions may not be supported.
Errors
Type | Description |
---|---|
userdata<Instance<LuaSourceContainer>> | The provided argument was not a `LuaSourceContainer` instance. |
bytecode not found | The script does not contain bytecode (e.g., it's empty or an external script). |
unknown error occurred while trying to fetch script closure. | An internal error occurred, possibly related to incompatible environment (e.g., Team Create for Server Scripts). |
getcallingscript
instances.
getcallingscript
(
) →
(
LuaSourceContainer
|
string
)
?
--
The calling script instance, or nil
if called from a context without a script (e.g., command bar), or string if an error occurred.
Returns the LuaSourceContainer
instance of the script that called this function.
getsenv
instances.
getsenv
(
) →
T
|
nil
--
The environment of the script, nil if the script is not running.
Returns the environment of the given running script.
Implementation
This function may perform GC scans to find script threads and obtain their environment.
Actors
If the script is running in a different mainthread
you must throw the 'script is running in a different Luau VM' error in order to prevent possible vulnerabilities and other issues associated with actors.
Errors
Type | Description |
---|---|
script is running in a different Luau VM | The script you tried to get the environment does not share the same mainthread state (Running under an actor/ in a different Luau VM). |
getscriptclosure
instances.
getscriptclosure
(
) →
(
(
T...
)
→
(
U...
)
)
|
nil
--
The 'main' closure of the script, nil
if the script has no bytecode.
Returns a non-runnable closure which holds debug info (constants, upreferences, debugname, etc.) of the script's main thread.
Implementation
This function may not perform a GC scan in an effort to find the Script object.
Errors
Type | Description |
---|---|
Cannot get closure of a server script | The script provided is a server script, and its source isn't available. |
exchangeinstancepointer
instances.
exchangeinstancepointer
(
) →
(
)
Exchanges the underlying pointer between two instances.
Usage
This can be used in place of instances.replacereference
if the user already holds a reference to the object you want replaced.
This function, unlike instances.replacereference
will overwrite the underlying pointer to the instance in the provided reference. This makes it so all instances of this reference are affected, regardless of whether they're just newly obtained from the Instance cache.
Implementation
The instances MUST be strictly checked to be such.
fireclickdetector
instances.
fireclickdetector
(
distance:
number?
,
--
The distance to fire the event at, if nil, defaults to 0.
eventName:
"MouseClick"
|
"RightMouseClick"
|
"MouseHoverEnter"
|
"MouseHoverLeave"
|
nil
--
The event to fire, if nil, defaults to "MouseClick"
) →
(
)
Fires a click detector event, which replicates to the server.
Implementations
You should not implement this function in luau.
firetouchinterest
instances.
firetouchinterest
(
) →
(
)
Fires a physics interaction between the given BasePart
objects, which replicates to the server.
Implementations
You should not implement this function in luau.
Errors
Type | Description |
---|---|
no world found | No RBX::World was found for either Part1 or Part2. |
overlap in a different world | Part1 and Part2 live in different RBX::World's and they cannot interact with each other. |
fireproximityprompt
Fires a proximity prompt's Triggered
signal, which replicates to the server.
Implementations
You should not implement this function in luau.
gethui
Returns the folder used by the executor to place User Interfaces.
Weak-Table attacks
This function may be vulnerarble to weak-table style attacks if not properly implemented.
Make a folder, parent it to CoreGui, and then use instances.invalidatereference
on it, then return the created folder, this should protect you from this kind of attack!
ContentProvider attacks
Game developers can use ContentProvider:PreloadAsync
to detect assets loaded in CoreGui when they should not be loaded, due to this they can check if any UI has been loaded that is not the
default ROBLOX Core Gui. You must protect yourself from this kind of attack by caching the return of CoreGui for the function, and returning the cached value after gethui is called. This should maintain the integrity of the system while hiding the new assets that are loaded on CoreGui. This change may also be needed on the game
instance.
getinstances
Returns a list with all instances that are currently referenced by the game.
Actors
If an instance is referenced inside an actor, this list of instances should not contain it!
getnilinstances
instances.
getnilinstances
(
) →
{
Instance
}
--
All instances that are currently referenced by the game, but with no parent.
Returns a list with all instances that are currently referenced by the game and are not parented to anything.
Actors
If an instance is referenced inside an actor, this list of instances should not contain it!
getinstancelist
instances.
getinstancelist
(
) →
{
[
userdata
]
:
Instance
}
--
The internal list ROBLOX uses for holding references to instances in Luau.
Returns a dictionary with all instances that are currently referenced by the game as their value, and a lightuserdata as their key.
This dictionary is also known as the instance cache.
Actors
If an instance is referenced inside an actor, this list of instances should not contain it!
getscripts
instances.
getscripts
(
) →
{
LuaSourceContainer
}
--
An array-like table containing all script instances.
Retrieves a list of all script instances (i.e., Script
, LocalScript
, ModuleScript
and AuroraScript
) currently referenced by the game.
Actors
If a script instance is referenced inside an actor, this list of instances should not contain it!
getconnections
instances.
getconnections
(
signal:
RBXScriptSignal
--
The signal instance (e.g., game.Players.PlayerAdded
) to get connections from.
) →
{
Connection
}
--
An array-like table containing Connection
objects for each active connection to the signal.
Retrieves a list of connection objects associated with a given signal.
Usage
This function allows you to inspect and manage individual connections to a signal. You can check properties like the connected function, its thread, whether it's enabled, or even manually fire, defer, enable, disable, or disconnect specific connections.
Remarks
- Calling
Disconnect
on aConnection
object invalidates it. Subsequent attempts to use the object will result in an error. Fire
andDefer
methods will not work for connections whereForeignState
is true (i.e., C functions or connections from different Luau VMs).- The order of connections in the returned table might not be predictable.
Errors
Type | Description |
---|---|
Expected RBXScriptSignal | The provided argument was not an `RBXScriptSignal`. |
connection cannot be obtained | An internal error occurred while trying to access the connection list. |