qbx_properties — Manual

Tela de escolha do apartamento inicial: um quadro de seleção em scaleform que o novo personagem usa para escolher onde vai morar; a criação da propriedade é delegada ao ps-housing.

Sumário

1. Estado do recurso
2. Dependências
3. Instalação
4. Configuração
5. Fluxo de uso
6. Controles
7. Banco de dados
8. Entrypoints para outros recursos
9. Localização
10. Estrutura de arquivos

Estado do recurso

Este é um fork em que o fxmanifest.lua carrega apenas client/apartmentselect.lua. Todos os demais scripts (o restante do client/ e o server/ inteiro) estão comentados no manifesto e não rodam:

Na prática, o recurso hoje entrega só a tela de seleção de apartamento e repassa a criação para o ps-housing. Compra, aluguel, corretor, decoração e stashes ficam por conta do ps-housing — as tabelas e o config correspondentes seguem no repositório para uso futuro.

Dependências

Instalação

1. Copie a pasta qbx_properties para resources/.
2. Adicione ao server.cfg:

   ensure qbx_properties
3. Alguém precisa disparar apartments:client:setupSpawnUI no cliente do jogador novo (no fluxo atual, o ps-housing). O script de servidor que fazia isso está desativado.
4. Os SQLs (property.sql, decorations.sql) não são necessários com o manifesto atual — só importe se reativar os scripts de servidor.
5. Conflitos — o README do upstream orienta remover qbx_apartments e qbx_houses de uma build limpa do QBox.

Configuração

config/shared.lua

O quadro monta a tela em blocos de 3 opções e as ramificações do código cobrem no máximo 6 entradas em apartmentOptions. Passar disso quebra a navegação.

config/client.lua

config/server.lua

Este arquivo só é lido pelos scripts de servidor, hoje desativados.

Fluxo de uso

1. Ao receber apartments:client:setupSpawnUI, o cliente teleporta e congela o personagem em frente ao quadro, monta a câmera e carrega o scaleform AUTO_SHOP_BOARD (streamado por este recurso).
2. Se apartmentOptions tiver apenas uma opção, a seleção é pulada e o apartamento é confirmado direto.
3. O jogador navega pelas opções e confirma; um lib.alertDialog pede a confirmação final.
4. Confirmado: a tela escurece, o personagem é movido para o ponto de entrada do apartamento e o cliente dispara ps-housing:server:createNewApartment com o label do apartamento escolhido.
5. Em seguida, QBCore:Server:OnPlayerLoaded e QBCore:Client:OnPlayerLoaded são disparados para o jogador terminar de carregar (roupas, etc.).

A lista efetivamente usada na navegação e na confirmação vem do evento ps-housing:setApartments; os textos exibidos no quadro (label e descrição) vêm de sharedConfig.apartmentOptions. Mantenha as duas listas na mesma ordem.

Controles

Válidos apenas enquanto o quadro de seleção está aberto.

Banco de dados

Os SQLs abaixo pertencem aos scripts de servidor desativados. Só importe se for reativá-los.

Entrypoints para outros recursos

Evento apartments:client:setupSpawnUI

Abre o quadro de seleção de apartamento no cliente do jogador. É o ponto de entrada do recurso.

-- servidor
TriggerClientEvent('apartments:client:setupSpawnUI', playerSource)

Evento ps-housing:setApartments

O recurso escuta este evento para receber a lista de apartamentos usada na navegação e na confirmação.

-- cliente
TriggerEvent('ps-housing:setApartments', apartments)

Função global CalculateOffsetCoords (shared)

Aplica um offset às coordenadas de uma propriedade, descontando shellUndergroundOffset do Z.

local coords = CalculateOffsetCoords(propertyCoords, offset) -- retorna vec4

Localização

Strings via ox_lib locale, em locales/:

en, pt-br, pt, es, fr, de, nl, da, ro

Idioma ativo pela convar:

setr ox:locale "pt-br"

Com o manifesto atual, apenas as chaves instructButtons.* e alert.apartment_selection / alert.are_you_sure são usadas; as demais pertencem aos scripts desativados.

Estrutura de arquivos

qbx_properties/
├── client/
│   ├── apartmentselect.lua   — ATIVO: quadro de seleção, câmera, scaleform e confirmação
│   ├── property.lua          — desativado no fxmanifest: entrar/sair, chaves, campainha, menu de gestão
│   ├── realtor.lua           — desativado no fxmanifest: criação de propriedades pelo corretor
│   ├── decorating.lua        — desativado no fxmanifest: colocação de móveis com gizmo
│   └── dataview.lua          — desativado no fxmanifest: helper de leitura binária
├── server/
│   ├── apartmentselect.lua   — desativado: inseria a propriedade em `properties` e criava o stash
│   ├── property.lua          — desativado: entrada/saída, keyholders, stashes
│   ├── realtor.lua           — desativado: criação/venda de propriedades
│   └── decorating.js         — desativado: usado só para gerar os screenshots dos móveis
├── config/
│   ├── shared.lua            — apartmentOptions, interiors, shellUndergroundOffset
│   ├── client.lua            — catálogo de móveis
│   └── server.lua            — slots e peso do baú do apartamento
├── shared/
│   └── main.lua              — CalculateOffsetCoords
├── stream/
│   ├── auto_shop_board.gfx   — scaleform AUTO_SHOP_BOARD do quadro de seleção
│   ├── auto_shop_board.ytd
│   └── auto_shop_board_img.ytd
├── screenshots/              — imagens dos móveis (usadas pela UI de decoração desativada)
├── locales/
│   ├── en.json
│   └── da / de / es / fr / nl / pt / pt-br / ro .json
├── property.sql              — tabela `properties`
├── decorations.sql           — tabela `properties_decorations`
└── fxmanifest.lua