Destroy() — Syntax, Example & Use Case

Function syntax

object:Destroy()

Short summary

Releases an engine object according to the host lifecycle rules. Your own references and external subscriptions still need deliberate cleanup.

Safe code example

local function cleanup(state)
    if state.connection then
        state.connection:Disconnect()
        state.connection = nil
    end
    if state.object then
        state.object:Destroy()
        state.object = nil
    end
end

Practical game development scenario

When a temporary collectible expires, disconnect an external event listener and remove its visual object. Clear your owning reference to avoid accidentally reusing an object that has already been removed.

Compatibility and safety notes

Do not assume destruction clears every reference in your code. Engine cleanup and Lua garbage collection are related but separate lifecycle concerns.

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

Define an idempotent cleanup contract

A cleanup operation is easier to use when calling it again leaves the system in the same cleaned state. Clear owned references after releasing them and check whether optional resources still exist before acting. This does not mean every host method can safely be called repeatedly; the owner should prevent duplicate calls when the host requires it. Document whether cleanup can run after partial initialization. A feature that acquired a listener but failed before creating its visual object still needs to release the listener. Treat that situation as an ordinary lifecycle case instead of writing cleanup that assumes the entire setup path always completed successfully before any resource is removed.

Separate scene removal from other responsibilities

Destroying a visual object does not automatically explain what happens to external subscriptions, timers, pending tasks, or references stored elsewhere in the application. List those resources when designing the owning component. Disconnect or cancel them through the mechanisms your host actually supplies. A delayed callback should also check that its owner remains active before attempting to update a removed object. Keep those checks close to the operation so a future maintainer can see why they exist. Resource cleanup becomes much more predictable when the code describes the complete ownership relationship rather than assuming the scene hierarchy represents every dependency associated with a feature.

Test long sessions and interrupted setup

A temporary object may appear to clean up correctly in a short test while leaving external work behind after repeated use. Exercise the feature many times and observe whether active references, listener counts, or scheduled operations keep growing. Also stop initialization at several points and run the same cleanup path. It should handle the resources actually acquired, not the resources you hoped to acquire. Add a diagnostic identifier for each owner when that helps trace unexpected callbacks. The goal is not to force garbage collection manually whenever something disappears. It is to make the intended lifecycle explicit enough that ordinary references and host-managed resources can be released when the feature is genuinely finished.