Developer Preview

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

Client
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

Shared
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

ParameterTypeDescription
simSimThe 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

Shared
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

ParameterTypeDescription
simSimThe 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

Shared
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

ParameterTypeDescription
simSimThe 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
end

GetSimGender

Shared
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

ParameterTypeDescription
simSimThe 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

Shared
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

ParameterTypeDescription
simSimThe Sim.

Returns

vector3 World position.

Example

local distance = #(GetSimPosition(sim) - Config.Counter)
if distance > 3.0 then
    return
end

GetSimNeed

Shared
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

ParameterTypeDescription
simSimThe Sim.
needstring'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

Shared
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

ParameterTypeDescription
simSimThe Sim.
needstring'hunger', 'energy', 'bladder', 'hygiene', 'social' or 'fun'.
valuenumberFrom -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

Shared
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

ParameterTypeDescription
simSimThe 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)
end

AddSimBuff

Shared
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

ParameterTypeDescription
simSimThe Sim.
buffstringBuff 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

Shared
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

ParameterTypeDescription
simSimThe Sim.
buffstringThe 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

Shared
boolean HasSimBuff(Sim sim, string buff)

Checks for a moodlet.

Cheaper than looping over GetSimBuffs when you only care about one moodlet.

Parameters

ParameterTypeDescription
simSimThe Sim.
buffstringThe buff.

Returns

boolean Whether the Sim has it.

Example

if HasSimBuff(sim, 'caffeinated') then
    exports.neighborly:notify({ text = 'Maybe no more coffee today.' })
end

GetSimBuffs

Shared
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

ParameterTypeDescription
simSimThe 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)
end

GetSimSkillLevel

Shared
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

ParameterTypeDescription
simSimThe Sim.
skillstringSkill 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
end

SetSimSkillLevel

Shared
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

ParameterTypeDescription
simSimThe Sim.
skillstringSkill name.
levelnumberNew 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

Shared
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

ParameterTypeDescription
simSimThe 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
end

GetSimCareer

Shared
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

ParameterTypeDescription
simSimThe 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)
end

PushSimInteraction

Shared
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

ParameterTypeDescription
simSimThe Sim.
interactionstringInteraction tuning name, or part of one: 'sit' picks the shortest matching interaction the target offers.
targetSim|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

Shared
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

ParameterTypeDescription
simSimThe 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

Shared
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

ParameterTypeDescription
simSimThe 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.' })
end

GetSimCurrentInteraction

Shared
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

ParameterTypeDescription
simSimThe Sim.

Returns

string? Name of the running interaction.

Example

if GetSimCurrentInteraction(sim) == 'sleep' then
    print('Shh, they are sleeping')
end

GetSimOutfit

Shared
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

ParameterTypeDescription
simSimThe 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

Shared
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

ParameterTypeDescription
simSimThe 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

Shared
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

ParameterTypeDescription
simSimThe 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)