Skip to Content
Kinemium

Object

The root class for engine objects, with shared identity, metadata, hierarchy, and lifecycle APIs.

Object is the root of Kinemium's class hierarchy. An Instance is an Object, but not every Object is necessarily an Instance. Classes that derive directly from Object, such as EditableMesh, do not have to inherit from Instance.

The shared object API gives you a consistent way to identify objects, organize them, attach metadata, and manage their lifetime. You don't need to work with the engine's implementation to use it.

Working with objects

When a function receives an engine object, you can inspect its class without knowing its exact type beforehand.

local function describe(object)
    print(object.Name, object.ClassName)
    print(object:GetFullName())

    if object:IsA("Instance") then
        print("This object inherits from Instance")
    end
end

These examples take an object you've already obtained. A standalone constructor for Object is not established by this API.

Properties

Identity and hierarchy

PropertyTypeAccessDescription
NamestringRead/writeThe object's name. The base default is "Object"; subclasses can supply their own.
ClassNamestringRead-onlyThe object's actual class name, not its parent class.
ParentObject?Read/writeThe immediate parent, or nil when detached.
ArchivablebooleanRead/writeWhether the object can be cloned. Defaults to true.
UniqueIdUniqueIdRead-onlyAn identity assigned when the object is created.

Replication and security

PropertyTypeAccessDescription
CanReplicatebooleanRead/writeWhether the object is marked as eligible for replication. Defaults to true.
ReplicationGroupstringRead/writeThe object's replication group. Defaults to an empty string.
ReplicationModeEnum.ReplicationModeRead/writeThe replication mode.
NetworkIdnumberRead-onlyThe assigned numeric network ID. Initially 0.
CapabilitiesSecurityCapabilitiesRestricted writeThe object's security capabilities. Only authorized internal scripts can change this.
SandboxedbooleanRestricted writeWhether the object itself is marked as sandboxed. Defaults to false. Only authorized internal scripts can change this.
IsInSandboxbooleanRead-onlyWhether the object or any of its ancestors is marked as sandboxed.

Replication settings do not by themselves promise that an object is sent to a client. The available replication modes and their network behavior are outside the scope of this reference.

Methods

Signatures describe the shared Luau object API. A return type of () means the method doesn't return a value.

Identity and hierarchy

SignatureDescription
IsA(className: string): booleanChecks the object's class and its inherited classes.
IsAncestorOf(descendant: Object): booleanChecks whether the supplied object is below this object.
IsDescendantOf(ancestor: Object): booleanChecks whether the supplied object is above this object.
GetFullName(): stringReturns the object's dot-separated name path.
GetChildren(): {Object}Returns the accessible direct children in a new array.
GetDescendants(): {Object}Returns the accessible descendants in a new array, in depth-first order.
GetProperties(): {string}Returns registered property names, including inherited properties, rather than their values.

An object isn't considered its own ancestor or descendant. GetFullName() is useful for debugging, but names need not be unique and the path can change when an object is renamed or reparented.

Finding objects

SignatureDescription
FindFirstChild(name: string, recursive: boolean?): Object?Finds a child by name. With recursive set to true, searches descendants if no direct child matches.
FindFirstChildOfClass(className: string): Object?Finds the first direct child whose class matches or inherits from the requested class.
FindFirstChildWhichIsA(className: string, recursive: boolean?): Object?Finds a child by class or inheritance, optionally searching descendants.
FindFirstAncestor(name: string): Object?Searches upward for the nearest ancestor with the given name.
FindFirstAncestorOfClass(className: string): Object?Searches upward for an ancestor whose class matches or inherits from the requested class.
FindFirstAncestorWhichIsA(className: string): Object?Searches upward for an ancestor with exactly the requested class name in the current implementation.
WaitForChild(name: string, timeout: number?): Object?Checks for a direct child by name. See the limitation below.
WaitForChildOfClass(className: string, timeout: number?): Object?Checks for a direct child by class or inheritance. See the limitation below.

Searches return nil when no matching accessible object can be returned. Recursive searches default to false and check direct children first. The current OfClass and WhichIsA behavior is not interchangeable for ancestor searches.

Both WaitForChild methods default to a timeout of 10, but currently poll without yielding or measuring real elapsed time. They can return immediately or consume CPU instead of waiting for future children. Don't rely on them to synchronize asynchronous creation; observe ChildAdded instead.

Lifecycle

SignatureDescription
Clone(): Object?Copies the object and its archivable descendants. Returns nil if the object isn't archivable or cloning fails.
Destroy(): ()Destroys the object and its descendants and detaches them from the hierarchy.
ClearAllChildren(): ()Destroys accessible direct children and their descendants while preserving this object.

A clone has its own identity and starts without a parent. Attributes and tags are copied; non-archivable descendants and their subtrees are skipped. Class-specific state depends on the class's supported cloning behavior.

Attributes

Attributes let you store small pieces of custom data without creating extra child objects.

SignatureDescription
GetAttribute(name: string): anyReturns the stored value, or nil if the attribute doesn't exist.
GetAttributes(): { [string]: any }Returns a new table containing all attribute names and values.
SetAttribute(name: string, value: any): ()Creates or replaces an attribute. Pass nil to remove it.

Attribute names must be 1–100 characters long and can contain ASCII letters, digits, underscores, hyphens, periods, and slashes. Names beginning with RBX (regardless of case) are reserved.

Supported values include booleans, numbers, strings, vectors, and registered engine datatypes. Ordinary tables, functions, and engine object references are not supported. An invalid name or unsupported value raises an error.

local function configure(object)
    object:SetAttribute("Health", 100)
    object:SetAttribute("Team", "Blue")

    local health = object:GetAttribute("Health")
    print(health)

    object:SetAttribute("Team", nil)
end

Changing an attribute does not directly fire the shared property-change signals. Attributes aren't regular class properties.

Tags

Tags are string labels you can attach to objects to identify a category or behavior.

SignatureDescription
AddTag(tag: string): ()Adds a tag if it isn't already present.
RemoveTag(tag: string): ()Removes a tag if present.
HasTag(tag: string): booleanChecks whether the tag is attached.
GetTags(): {string}Returns a new array of attached tags.

Tag names must be 1–100 characters long and cannot contain NUL bytes. Adding a duplicate or removing a missing tag has no effect.

local function markInteractable(object)
    object:AddTag("Interactable")
    print(object:HasTag("Interactable")) -- true
end

GetPropertyChangedSignal

GetPropertyChangedSignal(property: string): signal?

Returns a signal for the named property. Its callback receives no arguments, so read the property inside the callback. The signal can be nil if it cannot be created. The name isn't validated against the class's property list by this method.

local function watchName(object)
    local signal = object:GetPropertyChangedSignal("Name")
    if signal then
        signal:Connect(function()
            print(object.Name)
        end)
    end
end

Events

Connect to these events to respond to changes without repeatedly searching the object tree.

EventCallback argumentsWhen it fires
Changedproperty: stringA property-change notification is emitted.
ChildAddedchild: ObjectA direct child is attached.
ChildRemovedchild: ObjectA direct child is detached.
DescendantAddeddescendant: ObjectAn object is attached beneath this object.
DescendantRemovingdescendant: ObjectAn object is detached from beneath this object.
AncestryChangedobject: Object, parent: Object?This object's direct parent changes.
DestroyingNoneDestruction begins, before the object is detached.

Hierarchy events describe the current implementation: during a reparent operation the parent change has already been applied when removal notifications fire. Moving a whole subtree does not automatically emit a separate event for every nested descendant, and AncestryChanged is emitted for the moved object itself, not every descendant.

Changed and property-specific signals describe notifications, not a guarantee that every runtime or metadata change emits one.

See also

  • Instance, organizing objects, managing children, and using common inherited members.
  • GuiObject, positioning and interacting with GUI elements.

On this page