Server Exports

GetProperty

Returns full data of a property by its ID.

---@param {propertyId: number | string}: Property ID
---@return {propertyData: table | nil}
local propertyData = exports['vms_housing']:GetProperty(propertyId)

---

GetAllProperties

Returns full list of a properties.

local properties = exports['vms_housing']:GetAllProperties()

---

GetPlayerProperties

Returns a list of all properties owned / rented by the specified player.

---@param {identifier: number | string}: Player Server ID or Player Identifier
---@return {properties: table}: Data list of all properties
local properties = exports['vms_housing']:GetPlayerProperties(identifier)

Example

local properties = exports['vms_housing']:GetPlayerProperties(1)

print(json.encode(properties, {indent=true}))
--[[
    {
        "id": 138,
        "name": "Paleto House",
        "description": "",
        "type": "shell",
        "owner_name": "Tony Blunt"
        "owner": "char3:11000014c8ce27b",
        "region": "Paleto Bay",
        "address": "Procopio Dr",
        "last_enter": 1751993299,
        "unpaidBills": 0,
        "bills": [
            {
                "details": "{\"electricityUsage\":0,\"rateInfo\":{\"electricity\":0.0115,\"internet\":80.0,\"water\":0.5},\"internet\":80,\"electricity\":0,\"waterUsage\":0,\"water\":0.0}",
                "type": "services",
                "paid": false,
                "period": "07:2025",
                "id": 334,
                "house_id": 138,
                "total": 80
            }
        ],
        "permissions": [],
        "keys": "[\"138-9008CEA257\",\"138-9361DPW426\"]",
        "sale": {
            "active": false,
            "defaultActive": true,
            "defaultPrice": 1500000,
            "price": 1500000
        },
        "rental": {
            "active": false,
            "defaultActive": false,
            "defaultPrice": 0,
            "price": 0
        },
        "metadata": {
            "exit": {
                "w": 47.32084655761719,
                "x": -213.5472,
                "y": 6396.1655,
                "z": 32.1852
            },
            "lightState": false,
            "enter": {
                "x": -213.4049,
                "y": 6395.9585,
                "z": 33.7235
            },
            "allowFurnitureInside": true,
            "deliveryType": "outside",
            "lastCadastralPeriod": "07:2025",
            "zone": {
                "maxZ": 41.33707237243652,
                "area": 1148,
                "minZ": 25.33707237243652,
                "points": [
                    {
                        "y": 6362.8569,
                        "x": -192.8159
                    },
                    {
                        "y": 6378.2285,
                        "x": -177.2231
                    },
                    {
                        "y": 6388.0571,
                        "x": -186.8981
                    },
                    {
                        "y": 6389.7969,
                        "x": -185.0591
                    },
                    {
                        "y": 6408.2832,
                        "x": -204.0579
                    },
                    {
                        "y": 6415.0508,
                        "x": -207.3751
                    },
                    {
                        "y": 6415.5547,
                        "x": -207.3833
                    },
                    {
                        "y": 6398.7544,
                        "x": -227.5731
                    }
                ]
            },
            "upgrades": {
                "furnitureLimit": "1"
            },
            "locked": false,
            "allowFurnitureOutside": true,
            "garage": {
                "w": 46.99999618530273,
                "x": -197.7123,
                "y": 6397.5713,
                "z": 30.8626
            },
            "delivery": {
                "w": 130.0,
                "x": -216.7046,
                "y": 6394.7998,
                "z": 32.0852
            },
            "shell": "envi_shell_02_empty"
        },
        "creator": "char3:11000014c8ce27b",
        "furniture": [
            {
                "position": {
                    "pitch": 0.0,
                    "y": -3.47876214981079,
                    "z": 502.9772644042969,
                    "yaw": 0.0,
                    "x": -2.18221616744995,
                    "roll": -0.0,
                    "environment": "inside"
                },
                "stored": 0,
                "model": "prop_wall_light_06a",
                "id": 640,
                "metadata": [],
                "house_id": 138
            },
        ],
    },
]]

---

GetPlayerCurrentProperty

Returns the ID of the property the player is currently inside (or nil).

---@param {src: number}: Player Server ID
---@return {propertyId: string}
local propertyId = exports['vms_housing']:GetPlayerCurrentProperty(src)

---

IsPlayerInProperty

Returns true if the player is inside any property.

---@param {src: number}: Player Server ID
---@param {propertyId: number | string}
---@return {isInProperty: boolean}
local isInProperty = exports['vms_housing']:IsPlayerInProperty(src, propertyId)

---

HasKeys

Returns true if the player has keys to the specified property.

---@param {src: number}: Player Server ID
---@param {identifier: string}: Player Identifier (e.g. 'char1:1100113jadckz')
---@param {propertyId: number | string}
---@param {keyId: string} (Optional)
---@return {hasKeys: boolean}
local hasKeys = exports['vms_housing']:HasKeys(src, identifier, propertyId, keyId)

---

GenerateKeySerialNumber

Generates a unique serial number for a key for the given property.

---@param {propertyId: number | string}
---@return {serialNumber: boolean}
local serialNumber = exports['vms_housing']:GenerateKeySerialNumber(propertyId)

---

HasPermissions

Returns true if the player has the specified permission for a property.

---@param {propertyId: number | string}
---@param {identifier: string}: Player Identifier (e.g. 'char1:1100113jadckz')
---@param {permission: string}
---@return {hasPermissions: boolean}
local hasPermissions = exports['vms_housing']:HasPermissions(propertyId, identifier, permission)

Explanation

List of available permissions:

• garage

• furniture

• billPayments

• keysManage

• upgradesManage

• marketplaceManage

• sell

• automaticSell

• rent

• rentersManage

---

HasAnyPermission

Returns true if the player has any kind of permission for that property.

---@param {propertyId: number | string}
---@param {identifier: string}: Player Identifier (e.g. 'char1:1100113jadckz')
---@return {hasAnyPermissions: boolean}
local hasAnyPermissions = exports['vms_housing']:HasAnyPermission(propertyId, identifier)

---

EnterProperty

Enter the property (used for admin tools or dev cleanup).

---@param {src: number}: Player Server ID
---@param {propertyId: number | string}
exports['vms_housing']:EnterProperty(src, propertyId)

---

GiveProperty

Give the property to a player or company

---@param {identifier: number | string}: Player Server ID / Identifier or CitizenID / Agency Name
---@param {propertyId: number | string}: Property ID
exports['vms_housing']:GiveProperty(identifier, propertyId)

---

DeleteProperty

Deletes the property (used for admin tools or dev cleanup).

---@param {propertyId: number | string}: Property ID
exports['vms_housing']:DeleteProperty(propertyId)

---

CreateDirtAtCoords

Creating dirt for the house.

You can use this in your eating / drinking system when a player eats, they may leave a stain or crumbs.

---@param {propertyId: number | string}: Property ID
---@param {model: string}: Dirt object model from VMS Housing files
---@param {position: vector3}
---@param {heading: number}
exports['vms_housing']:CreateDirtAtCoords(propertyId, model, position, heading)

Dirt Models

vms_blood1 vms_blood1small vms_blood2 vms_blood2small vms_dirtfootsteps vms_coffeestain1 vms_coffeestain2 vms_crumbs1 vms_crumbs2 vms_dirtmud1 vms_dirtmud2 vms_dirtmud3 vms_dirtmud4 vms_ketchupspill vms_liquidspill1 vms_liquidspill2 vms_liquidspill3 vms_liquidspill4 vms_mustardspill vms_oilspill1 vms_oilspill2 vms_sodaspill1 vms_winestain1

Example

local myPed = GetPlayerPed(src)
local myCoords = GetEntityCoords(myPed)
local heading = GetEntityHeading(myPed)

local propertyId = exports['vms_housing']:GetPlayerCurrentProperty(src)
if not propertyId then
    return
end

local model = 'vms_crumbs1'
local position = vector3(myCoords.x, myCoords.y, myCoords.z - 0.99) -- Setting foot coordinates

exports['vms_housing']:CreateDirtAtCoords(propertyId, model, position, heading)

---

DropPlayerFromProperty

Kick a player out of the property immediately without screen fade-in/fade-out

---@param {src: number}: Player Server ID
exports['vms_housing']:DropPlayerFromProperty(src)

---

WipeProperty

Resets or partially clears a property depending on ownership state.

---@param {propertyId: number | string}: Property ID
---@param {removeOwnership: boolean}: If true, owner/renter may be removed depending on logic
---@param {identifier: string | nil}: Identifier / CitizenID / Agency Name
exports['vms_housing']:WipeProperty(propertyId, removeOwnership, identifier)

Explanation

This function may perform either a partial reset or a full reset depending on the ownership relationship.

• If identifier is nil, full reset is allowed (admin/system usage).

• If identifier belongs to the owner and there is no renter = full reset.

• If identifier belongs to the owner and renter exists = only owner is removed.

• If identifier belongs to the renter and no owner exists = full reset.

• If identifier belongs to the renter and owner exists = only renter is removed.

Full Reset

A full reset restores the property to its default configuration defined in Housing Creator before being purchased by a player.

Full reset includes:

• All furniture removed (database + memory)

• All property bills removed

• Unpaid bills counters cleared

• Keys cleared

• Permissions cleared

• Grass state cleared

• Metadata reset (locked state, lights, upgrades, dirt, alarm phone number, doors locked)

• Last enter timestamp removed

• Sale price restored to default value

• Rental price restored to default value

• Sale/rental active state restored to default (property returns to market if configured so)

---

ResetPlayerProperties

Resets all properties associated with a given identifier.

This function is primarily intended for character lifecycle management, such as Character Kill (CK), permanent character deletion, or player bans with asset removal.

It ensures that all properties linked to the character are safely restored to their default Housing Creator configuration.

---@param {identifier: string}: Identifier / CitizenID / Agency Name
exports['vms_housing']:ResetPlayerProperties(identifier)

Explanation

• Finds all properties owned or rented by the provided identifier.

• Internally calls WipeProperty for each property.

• Ownership logic is handled automatically.

---

AddStarterApartment

Gives a player a predefined starter apartment (e.g. at character creation).

---@param {identifier: string}: Player Identifier (e.g. 'char1:1100113jadckz')
exports['vms_housing']:AddStarterApartment(identifier)

Explanation

Read the How to use Starter Apartments guide if you want to know how to properly implement this feature on your server.

---

TeleportToStartingApartment

Teleport the player directly to the property.

It works only once, after the Starting Apartment has previously been granted. Example Integration

---@param {src: number}: Player Server ID
exports['vms_housing']:TeleportToStartingApartment(src)

---

RegisterHook

--- ### Available Hook Names:
--- OnPropertyCreate - Fired when a new property is created.
--- OnPropertyEdit - Fired when a property is edited.
--- OnPropertyDelete - Fired when a property is deleted.
--- OnPermissionUpdate - Fired when property permissions are updated.
--- OnOwnerChange - Fired when the owner of the property changes.
--- OnRenterChange - Fired when the renter of the property changes.

---@param name string The hook name (see list above)
---@param cb fun(data: table) Callback function triggered when the hook fires
exports['vms_housing']:RegisterHook(name, function(data)
    print(json.encode(data, {indent = true}))
end)