Instances¶

An Instance is Luduvo's slight spin on an ECS entity. As with normal ECS entities, Instances holds assets and game objects that interact directly with the engine rather than only with other scripts.

Similarly to an entity, an Instance is still largely defined by the Components attached to them. However, Luduvo Instances also take a more OOP approach to their design and bundle many operations and helper functions into the Instance as methods and properties that can be called directly on the Instance itself.

Obtaining Instances¶

From Existing Instances¶

There are several ways to get existing Instances in Luduvo. If you don't have a reference to an instance already, you can use the following methods:

• game.World.Each and, by extension, its Query counterpart for getting Instances based on their Components
• Script handles and the global self parenting for getting instances hand-made in the editor

If you already have a reference to an Instance, you can use its hierarchy-related methods and properties to find other Instances through its parent or child relationships:

• Instance.Parent, which returns the Instance that the current Instance is nested under
• Instance:FindFirstChild, which returns the first child Instance with the given name
• Instance:GetChildren, which returns all nested Instances of the called Instance
• Instance:IsDescendantOf, which checks whether the called Instance is a descendant of the given ancestor Instance

More details on these methods and properties can be found in the reference.

From New Instances¶

As of writing, there is no Instance.new() constructor that lets you create a blank entity directly. Instead, Instances must be created through these routes:

• Make the Instance through the Editor
• game.Prefabs.Spawn to spawn a premade Instance from a Luduvo object file
• Instance:Clone() to duplicate an existing Instance

Cloning¶

Clone() makes a new Instance with identical values to the source Instance wherever possible.

local copy = self:Clone()
copy.Parent = self.Parent --(1)!

1. self:Clone() only creates the Instance. To be visible in the engine, it still needs to be parented to the World hierarchy.

Native metadata exposes Clone to both server and client scripts and its implementation has no direct server check. Client execution has not been confirmed in a live test; if it succeeds, the result is local rather than automatically replicated.

Component Management¶

Instances come built in with methods for managing Components:

instance:AddComponent(name: string) -> ()
instance:RemoveComponent(name: string) -> ()
instance:HasComponent(name: string) -> boolean

As you might expect, AddComponent() adds a component to the Instance, RemoveComponent() removes it, and HasComponent() checks whether the given component is attached to the Instance. All 3 methods take a string name parameter, which requires the (case sensitive) name of the component you are looking to manage.

A full list of available components can be found in the Component reference.

These methods work differently depending on where they are called:

• Only server scripts can add or remove replicated and server-only components. Changes to replicated components are replicated to all clients.
• A client script can change only client-only components, but those changes stay local to that client's World.
• If a client attempts to write to a replicated component, Luduvo rejects it with '<name>' is replicated; only server scripts may write it.

Queries are not the only way to access component values. Fixed properties above expose selected built-ins. Platform custom components expose nested field proxies:

self.PlayerSpawner.character = "Character"
self.PlayerSpawner.respawnDelay = 3

self.Tool.equipped = 1 --(1)! 

Attributes¶

Currently, you cannot create your own components. However, if you need to store custom data on an Instance, you can still do so through the use of Attributes:

self.attr.Speed = 3
print(self.attr.Speed)

Attributes are a key-value dictionary for storing custom data on an Instance stored in a attr field. They act exactly like regular Lua tables, which means you can create, read, and modify them using standard table operations.

The only exception is that you cannot directly print the entire attr table through print(self.attr). Instead, you can use game.World.DumpAttributes(Instance):

game.World.DumpAttributes(self)

Replication rules still apply to attributes, so clients cannot write Attributes on a server-owned or replicated Instance.

Signals¶

Signals are Luduvo's equivalent of BindableEvents/RBXScriptSignals, or some other game engine's "hook" event equivalent. Luduvo uses them internally to hook scripts into engine events, but they can also be created by you directly:

local damaged = self:GetSignal("Damaged")

damaged:Connect(function(amount, source)
    print(amount, source)
end)

damaged:Emit(10, self)
self:Emit("Damaged", 10, self) -- equivalent after GetSignal registered the name

GetSignal() is the only discovered way to create a signal, so custom signals are tied to Instances.

Emitting Signals¶

Once a signal is attached to an instance, it can be fired using Signal:Emit(...args: any), and you can connect listeners to run callback functions on successful emission using Signal:Connect(callback: (...args: any) -> ()).

The arguments supplied to Signal:Emit() are passed directly to the signal's connected listeners.

Signal connections and emissions are completely local to where they are created, so they will not be replicated to other clients or the server. If the server emits a signal on an Instance that is replicated to and seen by other clients, only the server's handlers will run. If a client emits a signal on an Instance that multiple clients and the server can see, only that client's handlers will run.

Built-in Signals¶

• Instance.Changed:Connect(), which does nothing
• Instance.ChildAdded:Connect(child: Instance), which fires when an Instance is reparented to this Instance via Instance.Parent. The child argument is the Instance being reparented to it.
• Instance.ChildRemoved:Connect(child: Instance), which fires when a child is reparented to another Instance or nil via Instance.Parent. The child argument is the Instance leaving the hierarchy.
• Instance.Activated:Connect(activator: Instance), which fires when the Instance is clicked on. This signal is only relevant to UI Instances that have the UIClickable component attached to them. UIs with the UIDisabled component attached will be ignored and not trigger Activated.

Currently, the Emit method will work on ANY signal, even if the Signal is supposed to be managed by Luduvo itself.

Alongside signal:Emit(), Instances also have Instance:Emit(name: string, ...args: any) that can be used to fire any signal by name you gave it when running Instance:GetSignal().

Reference¶

World Hierarchy¶

Properties¶

type Kind = "Part" | "ScreenGui"

Methods¶

Appearance¶

Properties¶

Methods¶

Physics and gameplay¶

type SwingTwistJoint = {
    Anchor: vector,
    TwistAxis: vector,
    PlaneAxis: vector,
    RestAxis: vector,
    PlaneCone: number,
    NormalCone: number,
    TwistMin: number,
    TwistMax: number,
    Friction: number,
}

Properties¶

Methods¶

Signal properties¶

User Data¶

type IdentityResult = {
    userId: number,
    displayName: string,
    isAdmin: boolean,
}

type MoveIntent = {
    x: number,
    z: number,
    jump: boolean,
    shiftLock: boolean,
    targetYaw: number,
}

Properties¶

Methods¶

Signal properties¶

Animation¶

type AnimationPreviewState = {
    clip: string,
    time: number,
    speed: number,
    playing: boolean,
    shared: boolean,
}

Methods¶