Instance

Instance : InstanceBase

Overview

Instance는 Workspace, ReplicatedStorage, ServerStorage 등 DataModel 트리에 속할 수 있는 모든 객체의 최상위 기본 클래스입니다.

Instance.new() 생성자를 사용하면 Part, ParticleEmitter 등 지정한 객체를 런타임에서 동적으로 생성할 수 있습니다. 단, 최상위 Instance 객체는 직접 생성할 수 없습니다.

Properties

Parent

Instance

Parent 속성은 현재 인스턴스가 계층 구조상 어느 위치에 속하는지를 결정하는 핵심 속성입니다.

이 속성은 GetChildren(), FindFirstChild() 등과 같은 구조 탐색 메서드의 기반이 됩니다.

부모 객체에 Destroy()를 호출하면 해당 부모와 그 하위 모든 객체의 Parent가 nil로 설정되고, 이후 Parent 속성을 변경할 수 없게 됩니다.

Clone()이나 Instance.new()로 새로 생성된 객체는 기본적으로 Parent가 nil인 상태로 만들어집니다. 이 상태에서는 화면에 표시되지 않거나 동작하지 않으며, Parent가 지정된 이후에야 기능하거나 보이게 됩니다.

서버에서 생성된 객체는 복제(Replication) 가능한 계층에 Parent로 연결되기 전까지 클라이언트로 전송되지 않습니다. 객체를 만들고 여러 속성을 설정하는 경우, Parent 속성을 마지막에 지정하는 것이 권장됩니다.

Code Samples

local Part = Instance.new("Part")
local Workspace = game:GetService("Workspace")

Part.Parent = Workspace
print(Part.Parent)

Archivable

bool

현재 지원되지 않습니다.

Code Samples

ClassName

string

현재 인스턴스가 속한 클래스를 문자열로 나타내는 읽기 전용 속성입니다.

해당 객체의 클래스를 직접 확인하는 데 유용하며, 상속 관계를 포함한 타입 판별이 필요할 경우에는 IsA() 메서드를 사용하는 것이 좋습니다.

Code Samples

local Part = script.Parent

print(Part.ClassName)

Name

string

인스턴스의 이름을 지정하는 속성입니다.

이 이름은 계층 구조 내에서 인스턴스를 구별하고 정리하는 데 사용되며, 스크립트를 통해 해당 객체를 참조할 때도 활용됩니다.

스크립트에서 점(.) 연산자로 객체에 접근하려면 이름이 반드시 문자 또는 밑줄(_)로 시작해야 하며, 이후에는 문자, 숫자, 밑줄만 사용할 수 있습니다. 이 규칙을 따르지 않으면 점 표기법으로 접근할 수 없습니다.

같은 계층에 동일한 이름의 객체가 존재하면, 해당 이름으로 접근 시 하나의 객체만 반환되며, 이는 원하는 대상이 아닐 수 있습니다. 따라서 특정 객체를 정확히 참조하려면 고유한 이름을 지정하고 중복을 피하는 것이 안전합니다.

Code Samples

local Part = script.Parent

Part.Name = "NewPart"

ClientOnlyAttributes

InstanceAttributeArray

{Description Slot}

Code Samples

PendingAttributes

InstanceAttributeArray

{Description Slot}

Code Samples

EnabledMobility

bool

{Description Slot}

Code Samples

Methods

Clone

지정된 인스턴스와 그 하위 모든 요소를 복제하여, 최상위 복제본 인스턴스를 반환합니다.

반환된 인스턴스의 Parent 속성은 nil로 설정됩니다.

Parameters

Return

Instance	복제된 인스턴스입니다.

Code Samples

local Workspace = game:GetService("Workspace")
local Part = Workspace.Part

local NewPart = Part:Clone()
NewPart.Position = Part.Position + Vector3.new(300, 0, 0)
NewPart.Parent = Workspace

Destroy

지정된 인스턴스와 그 하위 모든 객체에 Destroy()를 호출하여 완전히 제거합니다.

Destroy()가 실행된 인스턴스는 Parent 속성이 잠겨 재사용할 수 없으므로, 객체를 완전히 삭제하지 않고 임시로 제거하려면 Parent를 nil로 설정하면 됩니다.

이 메서드는 불필요한 객체를 정리하는 데 사용하는 핵심 방법으로, 모든 이벤트 연결을 해제하고 사용하지 않는 객체를 제거하여 메모리 누수와 장기적인 성능 저하를 효과적으로 방지합니다.

Destroy() 호출 후에는 해당 객체 또는 하위 요소를 참조하는 변수를 반드시 nil로 초기화하여, 코드에서 이미 삭제된 객체에 접근하는 상황을 예방하는 것이 좋습니다.

Parameters

Return

void

Code Samples

local Workspace = game:GetService("Workspace")
local Part = Workspace.Part

Part:Destroy()

FindFirstAncestor

지정된 인스턴스의 상위 계층을 따라 올라가면서, 지정한 이름과 동일한 이름을 가진 가진 첫 번째 상위 인스턴스를 반환합니다.

탐색은 현재 인스턴스의 Parent부터 시작해 DataModel까지 진행되며, 조건에 맞는 객체가 없으면 nil이 반환됩니다.

Parameters

string InName	탐색할 상위 인스턴스의 이름입니다.

Return

Instance	탐색된 인스턴스입니다.

Code Samples

local Part = script.Parent

local Ancestor = Part:FindFirstAncestor("ParentPart")
print(Ancestor)

FindFirstAncestorOfClass

지정된 인스턴스의 상위 계층을 따라 올라가면서, 지정한 클래스 이름과 동일한 이름을 가진 가진 첫 번째 상위 인스턴스를 반환합니다.

탐색은 현재 인스턴스의 Parent부터 시작해 DataModel까지 진행되며, 조건에 맞는 객체가 없으면 nil이 반환됩니다.

주로 BasePart가 포함된 Model을 찾을 때 유용하게 쓰입니다.

Parameters

string InClassName	탐색할 상위 인스턴스의 클래스 이름입니다.

Return

Instance	탐색된 인스턴스입니다.

Code Samples

local Part = script.Parent

local AncestorOfClass = Part:FindFirstAncestorOfClass("Model")
print(AncestorOfClass)

FindFirstAncestorWhichIsA

지정된 인스턴스의 상위 계층을 따라 올라가면서, 지정한 클래스 이름에 대해 Object:IsA()의 검사 결과가 true인 첫 번째 상위 인스턴스를 반환합니다.

Instance:FindFirstAncestorOfClass()가 클래스 이름을 정확히 비교하는 반면, 이 메서드는 상속 관계를 고려하므로 MeshPart, Part처럼 BasePart를 상속한 객체라면 모두 탐색 대상이 됩니다.

탐색은 현재 인스턴스의 Parent부터 시작해 DataModel까지 진행되며, 조건에 맞는 객체가 없으면 nil이 반환됩니다.

Parameters

string InClassName	탐색할 상위 인스턴스의 클래스 이름입니다.

Return

Instance	탐색된 인스턴스입니다.

Code Samples

local Part = script.Parent

local AncestorWhichIsA = Part:FindFirstAncestorWhichIsA("BasePart")
print(AncestorWhichIsA)

FindFirstChild

지정한 이름의 첫 번째 자식 인스턴스를 반환하며, 해당 이름의 자식이 없으면 nil을 반환합니다.

recursive 값을 true로 설정하면 직접적인 자식뿐 아니라 모든 하위 계층까지 검색할 수 있습니다.

점(.) 표기법으로 자식을 참조할 때 해당 객체가 존재하지 않으면 오류가 발생하지만, FindFirstChild()를 사용하면 오류 없이 안전하게 존재 여부를 확인할 수 있습니다. 이를 활용하면 특정 Part를 찾기 전에 FindFirstChild()로 존재 여부를 먼저 검사하고, if 조건문을 통해 필요한 코드를 실행할 수 있어 보다 안전합니다.

다만 FindFirstChild()는 점(.) 표기법보다 속도가 느리므로, 성능이 중요한 반복문이나 RunService 이벤트에 연결된 함수에서는 직접 호출을 피하고 결과를 변수에 저장하여 사용하는 것이 권장됩니다.

Parameters

string InName	탐색할 하위 인스턴스의 이름입니다.
bool recursive	하위 모든 자식까지 검색할지 여부를 지정하는 옵션입니다. (기본값: false)

Return

Instance	탐색된 인스턴스입니다.

Code Samples

local Workspace = game:GetService("Workspace")

local Part = Workspace:FindFirstChild("Part")
print(Part)

FindFirstChildOfClass

지정된 인스턴스의 자식 중 클래스 이름이 지정한 값과 정확히 일치하는 첫 번째 객체를 반환하며, 조건을 만족하는 자식이 없으면 nil을 반환합니다.

Parameters

string InClassName	탐색할 하위 인스턴스의 클래스 이름입니다.
bool recursive	하위 모든 자식까지 검색할지 여부를 지정하는 옵션입니다. (기본값: false)

Return

Instance	탐색된 인스턴스입니다.

Code Samples

local Workspace = game:GetService("Workspace")

local Part = Workspace:FindFirstChildOfClass("Part")
print(Part)

GetAttribute

인스턴스에서 지정한 속성 이름에 해당하는 값을 반환하며, 해당 속성이 없으면 nil을 반환합니다.

SetAttribute()를 사용하면 속성 이름과 값을 지정하여 설정할 수 있고, GetAttributes()를 사용하면 인스턴스의 모든 속성과 값을 딕셔너리 형태로 가져올 수 있습니다.

Parameters

string attribute	확인할 속성 이름입니다.

Return

Value	해당 속성에 할당된 값입니다.

Code Samples

local AttributeName = "Number"
local SetValue = 1
Part:SetAttribute(AttributeName, SetValue)

local GetValue = Part:GetAttribute(AttributeName)
print(GetValue)

GetAttributes

인스턴스에 설정된 모든 속성을 키-값 쌍 형태의 딕셔너리로 반환합니다.

이 메서드를 사용하면 인스턴스가 가진 모든 속성과 그 값을 한 번에 확인할 수 있습니다.

Parameters

Return

Dictionary	속성의 이름과 값으로 구성된 딕셔너리입니다.

Code Samples

Part:SetAttribute("Number", 1)
Part:SetAttribute("Text", "Hello")

local AttributeList = Part:GetAttributes()
for attributeName, attributeValue in pairs(AttributeList) do
    print(attributeName, " : ", attributeValue)
end

GetAttributeChangedSignal

모든 속성 변화를 감지하는 AttributeChanged 이벤트와 달리, 이 메서드는 지정한 속성이 변경될 때만 동작하는 이벤트를 반환합니다.

Parameters

string InAttributeName	값 변화를 감지할 속성의 이름입니다.

Return

ScriptSignal	실행된 이벤트입니다.

Code Samples

local Object = script.Parent

Object:GetAttributeChangedSignal("SomeEvent"):Connect(function()
    print("Attribute Changed!")
end)

Object:SetAttribute("SomeEvent","test")

GetChildren

지정된 객체를 부모로 가지는 모든 직접 자식을 배열 형태로 반환합니다.

반환된 배열은 숫자 인덱스를 가지며, 일반 for 루프나 숫자 for 루프를 사용해 순회할 수 있고 배열 내 자식들의 순서는 Parent 속성이 이 객체로 설정된 순서에 따라 정해집니다.

모든 하위 요소를 가져오려면 GetDescendants() 메서드를 사용하면 됩니다.

Parameters

Return

Array	자식 인스턴스로 구성된 배열입니다.

Code Samples

local Workspace = game:GetService("Workspace")

local Children = Workspace:GetChildren() 
for _, child in ipairs(Children) do
    print(child.Name)
end

GetChildrenNum

지정된 객체를 부모로 가지는 모든 직접 자식의 수를 반환합니다.

Parameters

Return

number	자식 인스턴스의 수입니다.

Code Samples

local Object = script.Parent

print(Object:GetChildrenNum())

GetDescendants

지정된 객체의 모든 하위 계층을 배열 형태로 반환합니다.

GetChildren()이 하위에 있는 직접적인 자식만 가져오는 것과 달리, 이 메서드는 자식뿐 아니라 그 하위 요소까지 모두 검색하여 포함합니다.

Parameters

Return

array	자식 인스턴스의 하위 항목을 모두 포함한 배열입니다.

Code Samples

local Workspace = game:GetService("Workspace")

local Descendants = Workspace:GetDescendants()
for _, descendant in ipairs(Descendants) do
    print(descendant.Name)
end

IsDescendantOf

현재 인스턴스가 지정된 상위 객체의 하위 계층에 포함되어 있으면 true를 반환합니다.

Parameters

Instance InAncestor	확인할 조상 인스턴스입니다.

Return

bool	조상의 하위 계층에 포함되어 있는지 여부입니다.

Code Samples

local Workspace = script.Parent.Parent
local Part = script.Parent
local IsDescendantOf = script:IsDescendantOf(Workspace)

print(IsDescendantOf)

IsA

현재 인스턴스가 지정된 클래스이거나 해당 클래스를 상속받은 경우 true를 반환합니다.

이 메서드는 특히 객체가 특정 파트 계열에 속하는지 판별할 때 유용합니다. 예를 들어, Part나 MeshPart처럼 BasePart를 상속받은 객체인지 확인하려면 GetChildren()으로 모든 자식을 가져온 뒤 IsA()로 검사할 수 있습니다.

상속 관계를 포함한 타입 판별에 적합하며, 상속 관계를 무시하려면 ClassName 속성으로 직접 비교하는 것이 좋습니다.

또한 number나 string과 같은 Luau 기본 데이터 타입은 type() 또는 typeof() 함수를 사용해 확인해야합니다.

Parameters

string InClassName	탐색할 클래스 이름입니다.

Return

bool	포함 여부입니다.

Code Samples

local Part = script.Parent

print("Instance : ", Part:IsA("Instance")) -- true
print("Part : ", Part:IsA("BasePart"))     -- true
print("BasePart : ", Part:IsA("BasePart")) -- true
print("MeshPart : ", Part:IsA("MeshPart")) -- false

if Part:IsA("Part") then
    print("Part")
else
    
end

SetAttribute

현재 인스턴스에 지정한 이름의 속성 값을 설정합니다.

속성 이름에는 영문자, 숫자, 밑줄(_)만 사용할 수 있으며, 공백이나 특수문자는 허용되지 않고, 값이 nil로 주어지면 해당 속성은 삭제됩니다.

string, number, boolean 같은 Luau의 기본 데이터 타입뿐 아니라 Instance, CFrame 등 다양한 타입을 지원하지만, 지원되지 않는 타입으로 속성을 설정하면 오류가 발생합니다.

서버에서 설정한 값은 클라이언트로 자동 복제되며, 이를 활용하면 RemoteEvent를 사용하지 않고도 스크립트 간 통신이 가능합니다.

Attribute는 Value 오브젝트처럼 별도의 인스턴스를 생성하거나 파괴하지 않으므로 Instance.new()나 Destroy()에 비해 훨씬 빠르게 처리되며, 특히 다수의 오브젝트에 값을 동적으로 생성하거나 제거해야 하는 상황과 같이 고빈도 처리, 대량 오브젝트 제어, 반복적인 동기화가 필요한 경우에 유리합니다.

특정 이름의 속성을 가져오려면 GetAttribute()를, 모든 속성을 가져오려면 GetAttributes()를 사용하면 됩니다.

Parameters

string attribute	설정할 속성의 이름입니다.
Value value	할당할 값입니다.

Return

void

Code Samples

local AttributeName = "Number"
local SetValue = 1
Part:SetAttribute(AttributeName, SetValue)

WaitForChild

지정한 이름의 자식 인스턴스를 반환하며, 존재하지 않으면 해당 객체가 생성될 때까지 실행을 일시 중단합니다.

timeOut 값을 지정하면 설정된 시간(초)만 대기한 후, 여전히 해당 자식이 없으면 nil을 반환합니다. timeOut 없이 5초 이상 대기하면 무한 대기 가능성을 알리는 경고 메시지가 출력됩니다.

서버에서 클라이언트로 객체가 전송되는 시점과 순서는 보장되지 않으므로, 로드 순서로 인한 참조 실패를 방지하기 위해 LocalScript에서 클라이언트 측 객체를 다룰 때 필수적으로 사용됩니다.

Parameters

string InChildName	탐색할 하위 인스턴스의 이름입니다.
number InTimeOut	대기할 최대 시간(초)입니다. 생략하면 해당 객체가 존재할 때까지 계속 대기합니다.

Return

Instance	탐색된 인스턴스입니다.

Code Samples

local Workspace = game:GetService("Workspace")

local Part = Workspace:WaitForChild("Part")
print(Part)

AddTag

현재 인스턴스에 지정한 이름의 태그를 추가합니다.

Parameters

FName tag	지정할 태그의 이름입니다.

Return

void

Code Samples

Part:AddTag("SomeTag")

RemoveTag

현재 인스턴스에 지정한 이름의 태그를 삭제하며, 해당 태그가 존재하지 않아도 오류 없이 동작합니다.

Parameters

FName tag	삭제할 태그의 이름입니다.

Return

void

Code Samples

Part:RemoveTag("SomeTag")

HasTag

현재 인스턴스에 지정한 이름의 태그가 추가되어 있으면 true를 반환합니다.

Parameters

FName tag	확인할 태그의 이름입니다.

Return

bool	태그의 존재 여부입니다.

Code Samples

if Part:HasTag("SomeTag") then
    
else
    
end

GetTags

현재 인스턴스에 적용된 태그 목록을 문자열 배열로 반환합니다.

특정 태그만 확인하는 HasTag()와 달리, 인스턴스에 적용된 모든 태그를 조회할 때 적합합니다.

Parameters

Return

Array	문자열로 구성된 배열입니다.

Code Samples

Part:AddTag("SomeTag")

local Tags = Part:GetTags()
for i = 1, #Tags do
    print(Tags[i])
end

Events

AncestryChanged

현재 인스턴스 또는 상위 인스턴스의 Parent 속성이 변경될 때 실행되는 이벤트입니다.

하위 인스턴스의 Parent 속성이 변경될 때는 실행되지 않습니다.

Parameters

Instance child	Parent 속성이 변경된 인스턴스입니다.
Instance parent	변경된 Parent 값입니다.

Code Samples

local Part = Instance.new("Part")

local function OnAncestryChanged(child, parent)
    print(child, "Ancestry Changed:", parent)
end
Part.AncestryChanged:Connect(OnAncestryChanged)

wait(2)
Part.Parent = game.Workspace

AttributeChanged

현재 인스턴스에서 속성이 변경될 때마다 실행되는 이벤트로, 속성이 nil로 설정되는 경우도 감지합니다.

지정한 속성만 감지하는 GetAttributeChangedSignal()와 달리 모든 속성 변화를 감지하며, 이벤트가 실행되면 변경된 속성의 이름이 연결된 함수로 전달됩니다.

Parameters

string attribute	변경된 속성의 이름입니다.

Code Samples

local Part = script.Parent

local function OnAttributeChanged(attribute)
    print(attribute, "Changed:", Part:GetAttribute(attribute))
end
Part.AttributeChanged:Connect(OnAttributeChanged)

wait(2)
Part:SetAttribute("Color", "Blue")

Changed

현재 인스턴스에서 프로퍼티가 변경될 때마다 실행되는 이벤트입니다.

변경된 값은 object[property] 형태로 직접 조회할 수 있습니다.

주로 스크립트에 의한 프로퍼티 변화를 감지하는 데 사용되며, 물리 엔진에 의해 CFrame이나 Position 등이 변경되는 경우에는 실행되지 않습니다.

또한 변경 주기가 매우 짧은 속성은 일부 변경을 감지하지 못하거나 이벤트가 발생하지 않을 수 있으므로, 게임 로직에서 중요한 속성인 경우, 직접 조회를 통해 동작을 충분히 검증하는 것이 좋습니다.

Parameters

string property	변경된 프로퍼티의 이름입니다.

Code Samples

local Part = script.Parent

local function OnChanged(property)
    print(property, "Changed:", Part[property])
end
Part.Changed:Connect(OnChanged)

wait(2)
Part.Name = "MyPart"

ChildAdded

해당 인스턴스에 자식 인스턴스가 추가될 때 실행되는 이벤트입니다.

이 이벤트는 직접적인 자식만 감지하며, 전체 하위 계층의 추가를 감지하려면 DescendantAdded 이벤트를 사용해야 합니다.

또한 서버에서 생성된 객체를 클라이언트에서 감지하는 경우, 해당 객체의 하위 요소를 다룰 때는 반드시 WaitForChild()를 사용해야 합니다. 이는 서버와 클라이언트 간 동기화 시 객체와 그 하위 요소가 동시에 전송된다는 보장이 없기 때문입니다.

Parameters

Instance child	추가된 자식 인스턴스의 이름입니다.

Code Samples

local Part = script.Parent

local function OnChildAdded(child)
    print("Child Added:", child)
end
Part.ChildAdded:Connect(OnChildAdded)

wait(2)
local ChildPart = Instance.new("Part")
ChildPart.Name = "ChildPart"
ChildPart.Parent = Part

ChildRemoved

해당 인스턴스의 자식 인스턴스가 제거될 때 실행되는 이벤트입니다.

자식의 Parent 속성이 다른 인스턴스로 변경되거나, Destroy() 메서드를 호출해 삭제된 경우에도 실행됩니다.

이 이벤트는 직접적인 자식만 감지하며, 전체 하위 계층의 제거를 감지하려면 DescendantRemoving 이벤트를 사용해야 합니다.

Parameters

Instance child	제거된 자식 인스턴스의 이름입니다.

Code Samples

DescendantAdded

해당 인스턴스에 자손 인스턴스가 추가될 때 실행되는 이벤트입니다.

이 이벤트는 모든 자손 객체에 대해 실행되므로, 어떤 객체를 인스턴스의 자식으로 배치하면 그 객체뿐 아니라 그 객체가 포함하는 모든 하위 객체에 대해 개별적으로 이벤트가 발생합니다.

직접적인 자식만 감지하려면 ChildAdded 이벤트를 사용하세요.

Parameters

Instance descendant	추가된 자손 인스턴스의 이름입니다.

Code Samples

local Part = script.Parent

local function OnDescendantAdded(descendant)
    print("Descendant Added:", descendant)
end
Part.DescendantAdded:Connect(OnDescendantAdded)

wait(2)
local ChildPart = Instance.new("Part")
ChildPart.Name = "ChildPart"
ChildPart.Parent = Part

DescendantRemoving

해당 인스턴스의 자손 인스턴스가 제거되기 직전에 실행되는 이벤트입니다.

자손의 Parent 속성이 다른 인스턴스로 변경되거나, Destroy() 메서드를 호출해 삭제된 경우에도 실행됩니다.

이 이벤트는 모든 하위 계층에 대해 개별적으로 실행되므로, 어떤 객체가 제거될 때 그 객체뿐 아니라 그 객체의 모든 하위 객체에 대해서도 순차적으로 호출됩니다. 만약 제거되는 객체가 직속 자식이라면, 이 이벤트는 ChildRemoved 이벤트보다 먼저 실행됩니다.

이 시점에서는 자손의 부모 속성이 아직 변경되지 않은 상태이며, Parent를 다른 인스턴스로 변경하는 것은 불가능합니다.

직접적인 자식만 감지하려면 ChildRemoved 이벤트를 사용하세요.

Parameters

Instance descendant	제거된 자손 인스턴스의 이름입니다.

Code Samples

Destroying

해당 인스턴스가 Destroy() 메서드에 의해 삭제될 때 실행되는 이벤트입니다.

이벤트에 연결된 콜백 함수가 인스턴스를 참조하고 있는 동안에는 해당 인스턴스가 메모리에서 해제되지 않으므로, 안전하게 객체에 접근할 수 있습니다.

Parameters

Code Samples

local Part = script.Parent

local function OnDestroying()
    print(Part, "is being destroyed.")
end
Part.Destroying:Connect(OnDestroying)

wait(2)
Part:Destroy()