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
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
| Parameter | Type | Description |
|---|---|---|
definition | string|int | Object tuning name or definition id. |
coords | vector3 | Where to put it. |
heading | number? | 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
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
| Parameter | Type | Description |
|---|---|---|
object | Object | The 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
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
| Parameter | Type | Description |
|---|---|---|
object | Object | The 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
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
| Parameter | Type | Description |
|---|---|---|
zoneId | ZoneId? | Must be the lot you are on, or nil. |
definition | string|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
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
| Parameter | Type | Description |
|---|---|---|
coords | vector3 | Search center. |
definition | string|int? | Only this definition. |
radius | number? | 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
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
| Parameter | Type | Description |
|---|---|---|
object | Object | The object. |
Returns
string Tuning name of the object.
Example
if GetObjectDefinition(object) ~= 'object_coffeeMaker_espresso' then
return
endGetObjectPack
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
| Parameter | Type | Description |
|---|---|---|
object | Object | The 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
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
| Parameter | Type | Description |
|---|---|---|
object | Object | The object. |
Returns
ZoneId? Lot the object is on.
Example
local function isHere(object)
return GetObjectLot(object) == GetCurrentLot()
endGetObjectPosition
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
| Parameter | Type | Description |
|---|---|---|
object | Object | The 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
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
| Parameter | Type | Description |
|---|---|---|
object | Object | The object. |
coords | vector3 | New position. |
heading | number? | 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
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
| Parameter | Type | Description |
|---|---|---|
object | Object | The 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')
endGetObjectUsers
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
| Parameter | Type | Description |
|---|---|---|
object | Object | The 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
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
| Parameter | Type | Description |
|---|---|---|
object | Object | The 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)