“schedule the removal of the object without yielding any code”
Just means that the script’s execution won’t be delayed. The instance is scheduled for removal, once the time specified by the 2nd argument has elapsed the instance is destroyed, in the same way that “:Destroy()” will instantly destroy an instance. If any code proceeds the “:AddItem()” method call it won’t be halted.
Debris, waits a certain seconds b4 destroying an object, hence called cleaning up. On the other hand, :Destroy just sets the item to nil the instant, its called.
So if you want to schecdule an object to be destroyed at a specific time use Debris:AddItem(instance, 3). I
I don’t recall the exact details nor conversation but I remember that Debris has been finnicky when attempting to destroy a large number of instances - as it is, there already is an internally imposed maximum amount of instances that can be queued that can potentially make destruction unpredictable.
In most or all cases it’s better if you manually destroy instances you no longer need or write your own deletion scheduler instead of relying on Debris. The only benefit it provides you is being able to specify an expiry time but it’s very easy to write your own and better junk handler that better interfaces with the needs of your systems including recovery, deletion extension or cancellation. In a serious project, you may need to schedule cleaning for more than just instances (i.e. pure Lua objects).
You’re better off using :Destroy() as it’s far more reliable and will get rid of instances instantly.
Debris is also more about casual cleanup so you don’t need to script your own removal script (at least if you aren’t using a lot of parts) and is generally not as reliable anyway.
For example, say you had an explosion effect, or a building crumbling, but you didn’t want the loose parts just sitting there lagging the server. Instead of scripting a whole removal process, what you could do is just send them to debris with a timer of a few seconds, so they’ll despawn naturally.
Like Colbert stated above, I too have seen many reports of Debris being weird and not destroying Instances at all, you should use :Destroy() yourself, if you want an instance to be destroyed later you can use:
task.delay(1, function() -- The number 1 is the time it will wait before destroying it (seconds)
instance:Destroy()
end)
This also doesn’t yield the script at all, just like Debris Service.
One benefit of the Debris service is that it won’t error if the instance scheduled for deletion has already been deleted by the time the Debris service would otherwise delete it. On the flip side the “Destroy” instance method will error if called on an already deleted instance (nil). As previously mentioned in the thread, one could write their own wrappers to work around these behaviors.