player

Server

modkit.players finds players. The player table describes one player and carries the methods that act on that player. Event handlers and command handlers receive a player table as their first argument.

The methods live in a shared metatable. player.kick is a function, rawget(player, "kick") is nil, and modkit.json.encode(player) gives you the data fields only.

A player table is a snapshot. The server reads all player data twice per second. Fields such as health or x can be up to half a second old, and they do not update after you received the table. Call modkit.players.get(player.steamId) for fresh values.

modkit.players.list

modkit.players.list()

Returns: array of player tables, one per player in the game. A player shows up here once the script link is open, see the launcher rule.

for _, p in ipairs(modkit.players.list()) do
  print(p.name, p.species, p.growth)
end

modkit.players.get

modkit.players.get(key)

Returns: a player table, or nil when nobody matches.

local target = modkit.players.get("76561198000000001")
if target then target:message("hello") end

modkit.players.count

modkit.players.count()

Returns: number of players in the game.

print("online: " .. modkit.players.count())

Fields

Identity fields are always there.

Game fields are there when the server found the player in the game. For a player without a dinosaur hasDino is false, species is "" and the numbers are 0.

player:message

player:message(text [, sender])

Shows a chat line to this player only.

Returns: true when the player was found and the call was made.

player:message("Welcome back.", "Guide")

player:notify

player:notify(text)

Shows the game's own notification to this player (ClientShowNotification).

Returns: true when the player was found and the call was made.

player:notify("You entered the sanctuary.")

player:announce

player:announce(text [, title [, seconds]])

Shows the game's announcement banner to this player (Client_ProcessIncomingAnnouncement).

Returns: true when the player was found and the call was made.

player:announce("The event starts at the lake.", "Event", 12)

player:print

player:print(text)

Writes a line into the F8 console of this player. Does nothing while the script link of that player is down. The F8 console is off by default, ISLEMODKIT_CONSOLE=1 in the environment of the game turns it on.

player:print("pong")

player:call

player:call(event, ...)

Sends an event to the client scripts of this player. Does nothing while the script link of that player is down. See the events guide for the argument rules.

modkit.events.add("playerJoined", function(player)
  player:call("welcome", "Welcome to the server", modkit.players.count())
end)

player:kick

player:kick([reason])

Kicks the player from the game server and closes the script link.

Returns: true when the game kick was issued.

player:kick("AFK")

player:teleport

player:teleport(x, y, z [, yaw])

Moves the player's dinosaur. Without yaw it calls K2_SetActorLocation. With yaw it calls K2_SetActorLocationAndRotation and keeps pitch and roll. There is no collision sweep and no ground check. A position inside the terrain stays inside the terrain.

Returns: true when the player has a dinosaur and the call was made. The game's own result is not passed on.

modkit.commands.add("goto", function(player, steamId)
  local target = steamId and modkit.players.get(steamId)
  if not target or not target.hasDino then player:message("no such player") return end
  player:teleport(target.x, target.y, target.z + 150)
end, true)

player:pos

player:pos()

Returns: x, y, z from the latest snapshot, or nil when the player has no dinosaur.

local x, y, z = player:pos()
if x then print(string.format("%.0f %.0f %.0f", x, y, z)) end

player:rotation

player:rotation()

Reads the rotation of the dinosaur at the moment of the call.

Returns: pitch, yaw, roll in degrees, or nil when the player has no dinosaur.

local pitch, yaw, roll = player:rotation()

player:setHealth, setHunger, setThirst, setStamina

player:setHealth(value), player:setHunger(value), player:setThirst(value), player:setStamina(value)

Sets one stat of the dinosaur and forces a network update so the client sees it at once.

Returns: true when the player has a dinosaur and the call was made.

player:setHealth(0) does not kill reliably. The dinosaur can stay alive with zero health. Use player:kill().

player:setHealth(player.maxHealth)
player:setHunger(player.maxHunger * 0.5)

player:setGrowth

player:setGrowth(value)

Returns: true when the player has a dinosaur and the call was made.

player:setGrowth(1.0)

player:kill

player:kill()

Kills the dinosaur on the server. It sets health to zero and calls the game's SpecialDeathFromServer.

Returns: true when the player has a dinosaur and the call was made.

modkit.commands.add("slay", function(player, steamId)
  local target = steamId and modkit.players.get(steamId)
  if target then target:kill() end
end, true)

player:setSkin

player:setSkin(skin)

Changes the colors and pattern slots of the dinosaur. All players see the result. The skins guide explains zones and color formats.

Returns: true when the player has a dinosaur and the call was made.

player:setSkin({ body = "#223344", markings = { 0.0, 3.0, 3.0 } })

player:getSkin

player:getSkin()

Returns: a table with all ten zones as "#RRGGBB" plus pattern, theme, variation, female and code. nil when the player has no dinosaur.

local skin = player:getSkin()
if skin then print(skin.body, skin.pattern) end

modkit.players.find

modkit.players.find(text)

Returns: array of player tables, empty when nobody matches.

modkit.commands.add("heal", function(admin, name)
  local found = modkit.players.find(name or "")
  if #found ~= 1 then admin:message(#found .. " players match") return end
  found[1]:heal()
end, true)

player:heal

player:heal()

Sets health to the maximum, clears venom and heals fractures of legs, body and head.

Returns: true when the player has a living dinosaur.

player:restoreStats

player:restoreStats()

Everything heal does, plus hunger, thirst, stamina and blood to their maximum, locked damage to zero and the three diet values filled.

Returns: true when the player has a living dinosaur.

modkit.events.add("playerSpawned", function(player)
  modkit.setTimeout(2000, function()
    local fresh = modkit.players.get(player.steamId)
    if fresh then fresh:restoreStats() end
  end)
end)

player:damage

player:damage(amount)

Takes health away. When the health would reach zero the player is killed the same way as with player:kill().

Returns: true when the player has a living dinosaur and amount is above zero.

player:setGod, isGod

player:setGod(enabled) player:isGod()

Twice per second the server sets the health back to the maximum and clears locked damage. It is a fast heal, not true invulnerability. A single hit that takes more than the full health still kills. The flag belongs to the Steam ID and lasts until you switch it off or the server restarts.

modkit.commands.add("god", function(player)
  player:setGod(not player:isGod())
  player:message(player:isGod() and "god mode on" or "god mode off")
end, true)

player:setInfiniteStamina

player:setInfiniteStamina(enabled)

Refills the stamina twice per second while it is on. Lasts until you switch it off or the server restarts.

player:getStatus

player:getStatus()

Reads values that are not part of the player snapshot. This asks the game directly, so call it when you need it and not for every player every second.

Returns: a table, or nil without a dinosaur.

player:setPrime

player:setPrime(value)

Returns: true when the player has a living dinosaur.

player:getMutations

player:getMutations()

Returns: a table, or nil without a dinosaur. Only filled slots are present.

The values are the internal mutation names of the game. Read them from a dinosaur that has the mutation.

player:setMutations

player:setMutations(slots)

The server adds the names to the unlocked list, writes parent and elder slots at once and the four active slots half a second later, because the game drops active slots that are written in the same tick.

Returns: true when the player has a living dinosaur.

local current = player:getMutations()
current.slot1 = "Hydrodynamic"
player:setMutations(current)

player:getNutrients, setNutrients, fillDiet

player:getNutrients() returns a table with carb, protein, lipid, bones, cannibal, magy, rottenFlesh, mushrooms (numbers), malnutrition (boolean) and max, the value a full diet bar has. player:setNutrients(values) writes the fields you pass and leaves the rest. player:fillDiet() fills carb, protein and lipid, clears cannibal and rotten flesh values and the malnutrition flag.

All three return nil or false without a dinosaur.

player:setNutrients({ carb = 0, malnutrition = true })

player:setGrowthMultiplier, freezeGrowth

player:setGrowthMultiplier(multiplier) player:freezeGrowth(frozen) player:getGrowthControl() player:resetGrowthControl()

Growth speed of one player. 2 grows twice as fast, 0.5 half as fast. freezeGrowth(true) stops growth. The setting belongs to the Steam ID, it is applied again after every respawn and lasts until resetGrowthControl() or a server restart. For all players at once see modkit.world.setGrowthMultiplier.

The server changes the four growth stage times of the dinosaur, based on the defaults of its class. The game saves those times with the character. A player who logs out while frozen stays frozen on the next login until a script resets it.

getGrowthControl() returns { frozen, multiplier, own }. own is false when the player only follows the global multiplier.

modkit.events.add("playerGrew", function(player, step)
  if step == 0.75 then player:freezeGrowth(true) end
end)

player:groupMembers, inSameGroup

player:groupMembers() returns an array of player tables of the other group members, empty when the player is alone, nil without a dinosaur. player:inSameGroup(other) returns a boolean. other is a player table or a Steam ID.

player:distanceTo

player:distanceTo(other) player:distanceTo(x, y [, z])

Returns: distance in Unreal units from the snapshot positions, or nil when one side has no dinosaur. Without z the player's own height is used.

if player:distanceTo(target) > 5000 then player:message("Too far away (50 m).") end

player:setScale

player:setScale(scale)

Scales the visible mesh of the dinosaur, 0.1 to 100. Hitboxes and the camera stay as they are. The scale is lost on respawn.

player:setSpecies

player:setSpecies(species [, growth])

Turns the player into another species on the spot. The server spawns the new dinosaur 3 m above the old one, moves the Steam ID over, lets the controller possess it and destroys the old body. If possessing fails, the new body is removed and the player keeps the old one.

Returns: true, or false and a reason.

The new dinosaur starts with full health. It never went through the character editor, so it has no skin colors and can look black. Set a skin with player:setSkin about a second later. Mutations and stats of the old dinosaur are gone.

player:setCustomSpecies, getCustomSpecies

player:setCustomSpecies(name [, force]) gives the player a custom species or removes it with nil. player:getCustomSpecies() returns the name or nil.

player:getState

player:getState()

Returns: a plain table with everything the garage saves, or nil without a living dinosaur. You can store it with modkit.storage or modkit.json.

player:applyState

player:applyState(state [, options])

Writes a state onto the dinosaur the player plays now. The species must match state.species. It runs the same four steps as a garage restore, see garage. The event stateApplied(player) fires after step 2.

Returns: true when the first step ran, or false and a reason.

player:hasPermission

player:hasPermission(permission)

Returns: boolean, see acl.

player:ban

player:ban([reason [, hours]])

Adds the player to the ban list and kicks them. hours of 0 or nothing means forever.