Creatures
Find the animals and enemies in the world by kind, and hear when one appears, dies or leaves.
game.Creatures is a list of every animal and enemy in the world. Wax keeps it up to date while you play, so
asking for it costs almost nothing.
for _, wolf in ipairs(game.Creatures:GetAll("Wolf")) do
print(wolf.Name)
endKinds
A kind is named the way the game names it. These all work:
| You write | It means |
|---|---|
"Wolf" | Every kind of wolf. |
"Conifer_Wolf" | Only the forest wolf. |
"Cave Worm" | The name the game shows players. |
"IcarusMountCharacter" | A class name, for every mount. |
Letter case, spaces and underscores do not matter, so "cave worm" and "CaveWorm" are the same.
A name Wax does not know raises an error that suggests the nearest one:
'Wolff' is not a creature kind. Did you mean 'Wolf'?game.Creatures:GetKinds() lists every kind in your version of the game, with how many of each are in the
world now. game.Creatures:GetLiveKinds() gives only the names of the kinds that are here.
Asking for creatures
-- every creature
local all = game.Creatures:GetAll()
-- wolves within 50 metres, nearest first
local near = game.Creatures:GetAll("Wolf", { within = 50 })
-- the closest creature of any kind, and how far it is
local creature, metres = game.Creatures:GetNearest()
-- how many deer there are
local count = game.Creatures:Count("Deer")The options:
| Option | What it does |
|---|---|
within | Only creatures this many metres away or nearer. The result is sorted nearest first. |
from | Where to measure from: an Instance or { X = , Y = , Z = }. Your character when left out. |
dead | true also returns bodies that have not been cleared away yet. |
sort = "nearest" | Sorts nearest first without a distance limit. |
Distances are in metres. Positions are the engine's own, where 100 is one metre.
Facts about one creature
local facts = game.Creatures:Describe(creature)
print(facts.DisplayName, facts.Level, facts.Health, facts.MaxHealth, facts.IsAlive)Describe returns plain values: Kind, Variant, DisplayName, ClassName, Name, Level, Health,
MaxHealth, IsAlive and Position.
Fields on a creature
A creature has fields of its own, so you can read one value without Describe. Each asks the game when you
read it.
local window = ui.Window({ title = "Nearest creature", width = 320, height = 220 })
local name = window:Field("Kind", "")
local doing = window:Field("Doing", "")
local health = window:Field("Health", "")
task.every(0.5, function()
local creature = game.Creatures:GetNearest()
if not creature then return end
name:Set((creature.DisplayName or "?") .. " level " .. tostring(creature.Level))
doing:Set(creature.Action or "nothing")
health:Set(tostring(creature.Health) .. " / " .. tostring(creature.MaxHealth))
end)| Field | What it is |
|---|---|
Kind, Variant, DisplayName | Its kind, such as "Wolf", the version of its kind, such as "Conifer_Wolf", and the name the game shows. |
Epic | The name of the boss or alpha it is, such as "AlphaWolf_Boss". nil for an ordinary creature. |
Behaviour | Whom it treats as an enemy: "Default", "Friendly", "Tame", "HostileToPlayers", "HostileToAll", or the name of one of the game's teams. |
Action | What it is doing now, as the game calls it: "Wander", "FindFood". |
Target | The actor it is after right now, or nil. |
Stance | "Standing", "Sitting" or "Lying". |
IsJuvenile | true for a young animal. |
IsTamed, CanBeTamed | Whether it has been tamed, and whether the game's data has a taming rule for it. |
IsFrozen | true while it is held frozen. |
A creature is a character too. It also has Health, MaxHealth, Level, Alive, Position and the other
fields listed on Your character, and stats and
modifiers.
A few bosses are built differently in the game: their class is IcarusPawn, which is not a character. On
those, Epic, Behaviour, Action, Target, Stance and IsFrozen read nil, and they have none of the
character fields.
What the game's data says about a kind
GetInfo reads the game's tables for one kind or variant. The creature does not have to be in the world.
local info = game.Creatures:GetInfo("Buffalo")
print(info.DisplayName, info.Diet, info.Carcass)
if info.Tame then
print("Taming takes", info.Tame.Seconds, "seconds")
end| Field | What it is |
|---|---|
Kind, DisplayName, Tag | The kind's name, the name the game shows, and the game's own tag for it. |
Variants | Every variant of the kind. |
Variant | The variant the fields below are about. |
Team | The team it starts on, which decides whom it attacks. |
Diet | "Carnivore" or "Herbivore". |
Descriptors | The words the game's data describes it with, such as "Passive". |
Carcass, Loot | The item its dead body is, and what the body gives. |
Tame | The taming rule that names it: how long a taming takes, the food and shelter it wants, and what the animal becomes. nil when none does. |
Mount | What the data says about the tamed animal: its orders and the saddles that fit. nil when there is none. |
Give a variant such as "Conifer_Wolf" or a creature for that variant. Give a kind such as "Wolf" for the
variant named like the kind, or else its first one.
The first call reads three of the game's tables, which took between 1 and 15 ms. Later calls are quick. Call it when a window opens, not in the middle of a fight.
game.Creatures:GetTamed() lists the tamed animals in the world: mounts, pets and livestock, whoever they
belong to. It takes a kind and the same options as GetAll. No tamed animal was in the world when this was
tested, so it has only been seen to answer an empty list.
When creatures come and go
game.Creatures.Added:Connect(function(creature)
print("appeared:", game.Creatures:GetKind(creature))
end)
game.Creatures.Died:Connect(function(creature, info)
print(info.Kind, "died")
end)
game.Creatures.Removed:Connect(function(creature, info)
print(info.Kind, "is gone:", info.Reason)
end)| Signal | When it fires |
|---|---|
Added | A creature appeared. It fires for creatures that appear from now on. |
Died | A creature was killed. Its body stays for a few seconds. |
Removed | A creature left the world. info.Reason is "Destroyed" or "Unloaded". |
Cleared | The map changed. It fires once, in place of one Removed for each creature. |
After Removed, the creature can no longer be used. You can still compare it with one you kept.
From Wax 0.3.0 there is also game.Creatures.Damaged, and Died says what killed the
creature. Both are on Events of the game.
Now and later in one call
Observe calls your function for every matching creature that is here now and for each one that appears
later. If your function returns a function, that one runs when the creature is gone.
game.Creatures:Observe("Wolf", function(wolf)
local tag = ui.Tag(wolf, { text = "Wolf" })
return function() tag:Remove() end
end)Observe returns a connection. Call :Disconnect() on it to stop. Everything is undone when your mod reloads.
Players
game.Players has the same for the characters of the people in your session:
game.Players:ObserveCharacters(function(character)
if game.Players:IsLocal(character) then return end
print(game.Players:GetName(character), "is here")
end)Spawn a creature
local window = ui.Window({ title = "Spawner", width = 280, height = 170 })
window:Button("A deer in front of me", function()
local deer, why = game.Creatures:Spawn("Deer")
if not deer then
ui.Notify(why or "Nothing was spawned.", { kind = "warn" })
return
end
ui.Notify("A level " .. tostring(deer.Level) .. " deer.")
end)
window:Button("A level 5 wolf, 20 metres away", function()
local me = game.Me.Position
local place = { X = me.X + 2000, Y = me.Y, Z = me.Z }
game.Creatures:Spawn("Conifer_Wolf", place, { level = 5 })
end)game.Creatures:Spawn(kind, place, options) puts a new wild creature into the world with the game's own
spawn.
kindis a variant, such as"Conifer_Wolf"or"Deer", or a kind that has only one. A kind with several raises an error that lists them.placeis a position, an Instance orgame.Me. Left out, the creature goes six metres in front of your character.- Wax asks the game for ground a creature can walk on within 5 metres of the place. Where there is none, it raises an error and nothing is spawned.
- Inside a task, such as a button's function,
Spawnwaits until the game has given the creature its level. Anywhere else it answers at once, andLevelandHealthare right a few frames later.
| Option | What it does | When left out |
|---|---|---|
level | The creature's level, from 1 to 120. | The middle level of the zone the place lies in. |
variant | Which variant, when kind names a kind that has several. | |
facing | Which way it looks, as { Yaw = 90 }. | In front of you it looks at you. |
behaviour | The team to put it on. See Behaviour below. | |
keep | false takes the creature away again when your mod unloads. | true: it stays. |
One spawn took 3 to 4 ms, and 18 ms once when the game had to load the kind first. A tamed animal cannot be spawned in this version.
Change a creature
local window = ui.Window({ title = "Nearest creature", width = 280, height = 210 })
local function nearest()
return (game.Creatures:GetNearest({ within = 50 }))
end
window:Button("Freeze or free it", function()
local creature = nearest()
if not creature then return end
if creature.IsFrozen then creature:Unfreeze() else creature:Freeze() end
end)
window:Button("Make it friendly", function()
local creature = nearest()
if creature then creature.Behaviour = "Friendly" end
end)
window:Button("Remove it", function()
local creature = nearest()
if creature then creature:Remove() end
end)| You write | What it does |
|---|---|
creature:SetLevel(level) | Sets its level, from 1 to 120. Its health is full afterwards, so set the level first and Health after it. |
creature:Freeze(), creature:Unfreeze() | Holds it where it stands, and lets it go again. |
creature:Attack(target) | Makes a hunter angry at a player's character. target is that character or game.Me. |
creature:Remove() | Takes it out of the world, alive or dead, with nothing left behind. |
creature.Behaviour = "Friendly" | Puts it on another team: "Default", "Friendly", "Tame", "HostileToPlayers", "HostileToAll", or a team's own name. |
creature:Heal(), creature:Kill(), creature:Teleport(place), creature.Health = 50 | What can be done to any character. |
Things to know:
- These are for wild animals. On a tamed animal and on the few bosses of the class
IcarusPawn, each raises an error that says so. Attackworks on animals the game gives aggression, the hunters. On a deer or a rabbit it raises an error. Nothing calls an attack off again.Removetakes the animal away.- A new
Behaviourcounts from the next time the animal notices somebody. An animal that is already attacking goes on attacking after"Friendly". Removehappens a moment later, not in the same frame.creature:IsValid()says when it is gone.- Nothing is undone when your mod unloads, apart from a creature spawned with
keep = false. - Whether the other players in your session see a spawned creature and its changes has not been looked at.
In someone else's game
When you join another player's game, your PC only knows the creatures near you. The list is shorter than the
host's, and Removed also fires when a creature moves out of range.