Returns the child of the
Instance with the given name. If the child does not exist, it will yield the current thread until it does.
If the timeOut parameter is specified, this function will return nil and time out after timeOut seconds elapsing without the child being found.
Where should WaitForChild be used?
WaitForChild is extremely important when working on code ran by the client (in a
LocalScript). Roblox does not guarantee the time or order in which objects are replicated from the server to the client. This can cause scripts to break when indexing objects that do not exist yet.
For example, a
LocalScript may access a
Model in the
Workspace called ‘Ship’ like so:
local ship = workspace.Ship -- Will error if ship hasn't replicated
However if the model ‘Ship’ has not replicated to the client when this code is ran an error will be returned breaking the
Another alternative is using
Instance/FindFirstChild. Not only is this good practice when indexing objects in the
DataModel (as it avoids accidentally accessing properties) but it does not break if the object does not exist. For example:
local ship = workspace:FindFirstChild("Ship") -- Won't error, but ship will be nil if the ship hasn't replicated
Here, if the model doesn’t exist the code will not error. Instead the value ship will be equal to nil. This is better, but still not much good if we want to use the ship model.
Instead WaitForChild should be used:
local ship = workspace:WaitForChild("Ship") -- Will wait until the ship has replicated before continuing
Here, the thread will be yielded until the ship model has been found. This means the ship model can be used as soon as it is ready.
- If a call to this function exceeds 5 seconds without returning, and no timeOut parameter has been specified, a warning will be printed to the output that the thread may yield indefinitely; this warning takes the form
Infinite yield possible on 'X:WaitForChild("Y")', where X is the parent name and Y is the child object name.
- This function does not yield if a child with the given name exists when the call is made.
- This function is less efficient than
Instance/FindFirstChildor the dot operator. Therefore, it should only be used when the developer is not sure if the object has replicated to the client. Generally this is only the first time the object is accessed
An optional time out parameter.
The following code waits for an instance named “Part” to be added to Workspace.
local part = Workspace:WaitForChild("Part") print(part.Name .. " has been added to the Workspace")