Sim natives
Read and change Sims: names, ages, needs, moods, buffs, skills, careers, outfits and interactions.
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.
Read and change Sims: names, ages, needs, moods, buffs, skills, careers, outfits and interactions. A Sim id is a string. On the server, Sim natives are answered by the game of the player who owns that Sim, so they work for every connected player's Sims and wait for the answer – call them from a thread, an event handler or a command. On a client, they read and change Sims of your own household; for other players' Sims on your lot the client can read the name, age, gender, position and current interaction.
Open in the natives browser Search all 199 natives at once.
GetActiveSim
Sim? GetActiveSim()Returns the Sim the local player controls. Same as GetPlayerCharacter(PlayerId()).
Cache it in a local and refresh it in playerSpawned and characterSelected instead of calling it every frame.
Parameters
This native takes no parameters.
Returns
Sim? The local player's Sim.
Example
RegisterCommand('whoami', function()
local sim = GetActiveSim()
if not sim then
return ShowToast('Pick a character first.')
end
local first, last = GetSimName(sim)
local mood = GetSimMood(sim)
ShowNotification(('You are %s %s and you feel %s.'):format(first, last, mood), { sim = sim })
end, false)DoesSimExist
boolean DoesSimExist(Sim sim)Checks a Sim id. Always validate Sim ids coming from clients.
Sim ids sent by clients can be made up. Check them with DoesSimExist before you pass them to any server native.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
Returns
boolean Whether the id belongs to a Sim in the neighborhood.
Example
RegisterNetEvent('rtx_social:compliment', function(target)
local src = source
if type(target) ~= 'string' or not DoesSimExist(target) then
return
end
local player = GetPlayerFromSim(target)
if player and GetPlayerLot(player) == GetPlayerLot(src) then
TriggerClientEvent('neighborly:notify', player, { text = GetPlayerName(src) .. ' likes your style!' })
end
end)GetSimName
string, string GetSimName(Sim sim)Returns a Sim's first and last 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 |
|---|---|---|
sim | Sim | The Sim. |
Returns
string, string First name and last name.
Example
AddEventHandler('playerSpawned', function(sim)
local first, last = GetSimName(sim)
ShowNotification(('Welcome home, %s %s!'):format(first, last), { title = 'Neighborly', sim = sim })
end)GetSimAge
string GetSimAge(Sim sim)Returns a Sim's life stage.
Use it to keep adult-only features away from children and teens – check on the server, not only in your client UI.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
Returns
string 'infant', 'toddler', 'child', 'teen', 'young_adult', 'adult' or 'elder'.
Example
local age = GetSimAge(GetPlayerCharacter(source))
if age == 'child' or age == 'teen' then
return
endGetSimGender
string GetSimGender(Sim sim)Returns the gender set in Create a Sim.
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 |
|---|---|---|
sim | Sim | The Sim. |
Returns
string 'male' or 'female' (the Sim's frame).
Example
local function greeting(sim)
if GetSimGender(sim) == 'female' then
return Config.Greetings.female
end
return Config.Greetings.male
end
RegisterNetEvent('rtx_cafe:hello', function()
local src = source
local sim = GetPlayerCharacter(src)
if sim then
TriggerClientEvent('neighborly:notify', src, { text = greeting(sim) })
end
end)GetSimPosition
vector3 GetSimPosition(Sim sim)Returns where a Sim is standing.
Use #(a - b) to get the distance between two positions. On the server, distance checks are your main defence against players interacting with things across the map.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
Returns
vector3 World position.
Example
local distance = #(GetSimPosition(sim) - Config.Counter)
if distance > 3.0 then
return
endSee also
GetSimNeed
number GetSimNeed(Sim sim, string need)Returns one need of a Sim. On a client it only works for Sims of your own household.
On the server the value comes from the owner's game, so it is always current. Townies and Sims of players who are offline can't be read.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
need | string | 'hunger', 'energy', 'bladder', 'hygiene', 'social' or 'fun'. |
Returns
number From -100 (empty) to 100 (full).
Example
CreateThread(function()
local warned = false
while true do
local energy = GetSimNeed(GetActiveSim(), 'energy')
if energy < -50 and not warned then
exports.neighborly:notify({ text = 'You look exhausted. Time for bed?', type = 'warning' })
warned = true
elseif energy > 0 then
warned = false
end
Wait(10000)
end
end)SetSimNeed
number SetSimNeed(Sim sim, string need, number value)Sets one need of a Sim. The server asks the owner's game to change it; on a client it only works for your own household.
Values outside -100 to 100 are clamped. The change happens in the owner's game and shows up in their need panel straight away.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
need | string | 'hunger', 'energy', 'bladder', 'hygiene', 'social' or 'fun'. |
value | number | From -100 to 100. |
Returns
number The new value.
Example
RegisterNetEvent('rtx_food:eat', function(itemId)
local src = source
local item = Config.Food[itemId]
local sim = GetPlayerCharacter(src)
if not item or not sim or IsSimBusy(sim) then
return
end
if not TakeMoney(src, item.price, 'Food: ' .. item.label) then
return
end
SetSimNeed(sim, 'hunger', math.min(GetSimNeed(sim, 'hunger') + item.hunger, 100))
end)GetSimMood
string, int GetSimMood(Sim sim)Returns a Sim's current emotion and how strong it is.
The mood is calculated from the Sim's moodlets, so change it with AddSimBuff and RemoveSimBuff rather than directly.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
Returns
string, int Mood ('happy', 'confident', 'energized', 'flirty', 'focused', 'inspired', 'playful', 'fine', 'bored', 'dazed', 'embarrassed', 'sad', 'tense', 'angry', 'uncomfortable', 'scared') and intensity 1–3.
Example
local mood, intensity = GetSimMood(sim)
if mood == 'angry' and intensity >= 2 then
CancelSimInteractions(sim)
endAddSimBuff
boolean AddSimBuff(Sim sim, string buff)Adds a moodlet (buff) to a Sim. On a client it only works for your own household.
Use the buff's tuning name. Adding a buff the Sim already has refreshes it. Unknown names raise an error you can catch with pcall.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
buff | string | Buff tuning name, for example 'buff_Energized_Caffeinated'. |
Returns
boolean true if the buff was added.
Example
RegisterNetEvent('rtx_spa:finishMassage', function()
local src = source
local sim = GetPlayerCharacter(src)
if not sim or GetPlayerLot(src) ~= Config.SpaLot then
return
end
if AddSimBuff(sim, 'relaxed_massage', 240) then
TriggerClientEvent('neighborly:notify', src, { text = 'You feel wonderfully relaxed.', type = 'success' })
end
end)RemoveSimBuff
void RemoveSimBuff(Sim sim, string buff)Removes a moodlet from a Sim. On a client it only works for your own household.
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 |
|---|---|---|
sim | Sim | The Sim. |
buff | string | The buff to remove. |
Returns
Nothing (void).
Example
RegisterNetEvent('rtx_spa:towel', function()
local src = source
local sim = GetPlayerCharacter(src)
if sim and HasSimBuff(sim, 'uncomfortable_wet') then
RemoveSimBuff(sim, 'uncomfortable_wet')
AddSimBuff(sim, 'cozy', 60)
end
end)HasSimBuff
boolean HasSimBuff(Sim sim, string buff)Checks for a moodlet.
Cheaper than looping over GetSimBuffs when you only care about one moodlet.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
buff | string | The buff. |
Returns
boolean Whether the Sim has it.
Example
if HasSimBuff(sim, 'caffeinated') then
exports.neighborly:notify({ text = 'Maybe no more coffee today.' })
endGetSimBuffs
table GetSimBuffs(Sim sim)Returns all moodlets of a Sim.
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 |
|---|---|---|
sim | Sim | The Sim. |
Returns
table List of { name, mood } for every visible buff.
Example
for _, buff in ipairs(GetSimBuffs(sim)) do
print(buff.name, buff.mood, buff.minutesLeft)
endGetSimSkillLevel
int GetSimSkillLevel(Sim sim, string skill)Reads a skill level.
Skills use decimals for progress inside a level, so 3.5 means halfway to level 4. Compare with math.floor when you only need the level.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
skill | string | Skill name such as 'cooking', 'charisma', 'mixology', 'painting'. |
Returns
int Level, 0 when the Sim hasn't started the skill.
Example
if GetSimSkillLevel(GetPlayerCharacter(source), 'cooking') < 3 then
TriggerClientEvent('neighborly:notify', source, { text = 'You need cooking level 3 to work here.', type = 'error' })
return
endSetSimSkillLevel
int SetSimSkillLevel(Sim sim, string skill, number level)Sets a skill level. On a client it only works for your own household.
Levels are clamped to the skill's maximum (usually 10, 5 for toddler and child skills). Raising a skill this way does not trigger level-up notifications; send your own with ShowNotification if you want one.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
skill | string | Skill name. |
level | number | New level, up to the skill's maximum. |
Returns
int The new level.
Example
RegisterNetEvent('rtx_cafe:practice', function()
local src = source
local sim = GetPlayerCharacter(src)
if not sim or not Player(src).state.onDuty or IsSimBusy(sim) then
return
end
local level = GetSimSkillLevel(sim, 'mixology')
SetSimSkillLevel(sim, 'mixology', math.min(level + 0.25, 10))
if math.floor(level + 0.25) > math.floor(level) then
TriggerClientEvent('neighborly:notify', src, { text = 'Your mixology skill went up!', type = 'success' })
end
end)GetSimTraits
table GetSimTraits(Sim sim)Returns a Sim's traits, including aspiration bonus traits.
Trait names are tuning names such as 'cheerful', 'foodie' or 'hot_headed'. Traits from packs only appear when the server requires that pack.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
Returns
table List of trait names.
Example
for _, trait in ipairs(GetSimTraits(sim)) do
if trait == 'foodie' then
AddSimBuff(sim, 'delicious_food', 60)
end
endGetSimCareer
string?, int GetSimCareer(Sim sim)Returns the Sim's career.
Career names are tuning names like 'culinary' or 'painter'. Combine with Player(id).state.job when your own jobs and game careers should work together.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
Returns
string?, int Career name like 'culinary' and level, or nil without a career.
Example
local career, level = GetSimCareer(sim)
if career == 'culinary' and level >= 4 then
Player(source).state:set('canCook', true, true)
endPushSimInteraction
boolean PushSimInteraction(Sim sim, string interaction, Sim|Object? target)Adds an interaction to the Sim's queue, as if the player had clicked it. Only works for Sims of the player's own household – on the server the owner's game runs it.
The interaction goes through the game's normal rules – if the target is in use or the Sim can't reach it, it fails like a player's click would. A partial name like 'sit' is matched against the interactions the target offers; use the full tuning name when you need one exact interaction.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
interaction | string | Interaction tuning name, or part of one: 'sit' picks the shortest matching interaction the target offers. |
target | Sim|Object? | What to interact with. Leave it out for interactions on the Sim itself. |
Returns
boolean true if the interaction was queued.
Example
RegisterNetEvent('rtx_cinema:takeSeat', function(seat)
local src = source
local sim = GetPlayerCharacter(src)
if type(seat) ~= 'string' or not sim then
return
end
if not PushSimInteraction(sim, 'sit', seat) then
TriggerClientEvent('neighborly:notify', src, { text = 'That seat is taken.' })
end
end)CancelSimInteractions
boolean CancelSimInteractions(Sim sim)Cancels everything in a Sim's interaction queue except the posture (standing or sitting).
Use it before a cutscene or a teleport, so the Sim doesn't walk back to whatever they were doing.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
Returns
boolean true if something was cancelled.
Example
RegisterCommand('freeze', function(source, args)
local target = tonumber(args[1])
local sim = target and GetPlayerCharacter(target)
if not sim then
return print('Usage: freeze <player id>')
end
CancelSimInteractions(sim)
Player(target).state:set('frozen', true, true)
end, true)IsSimBusy
boolean IsSimBusy(Sim sim)Checks whether a Sim is doing something.
Useful before pushing interactions or teleporting – interrupting a Sim mid-interaction can look odd for everyone watching.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
Returns
boolean true while the Sim runs any interaction.
Example
if IsSimBusy(sim) then
return exports.neighborly:notify({ text = 'Finish what you are doing first.' })
endGetSimCurrentInteraction
string? GetSimCurrentInteraction(Sim sim)Returns what the Sim is doing right now.
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 |
|---|---|---|
sim | Sim | The Sim. |
Returns
string? Name of the running interaction.
Example
if GetSimCurrentInteraction(sim) == 'sleep' then
print('Shh, they are sleeping')
endGetSimOutfit
string, int GetSimOutfit(Sim sim)Returns which outfit a Sim is wearing.
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 |
|---|---|---|
sim | Sim | The Sim. |
Returns
string, int Outfit category ('everyday', 'formal', 'athletic', 'sleep', 'party', 'swimwear', 'hot_weather', 'cold_weather', 'career') and index.
Example
RegisterNetEvent('rtx_cafe:clockIn', function()
local src = source
local category = GetSimOutfit(GetPlayerCharacter(src))
if category ~= 'career' then
return TriggerClientEvent('neighborly:notify', src, { text = 'Put on your work uniform first.' })
end
Player(src).state:set('onDuty', true, true)
end)GetSimHousehold
HouseholdId? GetSimHousehold(Sim sim)Returns the household a Sim belongs to.
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 |
|---|---|---|
sim | Sim | The Sim. |
Returns
HouseholdId? The Sim's household.
Example
RegisterNetEvent('rtx_social:visitCard', function(target)
local src = source
local sim = type(target) == 'number' and DoesSimExist(target) and target
local householdId = sim and GetSimHousehold(sim)
if not householdId then
return
end
local home = GetHouseholdHome(householdId)
TriggerClientEvent('neighborly:notify', src, {
title = 'The ' .. GetHouseholdName(householdId) .. ' household',
text = home and ('They live at ' .. GetLotName(home)) or 'They are looking for a home.'
})
end)GetSimNeeds
table GetSimNeeds(Sim sim)Returns all needs of a Sim in one call – cheaper than calling GetSimNeed six times.
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 |
|---|---|---|
sim | Sim | The Sim. |
Returns
table { hunger, energy, bladder, hygiene, social, fun, ... } from -100 to 100.
Example
RegisterServerCallback('rtx_hud:needs', function(source)
return GetSimNeeds(GetPlayerCharacter(source))
end)