Household natives
Households are the families and roommate groups that live together and share funds and a home.
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.
Households are the families and roommate groups that live together and share funds and a home. Household natives on the server talk to the game of the player who plays that household.
Open in the natives browser Search all 199 natives at once.
GetHousehold
table? GetHousehold(HouseholdId householdId)Returns a summary of a household.
A snapshot table – changing it changes nothing. Use the household setters for changes.
Parameters
| Parameter | Type | Description |
|---|---|---|
householdId | HouseholdId | The household. |
Returns
table? { id, name, funds, members, home }.
Example
RegisterCommand('family', function(source)
local household = GetHousehold(GetPlayerHousehold(source))
if not household then
return
end
TriggerClientEvent('neighborly:notify', source, {
title = 'The ' .. household.name .. ' household',
text = ('%d members · %s'):format(#household.members, FormatMoney(household.funds))
})
end, false)GetPlayerHousehold
HouseholdId? GetPlayerHousehold(Player player)Returns the household a player is playing.
Households own lots and money in the game. Many ownership checks boil down to GetLotOwner(zoneId) == GetPlayerHousehold(player).
Parameters
| Parameter | Type | Description |
|---|---|---|
player | Player | Server id of the player. |
Returns
HouseholdId? The household of the player's current character.
Example
RegisterNetEvent('rtx_realty:appraise', function()
local src = source
local householdId = GetPlayerHousehold(src)
local home = householdId and GetHouseholdHome(householdId)
if not home then
return TriggerClientEvent('neighborly:notify', src, { text = 'You do not own a home.' })
end
TriggerClientEvent('neighborly:notify', src, {
text = ('%s is worth %s.'):format(GetLotName(home), FormatMoney(GetLotValue(home) or 0))
})
end)GetHouseholdName
string GetHouseholdName(HouseholdId householdId)Returns the household 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 |
|---|---|---|
householdId | HouseholdId | The household. |
Returns
string Family name.
Example
AddEventHandler('householdMovedIn', function(householdId, zoneId)
SendChatMessage(-1, 'Welcome Wagon', ('The %s family just moved into %s!'):format(GetHouseholdName(householdId), GetLotName(zoneId)), { 61, 220, 151 })
end)GetHouseholdMembers
table GetHouseholdMembers(HouseholdId householdId)Returns all Sims in a household, including roommates.
Includes members who are offline or played by nobody. Use GetPlayerFromSim to find the ones that are online right now.
Parameters
| Parameter | Type | Description |
|---|---|---|
householdId | HouseholdId | The household. |
Returns
table List of Sims.
Example
for _, sim in ipairs(GetHouseholdMembers(householdId)) do
print(GetSimName(sim))
endIsSimInHousehold
boolean IsSimInHousehold(Sim sim, HouseholdId householdId)Checks household membership.
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. |
householdId | HouseholdId | The household. |
Returns
boolean Whether the Sim belongs to it.
Example
if not IsSimInHousehold(GetPlayerCharacter(source), GetLotOwner(zoneId)) then
return
endGetHouseholdFunds
int GetHouseholdFunds(HouseholdId householdId)Returns how much money a household has.
For most money features use the economy natives (GetBalance, TakeMoney …) – they act on the same funds but keep a transaction log.
Parameters
| Parameter | Type | Description |
|---|---|---|
householdId | HouseholdId | The household. |
Returns
int Household funds in simoleons.
Example
RegisterCommand('funds', function()
local householdId = GetPlayerHousehold(PlayerId())
if householdId then
SendNUIMessage({ action = 'balance', value = FormatMoney(GetHouseholdFunds(householdId)) })
end
end, false)SetHouseholdFunds
void SetHouseholdFunds(HouseholdId householdId, int amount)Sets household funds directly. Prefer AddHouseholdFunds or the economy natives, which keep a transaction log.
Writes the funds directly without a transaction log entry. Prefer AddHouseholdFunds, RemoveHouseholdFunds or the economy natives in gameplay code; keep this one for admin tools.
Parameters
| Parameter | Type | Description |
|---|---|---|
householdId | HouseholdId | The household. |
amount | int | New amount, 0 or more. |
Returns
Nothing (void).
Example
RegisterCommand('setfunds', function(source, args)
local target, amount = tonumber(args[1]), tonumber(args[2])
local householdId = target and GetPlayerHousehold(target)
if not householdId or not amount or amount < 0 then
return print('Usage: setfunds <player id> <amount>')
end
SetHouseholdFunds(householdId, math.floor(amount))
print(('%s now has %s'):format(GetHouseholdName(householdId), FormatMoney(GetHouseholdFunds(householdId))))
end, true)AddHouseholdFunds
int AddHouseholdFunds(HouseholdId householdId, int amount, string reason)Adds money to a household.
Logged in the household's transaction history with your reason. Returns the new funds.
Parameters
| Parameter | Type | Description |
|---|---|---|
householdId | HouseholdId | The household. |
amount | int | Amount to add. |
reason | string | Shown in the transaction history. |
Returns
int New funds.
Example
AddEventHandler('dayChanged', function(day, weekday)
if weekday ~= 'friday' then
return
end
for _, player in ipairs(GetPlayers()) do
local householdId = GetPlayerHousehold(player)
if householdId then
AddHouseholdFunds(householdId, 150, 'Weekly neighborhood bonus')
end
end
end)RemoveHouseholdFunds
boolean RemoveHouseholdFunds(HouseholdId householdId, int amount, string reason)Takes money from a household if it has enough.
Checks and removes in one step, so funds can never go below zero.
Parameters
| Parameter | Type | Description |
|---|---|---|
householdId | HouseholdId | The household. |
amount | int | Amount to remove. |
reason | string | Shown in the transaction history. |
Returns
boolean false if the household can't afford it – nothing is taken then.
Example
if not RemoveHouseholdFunds(householdId, 1200, 'Property tax') then
print('Not enough money for the tax')
endGetHouseholdHome
ZoneId? GetHouseholdHome(HouseholdId householdId)Returns where a household lives.
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 |
|---|---|---|
householdId | HouseholdId | The household. |
Returns
ZoneId? Home lot, or nil if homeless.
Example
local home = GetHouseholdHome(GetPlayerHousehold(source))
if home then
TravelToLot(source, home)
end