Wax

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)
end

Kinds

A kind is named the way the game names it. These all work:

You writeIt 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:

OptionWhat it does
withinOnly creatures this many metres away or nearer. The result is sorted nearest first.
fromWhere to measure from: an Instance or { X = , Y = , Z = }. Your character when left out.
deadtrue 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.

init.lua
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)
FieldWhat it is
Kind, Variant, DisplayNameIts kind, such as "Wolf", the version of its kind, such as "Conifer_Wolf", and the name the game shows.
EpicThe name of the boss or alpha it is, such as "AlphaWolf_Boss". nil for an ordinary creature.
BehaviourWhom it treats as an enemy: "Default", "Friendly", "Tame", "HostileToPlayers", "HostileToAll", or the name of one of the game's teams.
ActionWhat it is doing now, as the game calls it: "Wander", "FindFood".
TargetThe actor it is after right now, or nil.
Stance"Standing", "Sitting" or "Lying".
IsJuveniletrue for a young animal.
IsTamed, CanBeTamedWhether it has been tamed, and whether the game's data has a taming rule for it.
IsFrozentrue 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
FieldWhat it is
Kind, DisplayName, TagThe kind's name, the name the game shows, and the game's own tag for it.
VariantsEvery variant of the kind.
VariantThe variant the fields below are about.
TeamThe team it starts on, which decides whom it attacks.
Diet"Carnivore" or "Herbivore".
DescriptorsThe words the game's data describes it with, such as "Passive".
Carcass, LootThe item its dead body is, and what the body gives.
TameThe 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.
MountWhat 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)
SignalWhen it fires
AddedA creature appeared. It fires for creatures that appear from now on.
DiedA creature was killed. Its body stays for a few seconds.
RemovedA creature left the world. info.Reason is "Destroyed" or "Unloaded".
ClearedThe 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

init.lua
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.

  • kind is 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.
  • place is a position, an Instance or game.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, Spawn waits until the game has given the creature its level. Anywhere else it answers at once, and Level and Health are right a few frames later.
OptionWhat it doesWhen left out
levelThe creature's level, from 1 to 120.The middle level of the zone the place lies in.
variantWhich variant, when kind names a kind that has several.
facingWhich way it looks, as { Yaw = 90 }.In front of you it looks at you.
behaviourThe team to put it on. See Behaviour below.
keepfalse 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

init.lua
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 writeWhat 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 = 50What 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.
  • Attack works on animals the game gives aggression, the hunters. On a deer or a rabbit it raises an error. Nothing calls an attack off again. Remove takes the animal away.
  • A new Behaviour counts from the next time the animal notices somebody. An animal that is already attacking goes on attacking after "Friendly".
  • Remove happens 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.

On this page