species

Server

modkit.species manages custom playable species. A custom species is a host species from the game with a new look, new values and its own attacks. The player controls a real host dinosaur, so movement, swimming, hunger, growth, saving and the game's own rules stay as they are. The client mod hides the host model and shows the custom model instead. The server applies the values and runs the attacks. The custom species guide walks through the whole flow.

Definitions come from two places. The Server Tool writes species\<name>\species.json under the server root, one folder per species, and builds the model into client-mods\species_<name>.pak. Scripts define a species with modkit.species.define. A script definition replaces a file definition of the same name while the server runs. The plugin looks at the files every 5 seconds and loads them again when they changed. Values and attacks apply right away. New models reach a player on the next join, because the launcher downloads the pak files before the game starts.

Species names have 1 to 32 characters from a-z, 0-9 and _.

Definition fields

Every field is optional except host. A missing field has its default. Distances are Unreal units (100 per metre), times are seconds, shares go from 0 to 1, angles are degrees.

visual

animations holds one entry per role. A role is a short id of an animation (idle = "idle"), a table { anim = "idle", rate = 1, loop = true }, or a blend space { blend = { { anim = "swim", x = 0, y = 0 }, ... }, rate = 1 } with up to 32 samples. x runs from -1 (turning left) to 1 (turning right), y from -1 (diving) to 1 (climbing). rate goes from 0.05 to 10.

A blend role plays the sample closest to the current turn and pitch. The client switches to another sample only when it is clearly closer and the current one has played for at least 0.3 seconds, and the new sample continues at the same point of its cycle, so a stroke does not restart. When the built blend space asset carries blend data, the client blends the samples smoothly instead.

thresholds sets the speeds in units per second at which the roles switch: { trot = 350, run = 700, swimFast = 900 }, each from 1 to 10000. A missing threshold comes from the host's movement values.

stats: a number replaces the host value, { factor = 1.5 } multiplies it.

habitat

attacks holds up to 16 entries.

access

How an attack runs

1. The player presses the key. The client mod sends the request to the server and plays nothing yet.
2. The server checks the species, the growth, the cooldown, the stamina, that the player is alive and not in another attack, and allowIn against the water.
3. customAttack fires. A handler that returns false cancels the attack.
4. The stamina is taken, the cooldown starts, and every player within 600 m receives the animation cue.
5. From hit.time on, for hit.duration, the server tests the shape against the positions and facing of the players and the animals with a handle. Every victim is hit once per attack. Damage goes through the normal damage path, so god mode and damage free zones apply. A victim with a custom species takes damageTaken times the damage.
6. customAttackHit fires for every hit.

A host attack with source = "host:<ability>" keeps the game's own hit detection and damage. The server only tells the clients which animation to play when the ability fires.

modkit.species.list

modkit.species.list()

Returns: the names of all species, sorted.

modkit.species.get

modkit.species.get(name)

Returns: the definition with every field filled in, defaults included, or nil.

local mosa = modkit.species.get("mosasaurus")
print(mosa.label, mosa.host, #mosa.attacks)

modkit.species.reload

modkit.species.reload()

Loads every species.json again right away. A file with broken JSON is skipped with a log line, and the definition from before stays. A bad value in a file is replaced by its default, and a log line names the field.

Returns: true.

modkit.species.define

modkit.species.define(name, definition)

Defines a species for as long as the server runs. Nothing is written to disk. The model and the animations must already be in a pak under client-mods, named after the species. An unknown field, a wrong type, a value outside its range, a missing host or a bad name raises a Lua error that names the field.

Returns: true.

modkit.species.define("night_deino", {
  label = "Night Deinosuchus",
  host = "deinosuchus",
  stats = { health = { factor = 1.5 }, swimSpeed = { factor = 1.2 } },
  habitat = { land = false, outOfHabitatDamage = 0.02, outOfHabitatGrace = 15 },
  access = { permission = "species.night" },
})

modkit.species.players

modkit.species.players(name)

Returns: array of player tables, the online players that have this species.

player:setCustomSpecies

player:setCustomSpecies(name [, force])

Gives the player the species, or removes it with nil. When the player plays another species than the host right now, the server first turns them into the host with player:setSpecies, which means a fresh dinosaur with full health and no skin. The values and attacks follow on the next spawn.

Without force the access rules apply: the permission and maxPlayers. force = true skips both.

The assignment is kept per Steam ID in data\species\players.json and applied again after every spawn as the host species. A spawn as another species removes the assignment. Parking in the garage stores the species with the dinosaur, and a restore brings it back.

Returns: true, or false and one of "unknown species", "species is disabled", "no permission", "species is full", "could not switch to the host species: ...".

modkit.commands.add("species", function(player, name)
  if not name then return player:message("Usage: /species <name> or /species none") end
  local ok, why = player:setCustomSpecies(name ~= "none" and name or nil)
  player:message(ok and "Done." or why)
end)

player:getCustomSpecies

player:getCustomSpecies()

Returns: the species name, or nil.

The player table also carries customSpecies with the same value.

Events

modkit.events.add("customAttack", function(player, attackId)
  for _, zone in ipairs(modkit.zones.at(player.x, player.y, player.z)) do
    if zone == "sanctuary" then return false end
  end
end)

modkit.events.add("customAttackHit", function(player, attackId, victim, damage)
  if victim.steamId then victim:message(player.name .. " hit you for " .. damage) end
end)