world

Server

Time of day, weather, day length, growth speed, messages to everyone and objects you place in the world.

The functions look up the sky actor (TISkyActor) and the weather actor (Ultra_Dynamic_Weather_C) in the running map. When the actor does not exist yet, the function returns nil or false and the plugin searches again two seconds later at the earliest.

modkit.world.getTime

modkit.world.getTime()

Returns: time of day in hours as a number, for example 13.5 for half past one. nil when there is no sky actor.

The value is the sky actor's TimeOfDayIsle divided by 100. 1200 in the game is noon, which is 12.0 here.

local hours = modkit.world.getTime()
if hours then print(string.format("it is %02d:%02d", math.floor(hours), math.floor(hours % 1 * 60))) end

modkit.world.setTime

modkit.world.setTime(hours)

Returns: true when the value was written. false when hours is out of range or there is no sky actor.

The day keeps running from the new time. There is no function to freeze the time yet.

modkit.commands.add("noon", function(player)
  modkit.world.setTime(12)
end, true)

modkit.world.getWeather

modkit.world.getWeather()

Returns: a table with the current values of the weather actor, or nil when there is none.

The numbers are the raw values of Ultra Dynamic Weather.

local w = modkit.world.getWeather()
if w and w.rain > 0.25 then modkit.world.notify("It is raining.") end

modkit.world.weatherPresets

modkit.world.weatherPresets()

Returns: array with the names of all weather presets (UDS_Weather_Settings_C assets) that are loaded on the server right now.

This scans every object in the game. Call it once in a command, not in a timer.

modkit.commands.add("presets", function(player)
  player:message(table.concat(modkit.world.weatherPresets(), ", "))
end, true)

modkit.world.setWeather

modkit.world.setWeather(preset [, seconds])

Calls the Change Weather function of the weather actor.

Returns: true when the preset was found and the call was made. false when the preset or the weather actor is missing. A missing preset is logged to server-plugin.log.

The runner writes bServerDynamicWeather=true into Game.ini, so the game may change the weather again by itself later.

modkit.commands.add("weather", function(player, name)
  if not name then player:message("usage: /weather <preset>") return end
  local ok = modkit.world.setWeather(name, 20)
  player:message(ok and ("weather changes to " .. name) or "unknown preset, try /presets")
end, true)

modkit.world.announce

modkit.world.announce(text [, title [, seconds]])

Shows the game's announcement banner to every player.

Returns: number of players it was sent to.

modkit.world.announce("Restart in five minutes.", "Server", 15)

modkit.world.notify

modkit.world.notify(text)

Shows the game's notification to every player.

Returns: number of players it was sent to.

modkit.world.notify("A storm is coming.")

modkit.world.clearSky

modkit.world.clearSky([seconds])

Switches to the first weather preset whose name contains clear. seconds is the transition time, default 30.

Returns: true when such a preset exists and the change was requested.

modkit.world.setWeatherCycle, stopWeatherCycle

modkit.world.setWeatherCycle(steps) modkit.world.stopWeatherCycle()

Runs through a list of weather presets and starts again at the end. The cycle replaces a cycle that is already running. It starts with the first step within one second.

1 to 64 steps. When a preset is not found, the cycle tries the next step 10 seconds later.

local steps = {}
for i, name in ipairs(modkit.world.weatherPresets()) do
  steps[i] = { preset = name, minutes = 15, transition = 90 }
end
if #steps > 0 then modkit.world.setWeatherCycle(steps) end

Preset names depend on the game version. Print modkit.world.weatherPresets() and pick from that list.

modkit.world.setNightBrightness

modkit.world.setNightBrightness(value)

Calls the game mode's SetBrightness for the night. 1 is the game's default, higher is brighter. nil goes back to 1. The server sends the value again every 30 seconds so that players who join later get it. The call needs one player on the server, without players it waits.

Returns: true.

modkit.world.setNightBrightness(3)

modkit.world.setDayLength, getDayLength, resetDayLength

modkit.world.setDayLength(dayMinutes [, nightMinutes]) sets how long day and night last in real minutes. Without the second value both get the same length. modkit.world.getDayLength() returns day and night length, or nil when the sky actor was not found. modkit.world.resetDayLength() puts back the values the map had before the first change.

modkit.world.setDayLength(60, 15)

modkit.world.freezeTime

modkit.world.freezeTime(frozen)

true stops the time of day by making day and night extremely long. false does the same as resetDayLength(). Combine it with setTime to hold a certain hour.

modkit.world.setTime(12)
modkit.world.freezeTime(true)

modkit.world.setGrowthMultiplier

modkit.world.setGrowthMultiplier(multiplier) modkit.world.getGrowthMultiplier()

Growth speed for every player who has no own setting from player:setGrowthMultiplier. 1 is normal. The value is not saved, set it when your resource starts.

modkit.world.setGrowthMultiplier(2)

modkit.world.spawnMesh

modkit.world.spawnMesh(path, x, y, z [, rotation [, scale [, material]]])

Spawns a static mesh actor that every player sees.

Returns: an integer handle, or nil and a reason ("static mesh could not be loaded", "spawn failed", "too many script spawned objects (limit 2000)").

The mesh is loaded from the game files on the game thread. The first load of an asset can cause a short hitch. The asset has to be part of the server's game files, and clients need it too. Mesh loading may fail on a Linux server. This plugin only runs on Windows, so that matters only if a Linux port happens.

Objects are gone after a server restart. Spawn them again when your resource starts.

local rock = modkit.world.spawnMesh("/Game/TheIsle/Environment/Rocks/SM_Rock_01.SM_Rock_01", -215000, 48000, 1200, 45, 2)

The path in the example is made up. Take real paths from the game files, for example with FModel.

modkit.world.spawnBlueprint

modkit.world.spawnBlueprint(path, x, y, z [, rotation [, scale]])

Same as spawnMesh for a blueprint actor class, /Game/.../BP_Name.BP_Name_C.

modkit.world.moveObject, deleteObject, objects

modkit.world.moveObject(handle, x, y, z [, rotation [, scale]]) returns true when the object still exists. modkit.world.deleteObject(handle) returns true when the object existed and was destroyed. modkit.world.objects() returns an array of tables with id, kind ("mesh" or "blueprint"), path, x, y, z, pitch, yaw, roll, scaleX, scaleY, scaleZ.