Open Asterune
Component

Component

Provides component field constructors and a registered component's runtime interface.

Behavior

Component provides component field constructors and a registered component's runtime interface.

Summary

Constructors17
Functions17
Members8
Properties2
  • Name: stringread only

    The registered component name, taken from its ComponentDefinition instance.

  • Version: numberread only

    The schema version declared in Component.define options.

Methods3
  • GetFields(): table

    Returns field metadata in declaration order.

  • GetInstances(): table

    Returns the Instances carrying this component.

  • SetMigration(migrate: ((saved: { [string]: any }, fromVersion: number, instance: Instance) -> { [string]: any }?)?): ()

    Registers migrate(saved, fromVersion, instance) for rows saved under an older schema version.

Events3
  • Added: RBXScriptSignalread only

    Fires with (instance, handle) when the component is added to an Instance.

  • Changed: RBXScriptSignalread only

    Fires with (instance, fieldName) when a component field changes.

  • Removed: RBXScriptSignalread only

    Fires with (instance) when the component is removed.

Constructors

boolean

Component.boolean(default: boolean?, options: ComponentFieldOptions?): ComponentField

Declares a boolean field. The default is false. Options are doc and renamedFrom.

buffer

Component.buffer(options: ComponentBufferOptions?): ComponentField

Declares a binary buffer field. maxBytes defaults to 4096 and is capped at 1048576. The default is an empty buffer.

cframe

Component.cframe(default: CFrame?, options: ComponentFieldOptions?): ComponentField

Declares a CFrame field. The default is the identity transform.

color

Component.color(default: Color3?, options: ComponentFieldOptions?): ComponentField

Declares a Color3 field. The default is black.

define

Component.define(fields: { [string]: ComponentField }, options: ComponentOptions?): Component

Defines one component schema. The enclosing ComponentDefinition supplies its name. This constructor is available only while evaluating a ComponentDefinition. See Component definitions for schema options.

enum

Component.enum(members: EnumType | { string }, default: (EnumItem | string)?, options: ComponentFieldOptions?): ComponentField

Declares a field restricted to an engine enum or a list of string members. The default must belong to that enum. Duplicate string members are rejected.

integer

Component.integer(default: number?, options: ComponentIntegerOptions?): ComponentField

Declares an integer field. The default is 0. Options include min, max, doc, and renamedFrom. Fractional values are rejected. Runtime assignments are clamped to the declared bounds.

list

Component.list(item: ComponentField, options: ComponentCollectionOptions?): ComponentField

Declares a sequence whose elements match the supplied field descriptor. The default is an empty list. maxItems defaults to 1024 and is capped at 65536.

map

Component.map(key: ComponentField | "string" | "integer", value: ComponentField, options: ComponentCollectionOptions?): ComponentField

Declares a map with string or integer keys and values matching the supplied field descriptor. The default is an empty map. maxItems defaults to 1024 and is capped at 65536.

number

Component.number(default: number?, options: ComponentNumberOptions?): ComponentField

Declares a finite numeric field. The default is 0. Options include min, max, step, doc, and renamedFrom. Runtime assignments are clamped to min and max; step does not quantize them.

optional

Component.optional(inner: ComponentField, options: ComponentCollectionOptions?): ComponentField

Declares a field that accepts nil or the supplied value type. The default is nil. Wrapping another optional field or a reference field is rejected.

ref

Component.ref(…)

Declares an optional Instance reference. Component.ref(className?, options?) restricts references to the named class and its subclasses. The default is nil. onDestroy accepts "clear", "remove", or "destroy"; the default is "clear".

string

Component.string(default: string?, options: ComponentStringOptions?): ComponentField

Declares a string field. The default is an empty string. maxLength defaults to 1024 characters and must be a positive integer.

struct

Component.struct(fields: { [string]: ComponentField }, options: ComponentCollectionOptions?): ComponentField

Declares a record with named, typed fields. At least one field is required. Omitted values use the nested fields' defaults.

udim2

Component.udim2(default: UDim2?, options: ComponentFieldOptions?): ComponentField

Declares a UDim2 field. Both scale and offset components default to zero.

vector2

Component.vector2(default: Vector2?, options: ComponentFieldOptions?): ComponentField

Declares a Vector2 field. The default is Vector2.new(0, 0).

vector3

Component.vector3(default: Vector3?, options: ComponentFieldOptions?): ComponentField

Declares a Vector3 field. The default is Vector3.new(0, 0, 0).

Properties

Name

Component.Name: string

The registered component name, taken from its ComponentDefinition instance.

Version

Component.Version: number

The schema version declared in Component.define options. The initial version is 1.

Methods

GetFields

Component:GetFields(): table

Returns field metadata in declaration order. Each entry includes Name, Type, Default, and Doc, plus type-specific constraints and nested type metadata.

GetInstances

Component:GetInstances(): table

Returns the Instances carrying this component.

SetMigration

Component:SetMigration(migrate: ((saved: { [string]: any }, fromVersion: number, instance: Instance) -> { [string]: any }?)?): ()

Registers migrate(saved, fromVersion, instance) for rows saved under an older schema version. Return a table of replacement field values or nil to retain the automatic migration result. Passing nil unregisters the callback. Registration requires serial execution.

Events

Added

Component.Added: RBXScriptSignal

Fires with (instance, handle) when the component is added to an Instance.

Changed

Component.Changed: RBXScriptSignal

Fires with (instance, fieldName) when a component field changes.

Removed

Component.Removed: RBXScriptSignal

Fires with (instance) when the component is removed.

Operators

__eq · __tostring · __type

Related APIs

ComponentDefinition · ComponentService · ComponentHandle · Query