Engine-host API
Function syntax
parent:WaitForChild(name, timeoutSeconds)Short summary
In compatible hosts, waits for a named child that may arrive asynchronously. Prefer a bounded timeout and handle a missing result.
Safe code example
-- Assumes a compatible host has supplied parent.
local function findCheckpoint(parent)
if not parent then return nil, "Missing parent" end
local checkpoint = parent:WaitForChild("Checkpoint", 5)
if not checkpoint then
return nil, "Checkpoint unavailable after timeout"
end
return checkpoint
endPractical game development scenario
A scene component may arrive after the script starts. Wait briefly, then show a recoverable loading state or skip the optional feature if the dependency is unavailable. Do not indefinitely block the entire game startup.
Compatibility and safety notes
Timeout units, return values, and scheduling behavior must be verified in your host documentation. This method is not a standard Lua table function.
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 dictionaryChoose the timeout from the caller’s responsibility
The example uses a bounded wait to make failure visible, not to recommend one universal duration. An optional decoration and a required loading dependency can justify different responses. Decide what the caller can safely do if the child is missing. It might skip a cosmetic effect, display a recoverable loading message, or stop initializing the affected feature. A timeout should lead to that documented outcome instead of simply replacing an indefinite wait with an eventual nil access. Keep the dependency name close to the feature that requires it so a renamed object produces a useful diagnostic rather than a generic failure far away in the startup sequence.
Recheck ownership after a wait returns
A dependency can arrive after the reason for requesting it has disappeared. The user may have closed a panel, the scene may have changed, or a newer initialization attempt may now own the feature. After a wait completes, check whether the original operation is still relevant before changing the scene. A small generation identifier or cancellation flag can make that decision explicit. The exact scheduling and lifecycle mechanisms depend on your host. The general rule is to avoid assuming that conditions observed before a yield remain unchanged afterward. Without that check, a delayed dependency can cause an old callback to reintroduce interface elements or objects that the owner already removed.
Prefer clear dependencies over repeated discovery
If a feature repeatedly needs the same child during a short operation, obtain and validate the reference once at an appropriate boundary. Repeatedly waiting from several helper functions can hide the true startup order and make failures difficult to reproduce. Document which component supplies the dependency and whether the reference remains valid across scene changes. When it becomes invalid, let the owner acquire a new reference deliberately rather than treating the previous one as permanent. Test the normal arrival path, a missing child, a late arrival after cancellation, and a dependency replaced during initialization. Those scenarios reveal integration problems that a single successful wait in a development scene will not show.