Exports

O DS-Homes expõe um conjunto de exports server-side para que outros recursos possam consultar o estado das casas, jogadores dentro de propriedades e dados de propriedades.

Todos os exports são server-side. Use exports['ds-homes']:nomeDoExport(args) a partir de qualquer outro recurso server.

Visão geral

Export	Descrição
`getPlayerHomes(user_id)`	Retorna todas as casas (próprias, financiadas, alugadas, morador)
`getPlayerResidences(user_id)`	Retorna apenas as casas de propriedade do jogador
`isPlayerInHome(user_id)`	Verifica se o jogador está dentro de alguma casa
`isUserInsideHome(source, houseId?)`	Verifica via source, opcionalmente filtrando por casa
`getAllHomes()`	Retorna todas as casas configuradas em `homes.lua`
`giveHome(user_id, homeName, options?)`	Entrega uma casa para um jogador
`removeHome(user_id, homeName)`	Remove uma casa específica de um jogador

getPlayerHomes

Retorna todas as casas relacionadas a um jogador: as que ele é dono, as que está financiando, as que está alugando de outro player e as que ele consta como morador.

local data = exports['ds-homes']:getPlayerHomes(user_id)

Parâmetros

Nome	Tipo	Descrição
`user_id`	`number`	ID do jogador

Retorno

{
  success = true,
  user_id = 42,
  total = 3,
  owned = { ... },
  financing = { ... },
  renting = { ... },
  resident_in = { ... },
}

Exemplo

local data = exports['ds-homes']:getPlayerHomes(user_id)

if not data.success then
  print("Erro: " .. (data.message or "desconhecido"))
  return
end

print(string.format("Player %d tem %d casas no total", data.user_id, data.total))

for _, home in ipairs(data.owned) do
  print(string.format(" - Própria: %s (IPTU: %s)", home.name, home.iptuStatus))
end

for _, rental in ipairs(data.renting) do
  print(string.format(" - Alugando de %d: %s", rental.ownerId, rental.homeName))
end

for _, fin in ipairs(data.financing) do
  print(string.format(" - Financiando: %s (%d/%d parcelas)",
    fin.homeName, fin.paidInstallments, fin.totalInstallments))
end

O export usa os.time() para calcular iptuStatus e isOverdue no momento da chamada. Não cacheie esses valores por longos períodos.

getPlayerResidences

Versão simplificada — retorna apenas as casas onde ds_homes.user_id = user_id. Mais leve que getPlayerHomes se você só precisa das próprias.

local result = exports['ds-homes']:getPlayerResidences(user_id)

Retorno

{
  success = true,
  properties = {
    {
      id = 12,
      name = "Apartamento S1 - Apt 101",
      buildingName = "Apartamento S1",
      apartmentNumber = 101,
      iptu = 1735689600,
      residents = { ... },
      houseCoords = vector3(...),
      type = "apartment",
      interior = "ds_apt_modern_01",
      price = 250000,
      needsIptu = true,
      garageData = { x, y, z, heading } | nil,
    },
    ...
  }
}

isPlayerInHome

Verifica se o jogador está dentro de alguma casa agora.

local state = exports['ds-homes']:isPlayerInHome(user_id)

Retorno

{
  inHome = true,
  homeName = "Apartamento S1 - Apt 101",
  ownerId = 42,
}

-- ou se não estiver
{ inHome = false }

Exemplo

RegisterCommand("checkhome", function(source)
  local user_id = vRP.getUserId(source)
  local state = exports['ds-homes']:isPlayerInHome(user_id)
  if state.inHome then
    print(("Player %d está em '%s' (dono: %d)"):format(user_id, state.homeName, state.ownerId))
  end
end)

isUserInsideHome

Variante que aceita source (ao invés de user_id) e opcionalmente verifica se está em uma casa específica.

exports['ds-homes']:isUserInsideHome(source)
exports['ds-homes']:isUserInsideHome(source, "Apartamento S1 - Apt 101")

Parâmetros

Nome	Tipo	Descrição
`source`	`number`	Source do jogador
`houseId`	`string?`	Opcional. Nome da casa para filtrar

Retorno

boolean — true se o jogador está dentro (e, se houseId foi passado, naquela casa específica).

getAllHomes

Retorna a tabela completa CFG['homes'] (todas as casas configuradas em config/homes.lua).

local homes = exports['ds-homes']:getAllHomes()

for _, home in ipairs(homes) do
  print(home.name, home.type, home.price)
end

Útil para gerar listagens, blips externos ou cruzar dados com outros recursos sem reler o config.

giveHome

Entrega uma casa para um jogador sem cobrar nada. Útil para sistemas de recompensa, eventos, painel de admin externo, comandos de staff customizados, etc.

local result = exports['ds-homes']:giveHome(user_id, homeName, options)

Parâmetros

Nome	Tipo	Descrição
`user_id`	`number`	ID do jogador que receberá a casa
`homeName`	`string`	Nome da casa (mesmo `name` do `config/homes.lua`)
`options`	`table?`	Opcional. Veja abaixo

Opções

Campo	Tipo	Padrão	Descrição
`skipMaxCheck`	`boolean`	`false`	Se `true`, ignora o limite máximo de casas por jogador
`setIptu`	`boolean`	`nil`	Se `true`, força criar com IPTU de 15 dias. Se `false`, força sem IPTU. Se `nil`, usa o `needsIptu` do config

Retorno

{
  success = true,
  propertyName = "Apartamento S1 - Apt 101",
  buildingName = "Apartamento S1",
  apartmentNumber = 101,                 -- nil se for casa (não apartamento)
}

Em caso de erro:

{ success = false, message = "max_properties_reached" }

Códigos de erro

Mensagem	Significado
`invalid_params`	`user_id` ou `homeName` faltando/invalido
`home_not_found`	Casa não existe em `CFG['homes']`
`home_disabled`	Casa foi desabilitada pelo admin
`home_deleted`	Casa foi removida do config pelo admin
`max_properties_reached`	Jogador já bateu o limite máximo de casas
`home_already_owned`	Casa (do tipo `house`) já tem dono
`all_apartments_occupied`	Prédio sem apartamentos livres

Exemplo

RegisterCommand("givecasa", function(source, args)
  local target = tonumber(args[1])
  local homeName = args[2]
  if not target or not homeName then
    return print("Uso: /givecasa <user_id> <home_name>")
  end

  local result = exports['ds-homes']:giveHome(target, homeName)
  if result.success then
    print(("Casa '%s' entregue para %d"):format(result.propertyName, target))
  else
    print("Falha: " .. result.message)
  end
end, true)

Forçando sem checar limite de casas:

exports['ds-homes']:giveHome(user_id, "Apartamento S1", { skipMaxCheck = true })

O export valida o estado do jogador e do prédio, mas não cobra dinheiro nem coins. Se você quiser cobrar, faça antes de chamar o export e reverta se o retorno for success = false.

Para apartamentos, o intercom é selecionado automaticamente (primeiro número livre entre 101 e 100 + maxApartments).

Remove uma casa de um jogador. Faz toda a limpeza: expulsa quem estiver dentro, limpa o báu (incluindo provedores externos via chest_hooks.onClear), apaga favoritos, outfits e dados relacionados, e atualiza o cache do dono.

local result = exports['ds-homes']:removeHome(user_id, homeName)

Parâmetros

Nome	Tipo	Descrição
`user_id`	`number`	ID do dono atual da casa
`homeName`	`string`	Nome completo da casa em `ds_homes.name` (ex: `"Apartamento S1 - Apt 101"`)

homeName é o ds_homes.name (com sufixo de apartamento se aplicável), não o building_name. Para apagar todas as casas de um prédio em lote, use o callback admin ou consulte o banco antes.

Retorno

{ success = true }

Em caso de erro:

{ success = false, message = "home_not_found" }

Códigos de erro

Mensagem	Significado
`invalid_params`	`user_id` ou `homeName` faltando/invalido
`home_not_found`	Casa não existe para esse `user_id`
`delete_failed`	Falha inesperada no DELETE (raro)

Exemplo

RegisterCommand("tirarcasa", function(source, args)
  local target = tonumber(args[1])
  local homeName = table.concat(args, " ", 2)
  if not target or homeName == "" then
    return print("Uso: /tirarcasa <user_id> <home_name>")
  end

  local result = exports['ds-homes']:removeHome(target, homeName)
  if result.success then
    print(("Casa '%s' removida de %d"):format(homeName, target))
  else
    print("Falha: " .. result.message)
  end
end, true)

A remoção é irreversível. Mobília, báu, financiamento ativo e aluguéis vinculados à casa também são apagados junto.

Exports

owned[] — casas próprias

financing[] — financiamentos

renting[] — aluguéis ativos

resident_in[] — onde é morador

On this page