World natives
The shared clock, calendar, seasons, worlds and sounds.
Developer Preview. Scripting is live on Neighborly servers – everything on these pages works today. The API is young, so tell us what you need next on Discord.
The shared clock, calendar, seasons, worlds and sounds. Neighborly servers run in real time, so every player sees the same hour.
Open in the natives browser Search all 199 natives at once.
GetGameTime
int, int GetGameTime()Returns the time on the neighborhood clock. It is the same for every player.
The neighborhood clock is shared: every player sees the same time. It moves according to the server's game speed, not real time. For cooldowns use GetGameTimer.
Parameters
This native takes no parameters.
Returns
int, int Hour (0–23) and minute.
Example
CreateThread(function()
while true do
local hour, minute = GetGameTime()
GlobalState.cafeOpen = hour >= 7 and hour < 22
Wait(10000)
end
end)SetGameTime
void SetGameTime(int hour, int? minute)Sets the neighborhood clock for everyone.
Changes the clock for every player at once. Jumping forward does not fast-forward needs – it only moves the clock.
Parameters
| Parameter | Type | Description |
|---|---|---|
hour | int | 0–23. |
minute | int? | 0–59. |
Returns
Nothing (void).
Example
RegisterCommand('time', function(source, args)
local hour, minute = tonumber(args[1]), tonumber(args[2]) or 0
if not hour or hour < 0 or hour > 23 then
return print('Usage: time <hour> [minute]')
end
SetGameTime(hour, minute)
SendChatMessage(-1, 'World', ('The clock was set to %02d:%02d.'):format(hour, minute))
end, true)GetGameDay
int, string GetGameDay()Returns the current day.
Days count up from the server's first start, so they work for weekly events. Listen to dayChanged instead of polling.
Parameters
This native takes no parameters.
Returns
int, string Day number and weekday name.
Example
local day, weekday = GetGameDay()
if weekday == 'saturday' then
GlobalState.marketDay = true
endSee also
GetGameSpeed
int GetGameSpeed()Returns the game speed. It exists for compatibility; time never runs faster or pauses on a server.
Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.
Parameters
This native takes no parameters.
Returns
int Always 1 – Neighborly servers run in real time.
Example
CreateThread(function()
while true do
SendNUIMessage({ action = 'speed', paused = GetGameSpeed() == 0 })
Wait(1000)
end
end)See also
GetSeason
string? GetSeason()Returns the current season in the player's game.
Seasons run in each player's own game, so ask on the client.
Parameters
This native takes no parameters.
Returns
string? 'spring', 'summer', 'fall', 'winter', or nil without Seasons (EP05).
Example
AddEventHandler('lotEntered', function()
local season = GetSeason()
SendNUIMessage({ action = 'menu', items = Config.Menus[season or 'summer'] })
end)GetWorlds
table GetWorlds()Returns the worlds players can live in, depending on the server's packs.
Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.
Parameters
This native takes no parameters.
Returns
table List of world names, like 'Willow Creek'.
Example
for _, world in ipairs(GetWorlds()) do
print(world, GetWorldName(world))
endGetWorldName
string GetWorldName(string world)Returns a world's display name.
Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.
Parameters
| Parameter | Type | Description |
|---|---|---|
world | string | World id like 'willow_creek'. |
Returns
string Display name like 'Willow Creek'.
Example
RegisterCommand('worlds', function()
for _, world in ipairs(GetWorlds()) do
AddChatMessage('Worlds', ('%s – %d lots'):format(GetWorldName(world), #GetLotsInWorld(world)))
end
end, false)GetCurrentWorld
string? GetCurrentWorld()Returns the world the local player is in.
World ids look like 'willow_creek'; turn them into names with GetWorldName.
Parameters
This native takes no parameters.
Returns
string? Name of the world the local player is in.
Example
if GetCurrentWorld() == 'newcrest' then
exports.neighborly:notify({ text = 'Welcome to Newcrest!' })
endPlaySoundFrontend
void PlaySoundFrontend(string sound, number? volume)Plays a sound only the local player hears.
Only the local player hears it – ideal for UI clicks and personal alerts.
Parameters
| Parameter | Type | Description |
|---|---|---|
sound | string | Game UI sound name or nui:// path. |
volume | number? | 0.0–1.0. |
Returns
Nothing (void).
Example
RegisterNetEvent('rtx_cafe:tipReceived', function(amount)
PlaySoundFrontend('ui_cash_register', 0.8)
ShowToast('+' .. FormatMoney(amount) .. ' tip', 2000)
end)