The game tree
Start at game and reach the world, the player and every object in it.
You reach everything in the game from one name: game.
print("Map:", game.MapName)
print("In a prospect:", game.InProspect)
local character = game.Character
if character then
print("Your character is", character.Name)
else
print("No character yet. You are at the main menu.")
endOpen the Log page of the Wax panel to see what it printed.
What game has
| Name | What it is | Its class |
|---|---|---|
game.World | The current world. Its children are the actors in it. | World |
game.LocalPlayer | Your player controller. | IcarusPlayerController |
game.Character | The character you control. nil at the main menu. | IcarusPlayerCharacter |
game.Players | The players in the session. See below. | |
game.GameState | The state of the session, shared with every player. | IcarusGameStateBase |
game.GameMode | The rules of the session. nil when you are a client in someone else's game. | IcarusGameModeBase |
game.GameInstance | The object the game keeps from when it starts until it closes. | BP_IcarusGameInstance_C |
game.Engine | The Unreal Engine object. | IcarusGameEngine |
game.Viewport | The game's view on the screen. | IcarusGameViewportClient |
game.MapName | The name of the current world, as text. | |
game.InProspect | true while you are in a prospect. | |
game.MapChanged | A signal that fires when the world changes. |
Most of these are Instances: objects of the game that you can read, change and call. The next page, Instances, shows how.
Each one is of a different class, so each has different properties and functions. A player controller has
PlayerCameraManager, and a game state has PlayerArray. Click a class in the table to see everything it
has in the Explorer. The object you get in the game can be of a class built on the one named here.
It then has everything listed, and more.
game is read-only. If you misspell a name, you get an error that suggests the right one.
Check for nil
game.Character is nil when you have no character, for example at the main menu. Check before you use it.
local character = game.Character
if not character then
return
end
print(character.ClassName)When the map changes
Entering or leaving a prospect changes the world. game.MapChanged fires with the new map's name.
game.MapChanged:Connect(function(name)
ui.Notify("You are now on " .. name, { title = "Map changed" })
end)Objects do not survive a map change
An Instance you got before the map changed is gone afterwards. Using it raises an error that tells you to
get it again. Ask game for a new one each time you need it. Don't keep an old one for long.
Players
for i, player in ipairs(game.Players:GetPlayers()) do
print(i, player)
end
for i, character in ipairs(game.Players:GetCharacters()) do
print(i, character)
end| Name | What it gives |
|---|---|
game.Players:GetPlayers() | A list with one Instance per player in the session (their player state). It works for the host and for clients. |
game.Players:GetCharacters() | A list of the characters those players control right now. |
game.Players.LocalPlayer | The same as game.LocalPlayer. |
Finding objects
local controller = game:Find("PlayerController")
print(controller)
local everyone = game:FindAll("PlayerController")
print("Controllers:", #everyone)| Function | What it gives |
|---|---|
game:Find(class_name) | The first live object of a class, or nil. |
game:FindAll(class_name) | A list of every live object of a class. |
game:Library(name) | One of the game's function libraries. See below. |
game:GetTagged(tag) | Every Instance you marked with that tag. |
game:GetChildren() | The top of the tree: world, game instance, game state and so on. |
game:GetService(name) | The same as game[name]. |
FindAll is slow
game:FindAll looks at every object in the game. Call it once and keep the answer for a while. Never call
it many times a second.
Function libraries
Some functions belong to no object in the world. The game keeps them in libraries, such as
KismetMathLibrary, KismetSystemLibrary and GameplayStatics. game:Library gives you one, and you call
its functions with a colon.
local maths = game:Library("KismetMathLibrary")
print(maths:Abs(-3.5)) -- 3.5
local system = game:Library("KismetSystemLibrary")
print(system:GetGameTimeInSeconds(game.World)) -- seconds since the world startedMany of these functions ask for a WorldContextObject first. Pass game.World.
The Explorer lists every library and what its functions take. A wrong name raises an error that suggests the right one.
The actors in the world
An actor is one thing placed in the world, such as a character or a tree. The children of game.World are
the actors. This counts them by class and prints the five most common ones.
local counts = {}
for _, actor in ipairs(game.World:GetChildren()) do
counts[actor.ClassName] = (counts[actor.ClassName] or 0) + 1
end
local names = {}
for class_name in pairs(counts) do
names[#names + 1] = class_name
end
table.sort(names, function(a, b) return counts[a] > counts[b] end)
for i = 1, math.min(5, #names) do
print(counts[names[i]], names[i])
endEvery function is listed in the game reference.