11 FindFirstChild and WaitForChild
Kyra Ma; Hasan Malik; and Rutwa Engineer
Learning Objectives
- Learn about the FindFirstChild and WaitForChild
- Learn when to use which
- Learn about Folders
- Learn about Models
Introduction
In Roblox Lua scripting, managing objects inside the game’s hierarchy is crucial. FindFirstChild and WaitForChild are two powerful functions used to search for objects within parent containers like Workspace, Players, and StarterGui.
Folder Structure
As we mentioned earlier on, Roblox organizes objects in a tree-like hierarchy where everything has a Parent and may have multiple Children.
For example,
📂 Workspace
┣ 📂 Map
┃ ┣ 🏠 House
┃ ┃ ┣ 🧱 Wall
┃ ┃ ┗ 🚪 Door
┃ ┗ 🌲 Tree
┣ 📂 Enemies
┃ ┣ 👾 Zombie
┃ ┗ 🐍 Snake
┗ 📂 Weapons
┣ ⚔️ Sword
┗ 🔫 Gun
Parent: House is inside Map, so Map is its parent.
Children: House has Wall and Door as its children.
Folders and Models
Folders help group objects logically without affecting the game’s physics. For example:
- game.Workspace.Enemies → Groups all NPCs
- game.ReplicatedStorage.Weapons → Stores all weapon assets
- game.ServerStorage.AdminScripts → Stores admin-related scripts
Example
local Folder = Instance.new(“Folder”)
Folder.Name = “Enemies”
Folder.Parent = game.Workspace — Adds the folder to Workspace
local Zombie = Instance.new(“Model”)
Zombie.Name = “Zombie”
Zombie.Parent = Folder — Adds Zombie inside Enemies folder
print(“Hello world!”)
Models group parts that belong together and allow scripts to treat them as a single entity.
For example:
- A car model containing wheels, seats, and a body.
- A character model containing head, arms, and legs.
- A door model with hinges and a script for opening.
Example
local Car = Instance.new(“Model”)
Car.Name = “Car”
Car.Parent = game.Workspace — Add car to Workspace
local Wheel = Instance.new(“Part”)
Wheel.Name = “Wheel”
Wheel.Parent = Car — Wheel becomes a child of the Car
FindFirstChild: Searching for Objects
This function searches for an object inside a parent without causing errors. It also returns nil if the object doesn’t exist, instead of stopping the script. This is used for checking if an object exists before accessing it and avoiding errors when accessing optional objects.
Example: Checking for a part inside our game
local part = game.Workspace:FindFirstChild("Door")
if part then
print("Door found!")
else
print("Door is missing!")
end
If Door exists, it prints “Door found!”.
If not, it prints “Door is missing!” but does not stop the script.
Example: Searching inside a folder
local enemyFolder = game.Workspace:FindFirstChild("Enemies")
if enemyFolder then
local zombie = enemyFolder:FindFirstChild("Zombie")
if zombie then
print("Zombie found!")
end
end
This program first checks if “Enemies” exists. Then, looks for “Zombie” inside “Enemies”.
PRO TIP: Using FindFirstChild with Timeout
One good use of FindFirstChild is looping until an object is found (instead of failing immediately). For example:
local part
local timeOut = 5 -- Wait for up to 5 seconds
local startTime = tick()
repeat
part = game.Workspace:FindFirstChild("Door")
task.wait(0.1) -- Small delay to prevent lag
until part or tick() - startTime > timeOut
if part then
print("Door found!")
else
print("Timed out waiting for Door")
end
This code repeatedly searches for an object (Door) in Workspace for up to 5 seconds before giving up. This prevents the script from running indefinitely if Door never appears.
- part starts as nil, since we haven’t found anything yet.
- timeOut = 5 means we will keep searching for up to 5 seconds.
- startTime = tick() stores the current time in seconds when the script starts.
Repeat loop:
- FindFirstChild(“Door”) tries to find “Door” inside Workspace.
- If “Door” is found, part is set to it and the loop stops.
- If “Door” is not found, the script waits 0.1 seconds before trying again.
- tick() – startTime > timeOut checks how much time has passed.
- If more than 5 seconds have passed, the loop stops even if the Door wasn’t found.
The last part of the code:
- If part is not nil, it means “Door” was found, so we print “Door found!”.
- If part is still nil, it means we waited 5 seconds without finding “Door”, so we print “Timed out waiting for Door”.
WaitForChild: Ensuring Objects Exist
WaitForChild pauses the script until the object appears. This prevents errors by making sure the object exists before accessing it. This function is mostly used when waiting for objects to load (especially when scripts run before everything is created) and ensuring network-replicated objects (like StarterGui elements) are available.
Example: Waiting for a Part to Appear
local part = game.Workspace:WaitForChild(“Door”)
print(“Door is ready!”)
- If Door exists, the script continues immediately.
- If Door doesn’t exist, the script pauses until it appears.
Example: Using WaitForChild in Player Characters
When a player joins, their character may take time to load, so WaitForChild is useful.
game.Players.PlayerAdded:Connect(function(player)
player.CharacterAdded:Connect(function(character)
local humanoid = character:WaitForChild("Humanoid") -- Ensures humanoid exists
print(player.Name .. "'s character has loaded!")
end)
end)
- Ensures Humanoid is ready before using it.
- Prevents nil errors when accessing Humanoid.Health.
FindFirstChild vs. WaitForChild
Okay, that was a lot of information! Which one should I use?
When to use WaitForChild:
Use WaitForChild when you are dealing with objects that may not be immediately available when the script runs. This is useful when working with dynamically loaded game assets, such as:
- Waiting for a player’s character to load before modifying it.
- Ensuring a UI element exists before trying to change its properties.
- Handling objects in ReplicatedStorage that may not be fully replicated to the client yet.
One potential downside is that if the object never appears, the script could freeze indefinitely unless a timeout is specified!
Use FindFirstChild when you don’t want the script to pause and the object you’re looking for is optional or already expected to exist. This is great for:
- Checking if an enemy has a shield before applying damage.
- Seeing if a specific tool exists in a player’s backpack before allowing an action.
- Making sure a button exists before modifying it, without stopping the script.
If the object doesn’t exist at that exact moment, FindFirstChild will just return nil, preventing potential script errors.
Congratulations—you are now familiar with the FindFirstChild and WaitForChild functions!