Developer Preview

Object natives

Objects are everything placed on a lot – fridges, beds, espresso machines, doors.

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.

Objects are everything placed on a lot – fridges, beds, espresso machines, doors. Objects are identified by their tuning name (find it with GetObjectDefinition on one placed in the world) or definition id. Object natives run on the client, against the lot the player is on. Objects created with CreateObject are local to that player and temporary: they are never saved and disappear when the lot unloads or the resource stops. To show something to everyone on a lot, send a client event to everyone there and let each client create it.

Open in the natives browser Search all 199 natives at once.

CreateObject

Client
Object CreateObject(string|int definition, vector3 coords, number? heading)

Creates a temporary object for the local player on the current lot. It is never saved, only this player sees it, and it is removed when the resource stops or the lot unloads. Objects from packs the server doesn't use are refused.

Script objects are perfect for props, decorations and effects. Track the ids you create and delete them in onResourceStop – Neighborly also removes them for you when the resource stops.

Parameters

ParameterTypeDescription
definitionstring|intObject tuning name or definition id.
coordsvector3Where to put it.
headingnumber?Rotation in degrees.

Returns

Object The new object.

Example

local balloon

RegisterNetEvent('rtx_party:balloon', function(coords)
    if balloon then
        DeleteObject(balloon)
    end
    balloon = CreateObject(Config.BalloonObject, coords, 90.0)
end)

DeleteObject

Client
boolean DeleteObject(Object object)

Removes an object that this player's scripts created with CreateObject. Furniture placed in Build mode can't be deleted by scripts.

The object disappears for every player and its entity state bag is removed. Deleting objects players built themselves should always need their permission.

Parameters

ParameterTypeDescription
objectObjectThe object.

Returns

boolean true if it was removed.

Example

local spawned = {}

RegisterCommand('confetti', function()
    local pos = GetSimPosition(GetActiveSim())
    spawned[#spawned + 1] = CreateObject(Config.PropObject, pos + vector3(1.0, 0.0, 0.0))
end, false)

RegisterCommand('cleanup', function()
    for _, object in ipairs(spawned) do
        DeleteObject(object)
    end
    spawned = {}
end, false)

DoesObjectExist

Client
boolean DoesObjectExist(Object object)

Checks whether an object with that id is on the lot you are on.

Object ids only make sense on the lot the player is on. To tell the server about an object, send its position or definition – the server can't look objects up.

Parameters

ParameterTypeDescription
objectObjectThe object.

Returns

boolean Whether the id belongs to an object.

Example

RegisterNetEvent('rtx_notes:show', function(object, text)
    if type(object) ~= 'string' or not DoesObjectExist(object) then
        return
    end
    ShowHelpText(text, 5000)
end)

GetObjectsOnLot

Client
table GetObjectsOnLot(ZoneId? zoneId, string|int? definition)

Returns objects on a lot, optionally filtered.

Works for lots the side has loaded: on a client that is the current lot. Filtering by definition is much faster than filtering the full list in Lua.

Parameters

ParameterTypeDescription
zoneIdZoneId?Must be the lot you are on, or nil.
definitionstring|int?Only objects of this tuning name or definition id.

Returns

table List of objects.

Example

RegisterCommand('fridges', function()
    local fridges = GetObjectsOnLot(nil, Config.FridgeObject)
    exports.neighborly:notify({ text = ('%d fridges on this lot.'):format(#fridges) })
end, false)

GetClosestObject

Client
Object? GetClosestObject(vector3 coords, string|int? definition, number? radius)

Finds the nearest object.

Searches the lot the coordinates are on. Keep the radius small; on a client it only sees the current lot.

Parameters

ParameterTypeDescription
coordsvector3Search center.
definitionstring|int?Only this definition.
radiusnumber?Max distance, default 5.0.

Returns

Object? Closest match.

Example

RegisterCommand('register', function()
    local register = GetClosestObject(GetSimPosition(GetActiveSim()), 'object_register_cafe', 3.0)
    if not register then
        return ShowToast('Walk up to the cash register first.')
    end
    exports.neighborly:showContext('cafe_register')
end, false)

GetObjectDefinition

Client
string GetObjectDefinition(Object object)

Returns what kind of object it is.

The tuning name of the object's catalog entry, for example 'object_fridge_basic'. It is the same on every machine, so it is safe to compare in client and server code.

Parameters

ParameterTypeDescription
objectObjectThe object.

Returns

string Tuning name of the object.

Example

if GetObjectDefinition(object) ~= 'object_coffeeMaker_espresso' then
    return
end

GetObjectPack

Client
string GetObjectPack(Object object)

Returns the pack an object comes from.

Client only: it runs on the local player's PC and affects only their game. Other players don't see the result unless you tell the server.

Parameters

ParameterTypeDescription
objectObjectThe object.

Returns

string Pack code like 'EP01', 'BG' for the base game.

Example

RegisterCommand('whatpack', function()
    local object = GetClosestObject(GetSimPosition(GetActiveSim()), nil, 2.0)
    if object then
        local pack = GetObjectPack(object)
        ShowToast(('%s comes from %s'):format(GetObjectDefinition(object), GetPackName(pack) or pack))
    end
end, false)

GetObjectLot

Client
ZoneId? GetObjectLot(Object object)

Returns the lot an object is on – the current lot if the object exists, otherwise nil.

Client only: it runs on the local player's PC and affects only their game. Other players don't see the result unless you tell the server.

Parameters

ParameterTypeDescription
objectObjectThe object.

Returns

ZoneId? Lot the object is on.

Example

local function isHere(object)
    return GetObjectLot(object) == GetCurrentLot()
end

GetObjectPosition

Client
vector3, number GetObjectPosition(Object object)

Returns where an object is.

Object ids are only meaningful on the lot they belong to. Send positions to the server, not object ids, when other players need to know where something is.

Parameters

ParameterTypeDescription
objectObjectThe object.

Returns

vector3, number Position and heading in degrees.

Example

RegisterCommand('bell', function()
    local bell = GetClosestObject(GetSimPosition(GetActiveSim()), Config.BellObject, 3.0)
    if not bell then
        return ShowToast('Walk up to the bell first.')
    end
    local coords = GetObjectPosition(bell)
    TriggerServerEvent('rtx_cafe:ringBell', coords)
end, false)

SetObjectPosition

Client
boolean SetObjectPosition(Object object, vector3 coords, number? heading)

Moves an object that this player's scripts created with CreateObject.

Moves the object for everyone, without placement checks – make sure the spot is free and on the same lot.

Parameters

ParameterTypeDescription
objectObjectThe object.
coordsvector3New position.
headingnumber?Rotation in degrees. Leave it out to keep the current one.

Returns

boolean true when it moved.

Example

local sign = CreateObject(Config.SignObject, Config.SignCoords)

RegisterCommand('movesign', function()
    SetObjectPosition(sign, GetSimPosition(GetActiveSim()) + vector3(0.0, 0.0, 1.5), 180.0)
end, false)

IsObjectInUse

Client
boolean, Sim? IsObjectInUse(Object object)

Checks whether a Sim is using an object.

Client only: it runs on the local player's PC and affects only their game. Other players don't see the result unless you tell the server.

Parameters

ParameterTypeDescription
objectObjectThe object.

Returns

boolean, Sim? Whether it's in use and by which Sim.

Example

local inUse, user = IsObjectInUse(object)
if inUse then
    print(GetSimName(user) .. ' is using it')
end

GetObjectUsers

Client
table GetObjectUsers(Object object)

Returns all Sims using an object (sofas and tables can have several).

Client only: it runs on the local player's PC and affects only their game. Other players don't see the result unless you tell the server.

Parameters

ParameterTypeDescription
objectObjectThe object.

Returns

table List of Sims.

Example

RegisterCommand('sofa', function()
    local sofa = GetClosestObject(GetSimPosition(GetActiveSim()), nil, 3.0)
    if not sofa then
        return
    end
    for _, sim in ipairs(GetObjectUsers(sofa)) do
        local first = GetSimName(sim)
        AddChatMessage('Sofa', first .. ' is sitting here')
    end
end, false)

GetObjectPrice

Client
int GetObjectPrice(Object object)

Returns an object's current value in simoleons.

Client only: it runs on the local player's PC and affects only their game. Other players don't see the result unless you tell the server.

Parameters

ParameterTypeDescription
objectObjectThe object.

Returns

int Current value in simoleons.

Example

RegisterCommand('appraise', function()
    local object = GetClosestObject(GetSimPosition(GetActiveSim()), nil, 2.0)
    if object then
        ShowToast(GetObjectDefinition(object) .. ' is worth ' .. FormatMoney(GetObjectPrice(object)))
    end
end, false)