Isle Modkit: Server Owner Guide

Everything a server owner needs to run a modded Isle server with custom skins, chat commands and Lua scripts. No Unreal Editor, no cooking.

What runs where

• IsleModkitServer.exe (the runner) writes the config, starts the dedicated server, injects the modkit server plugin and shows the log. Its folder is the server root.
• The server plugin runs inside the game server. It loads your resources, talks to the modded clients on the script port, serves resource files on the HTTP port and gives Lua access to players, skins and chat.
• Every player joins with the Isle Modkit launcher and gets your client scripts and UI automatically. A client without the launcher is kicked after a short grace period.

Folder layout

server root\
  server.cfg          settings, one "load <resource>" line per resource
  resources\          your resources (Lua, UI, textures)
  client-mods\        .pak/.utoc/.ucas content mods that players download
  server-mods\        content mods copied into the game server
  server-plugin\build\isle-modkit-server.dll

server.cfg

sv_hostname My Modded Server
sv_maxplayers 40
sv_map Gateway
sv_port 7777
sv_httpport 30120
sv_scriptport 30122
sv_publicip 203.0.113.10
sv_gamedir C:\isle-modded-server
sv_admins 76561198000000001,76561198000000002
load skins
load myresource

sv_admins are Steam IDs. They can use admin-only commands and admin-only skins.

The launcher is mandatory. sv_requirelauncher 0 turns that check off, use it only for local debugging.

Your own lines on the server page

sets <name> "<text>" adds a line to your server page in the launcher, the same idea as sets on FiveM. The name is the label, the text is the value. Up to 24 lines, names up to 32 characters, text up to 200.

sets AntiCheat "Active"
sets Discord "discord.gg/myserver"
sets Rules "Semi realism, no KOS at water"
sets tags "realism, events, growth x2"

tags is special. It is split at the commas and shown as small labels. Everything else appears as written, in the order of your file. Emoji work if you save server.cfg as UTF-8.

The page also lists the resources you load and the paks players get on join. Restart the runner after changing these lines.

Resources

A resource is a folder under resources\ with a manifest.lua:

name "myresource"
author "you"

server "server.lua"
client "client.lua"
files { "ui/*", "textures/*" }

server scripts run in the game server. client scripts and files are sent to modded clients, encrypted per session, never written to their disk. Enable a resource with load myresource in server.cfg and restart the server.

Create a new resource from a template in the runner console:

new resource myresource
new skins

Skins

new skins creates the skins resource. Edit resources\skins\skins.lua:

Skins = {
  neon_rex = {
    species = "Tyrannosaurus",
    body = { 0.0, 4.0, 4.0 },
    markings = { 6.0, 0.0, 6.0 },
  },
  blood = {
    body = "#5A0A0A",
    flank = "#7A1010",
    underbelly = "#2A0505",
    markings = "#C41E1E",
    display = "#FF2020",
  },
}

Zones: body, flank, underbelly, markings, display, teeth, mouth, claws, detail, eyes. A zone you leave out keeps the player's own color.

Colors are "#RRGGBB" (the same values the in-game skin code uses) or { r, g, b } in linear light. Values above 1.0 make neon colors. species limits the skin to one dinosaur, admin = true limits it to admins, pattern, theme and variation set the pattern slots.

Players use it in chat or the F8 console:

/skins           list
/skin neon_rex   wear it, kept across respawns
/skinreset       back to the normal look
/giveskin <steamId> <name>   admins only

Server Tool (GUI)

IsleModkitServerTool.exe is the owner app. It has six tabs:

• Server picks the server folder and edits server.cfg (name, slots, map, ports, admins, game folder).
• Resources lists every folder under resources\, switches load lines on and off, and creates a new resource from a template.
• Skins is the skin editor. Every skin has ten zone rows with a color picker, a hex field and a neon factor. Saving writes resources\skins\skins.json (what the editor reads back) and resources\skins\skins.lua (what the server runs), and enables the skins resource in server.cfg. If a hand-written skins.lua is replaced the old file is kept as skins.lua.bak.
• AI builds your own animal AI without code. See Custom AI.
• Species turns your own model and animations into a playable animal. See Custom species.
• Dino Studio paints pattern textures on the real game model.

The tool needs modkit-assets.exe in a tools\ folder next to it. That helper reads the installed game and writes the extracted files to %LOCALAPPDATA%\IsleModkit\assets\<Species>\.

Custom AI

The AI tab has three parts.

• Brains describe how an animal senses, moves, picks targets, fights, works in a pack and when it is removed. New brain starts from Predator, Prey, Guard, Passive or Blank. The sections are Senses, Movement, Targets, Temperament, Attack, Pack, Idle and Body and despawn. The Lua section shows the same brain as a modkit.ai.defineBrain call you can copy into a script.
• Spawners keep a number of animals of one species alive around a point and give them a brain. X, Y and Z are game coordinates.
• Wild AI gives the animals the game spawns by itself one of your brains, species by species.

The tool shows metres and percent. Save writes data\ai\brains.json and data\ai\spawns.json in the server folder. A running server loads the change within a few seconds, no restart needed.

Scripts use the same brains through modkit.ai, see the Custom AI guide in the wiki.

Custom species

A custom species rides on an animal that is already in the game, the host. The host gives it movement, swimming, collision, hunger, growth and saving. Your model, your animations, your values and your attacks go on top. Every player sees your model because every player joins with the launcher.

You need the model and its animations as FBX files, the textures as PNG, TGA or JPG, and Unreal Engine 5.6 installed through the Epic Games launcher. You do not need to open Unreal.

1. New species. Pick a name and the host. Choose the host that moves most like your animal, for a sea creature that is Deinosuchus.
2. Import. Choose the folder with your files. The tool copies them into species\<name>\source\ and reads every FBX: bones, triangles, length, animations, textures.
3. Look. Size, offset and turn of your model on the host.
4. Animations. Link each situation (idle, swim, swim fast, hit, death and more) to one of your animations. Swimming and running can use a direction grid, one animation per turn and pitch. Suggest from file names fills most of it when the files are named after what they show.
5. Stats. Every value starts from the host. Keep it, set your own number or multiply the host value.
6. Habitat. Water, land, and how much health the animal loses outside.
7. Attacks. Own attacks with key, animation, damage, stamina cost, cooldown and hit area, or a host attack that keeps the game's damage and only gets your animation.
8. Access. A permission and a player limit.
9. Build. Imports, links and cooks everything and writes client-mods\species_<name>.pak. Players download it on their next join.

Values and attacks reach a running server within a few seconds after Save. Only new models, textures or animations need a new build. Scripts hand out the species with player:setCustomSpecies, see the Custom species guide in the wiki.

Dino Studio

The studio works on the game's own files, not on a copy.

1. Read game files lists the 25 playable species out of the installed paks.
2. Extract a species. You get every pattern texture (adult, juvie, hatchling), the teeth and mouth mask, the normal map, the roughness map and the skinned mesh as mesh.glb.
3. Open shows the model in 3D on the left and the UV map on the right. Drag in the 3D view to turn the model.
4. Pick a base pattern, then paint. The six letter buttons R G B C M Y are the six color zones of the game material, the three below them are teeth, mouth and claws. Every stroke rebakes the texture and the model updates while you paint.
5. Import PNG replaces the whole pattern with your own file. Only pure red, green, blue, cyan, magenta and yellow count as zones, everything else stays neutral gray.
6. Save texture writes a 2048x2048 PNG to resources\skins\textures\.

Assign the texture in the Skins tab under "Pattern texture". The skin then carries a line like:

studio_test = {
  species = "Tyrannosaurus",
  texture = "textures/test_stripes.png",
  body = "#6C3729",
}

The zone colors apply through the normal skin path. The texture comes on top: the server tells every client who wears which texture, the client mod loads the PNG out of the resource and swaps Adult_Base_ColorOverlay, Juvenile_Base_ColorOverlay and Hatchling_Base_ColorOverlay on the body material.

Content mods (.pak)

Drop mod_*.pak/.utoc/.ucas into client-mods\ (players download them on join) and server-mods\ (copied into the server). Run mods in the console or restart.

Server Lua API

The full reference with every function and its parameters is in the natives reference. The overview below is shorter.

Scripts run inside the game server on the game thread. Every handler receives a player table first.

Events

modkit.events.add("playerSpawned", function(player)
  player:message("Welcome " .. player.name .. ", you are a " .. player.species)
end)

player

Fields: steamId, name, species, growth, health, maxHealth, alive, hasDino, x, y, z, admin, linked (modded client), id (script link id, 0 without modded client), ip.

Methods:

player:message(text [, sender])      chat line to this player
player:print(text)                   F8 console line (modded clients)
player:call(event, ...)              event to this player's client scripts
player:kick(reason)
player:teleport(x, y, z)
player:pos()                         x, y, z or nil
player:setSkin{ body = "#FF0000", pattern = 2 }
player:getSkin()                     table with the current colors and pattern

modkit

modkit.players.list()                all players on the server
modkit.players.get(steamId)          one player or nil
modkit.players.count()
modkit.commands.add(name, fn [, adminOnly])   fn(player, arg1, arg2, ...)
modkit.events.add(name, fn)
modkit.events.callAll(event, ...)    to every modded client
modkit.roster.add(name, classPath, diet)      add a playable species (needs the content mod)
modkit.roster.remove(name)
modkit.roster.list()
modkit.setTimeout(ms, fn)            returns timer id
modkit.setInterval(ms, fn)           returns timer id
modkit.clearTimer(id)
modkit.isAdmin(steamId)
modkit.log(text)

Commands work from chat (/name args) and from the F8 console of modded clients. The standard Lua libraries (io, string, table, math, os) are available, so you can keep data in files next to your scripts.

Client Lua API

Client scripts run inside the player's game. They can draw UI (CEF browser pages), read keys and change how dinosaurs look locally.

modkit.events.add("onClientReady", function() ... end)
modkit.events.add("onServerConnected", function(target) ... end)
modkit.events.add(name, fn)          events from the server (player:call / callAll)
modkit.events.callRemote(name, ...)  event to the server scripts
modkit.setTimeout(ms, fn)  modkit.setInterval(ms, fn)  modkit.clearTimer(id)
modkit.keys.on("F5", function(down) ... end)    keys: letters, digits, F1..F24, SPACE, ENTER, ...
modkit.browser.add("ui/index.html")  browser handle with :call/:on/:execute/:setActive/:destroy
modkit.gui.cursor.show(freeze [, visible])
modkit.json.encode(value)  modkit.json.decode(text)
modkit.resources.file("textures/pattern.png")   bytes of a resource file

modkit.game

local me = modkit.game.localPlayer()      { id, species, growth, health, maxHealth, alive, x, y, z, isLocal }
local all = modkit.game.characters()      every dinosaur the client can see
modkit.game.materialCount(char)
modkit.game.materialParams(char, slot)    { {type, name, value}, ... } from the material chain
modkit.game.setMaterialColor(char, slot, "Color1_RedLayer", r, g, b [, a])
modkit.game.setMaterialScalar(char, slot, "Detail_Scale", 12)
modkit.game.setMaterialTexture(char, slot, "Adult_Base_ColorOverlay", "textures/pattern.png")

char is a character table, its id, or nil for the local player. Slot 0 is the body material of the dinosaur master material M_MasterSkin_Dinosaur. Known parameters: colors Color1_RedLayer to Color6_YellowLayer and MouthColor, textures Adult_Base_ColorOverlay, Juvenile_Base_ColorOverlay, Hatchling_Base_ColorOverlay, Base_Mask, Base_NormalMap, Base_RoughAlbedoCavityMap, Detail_NormalMap, Base_VFX_Mask, scalars GrowthAmount, Detail_Scale. The color overlay textures are zone maps: pure red, green, blue, cyan, magenta and yellow pixels select the six color layers.

Texture skins need the modded client on every player who should see them. Color skins set on the server are visible to everyone.

Ports

Open all three in the firewall.

Logs

• Runner console shows the game server log.
• %LOCALAPPDATA%\IsleModkit\server-plugin.log has resource output, Lua errors, chat hooks and the script link.
• status in the runner console shows players, script links and loaded resources.