Instance.new() — Syntax, Example & Use Case

Function syntax

Instance.new(className)

Short summary

Constructs an engine object in a host that provides an Instance factory. This is not part of standard Lua.

Safe code example

-- Engine-host example: requires an injected Instance factory.
local function makeMarker(Instance, parent)
    assert(Instance and parent, "Engine dependencies required")
    local marker = Instance.new("Part")
    marker.Name = "CheckpointMarker"
    marker.Anchored = true
    marker.Parent = parent -- Configure before exposing to the scene.
    return marker
end

Practical game development scenario

Create a stationary checkpoint marker only after its name and physics state have been configured. Use a known class name chosen by the developer; never accept arbitrary construction requests from an untrusted client.

Compatibility and safety notes

Class names, properties, and parent assignment are defined by the host engine. This example is illustrative and will not run in a standalone Lua interpreter.

These examples demonstrate defensive patterns. They are not sandboxing mechanisms or substitutes for permission checks, server-side validation, and resource limits.

Read the official Lua 5.4 reference manual for language semantics. Engine methods require separate host documentation.

← Back to the dictionary

Construct from a trusted specification

Object creation is easier to review when the class and configuration come from developer-controlled data. If players can request a feature, translate that request into a small set of approved construction choices instead of passing arbitrary class names into a factory. Bound the number of objects one operation can create and identify who owns the returned references. This reference example assumes a compatible engine provides the factory and property model. Those dependencies should be explicit in your integration. A successful constructor call does not establish that the object is appropriate for a particular player, scene, or transaction, so keep permission checks in the system that decides when creation is allowed.

Configure before publishing to other systems

A newly created scene object may become visible to other scripts once it is attached to the active hierarchy. Set the properties required for a valid initial state before making that attachment, where your host supports the pattern. Avoid exposing an object whose name, position, or physics behavior will be corrected several steps later. If configuration can fail, keep a reference that allows the owner to clean up the incomplete object. Verify the host's actual lifecycle behavior rather than assuming this pattern suppresses every callback. The purpose is to minimize the interval in which another system can observe a partially configured instance and act on assumptions that are about to change.

Test creation as part of a lifecycle

A useful test does more than check that a reference was returned. Create the object, verify its required initial properties, attach it to the intended owner, and exercise the cleanup path. Repeat the operation several times and confirm that failed attempts do not leave abandoned objects. Consider what happens if the owning scene closes between configuration and attachment. Decide whether the operation should be cancelled or redirected before attempting it. Keep those rules in the integration layer rather than scattering parent assignments throughout unrelated scripts. Construction, ownership, and destruction form one lifecycle, and treating them together makes resource growth easier to understand when a long-running game session behaves differently from a short local test.