Instance System

Understanding Instances

In StarForge, everything is an Instance. Parts, UI elements, scripts, systems - they all inherit from the base Instance class. This creates a unified, tree-structured hierarchy that's easy to work with and reason about.

The Instance Tree

Instances are organized in a parent-child relationship, forming a tree:

Engine
├── World
│   ├── Part (Floor)
│   ├── Part (Wall)
│   └── Player
│       ├── Part (Body)
│       └── Script (Controller)
├── InputSystem
├── UILayer
│   └── UIFrame (HUD)
└── ...

Core Properties

Every Instance has these fundamental properties:

• Name - A string identifier (not necessarily unique)
• Parent - Reference to the parent Instance
• Children - Array of child Instances
• Id - A unique identifier assigned by the engine
• Archivable - Whether the instance can be saved to files

Working with Instances

-- Create a new instance
local part = new("Part")
part.Name = "MyPart"

-- Set parent (adds to tree)
part.Parent = world

-- Access children
for _, child in ipairs(world.Children) do
    print(child.Name)
end

-- Find by name
local floor = world:FindFirstChild("Floor")

-- Destroy (removes from tree)
part:Destroy()

Events

Instances fire events when their state changes:

• Changed(propertyName) - When any property changes
• ChildAdded(child) - When a child is added
• ChildRemoved(child) - When a child is removed
• DescendantAdded(child, parent) - When any descendant is added
• DescendantRemoved(child, parent) - When any descendant is removed

-- Listen for property changes
part.Changed:Connect(function(propName)
    print(propName .. " changed!")
end)

-- Listen for new children
world.ChildAdded:Connect(function(child)
    print("New object: " .. child.Name)
end)