Lumo Housing

Shells, interiors and MLO homes: buy, rent, keys, furniture, mortgages and police raids.

Version 1.2.2 · Frameworks QBCore · Qbox · ESX · standalone · Requires oxmysql

Installation · Config files · Exports & events · Changelog

Player housing for FiveM. Homes can be shells, base-game interiors or real MLO doors. Players can buy, rent, resell, hand out keys and furnish them. Admins create houses in game. QBCore, Qbox, ESX Legacy and standalone, detected automatically.

Version 1.1.0 adds realtor workflows, utilities, residents, auctions, security, living features and home showcases.

Install guide per framework: Installation.

What players get

• Realestate browser (/houses or a realestate office). It is a board of every listing, with its distance and compass direction from you, price, rent and interior. Listings without a photo get generated blueprint art.
• Buying. A deed shows the list price, tax and broker fee, and you hold to sign. Money comes from bank, then cash (Config.Payment).
• Renting. Houses the creator marks as rentable are paid per period. Rent can be taken automatically, and a tenancy ends after a grace period unpaid.
• Selling. Sell back to the bank for a share of the list price, or list the home for other players (with a floor price). The seller is paid even when offline.
• Mortgages. Choose "Finance" on the deed and pay only the deposit, tax and fees. The rest, plus interest, is paid in instalments taken from the owner's account. If an instalment stays unpaid past the grace period, the bank takes the home back. A mortgaged home cannot be listed or handed over, and selling to the bank takes the debt off the price.
• Storage upgrades. Owners buy bigger storage tiers (Config.Stash.upgrades). They stay with the home when it is sold to another player.
• Activity log. Residents see who used a key, who came in as a guest, who rang the bell, keys given and taken, and police raids.
• Police raids. Officers on duty with the right job and grade breach a locked door (Config.Raid). The owner is warned and the door stays unlocked. Officers inside can search the storage.
• Keys. Give keys to nearby players (up to Config.Keys.max) and take them back.
• At the door: enter, look inside (a tour) before buying, lock or unlock, ring the doorbell, and use the garage when the house has one.
• Inside: a home console at the bottom of the screen with storage, wardrobe, doorbell (let visitors in), leave, decorate and manage.
• Buildings with units. One entrance can hold up to 99 homes. The lobby shows a grid of units.
• Furniture (/decorate). There are about 120 base-game props. You place each one with a raycast tool that snaps to walls and shows the piece's box. A piece of kind storage, wardrobe or bed works like the home's own. Furniture stays with the home when it is sold or handed over. When the bank takes the home back, the owner gets sellBackPercent of the furniture's value. Also used by lumo-apartments for its flats.
• Building pieces. Doors, frames, windows, glass, partitions, walls, steps, stairs, rails and pillars for empty shells and MLOs. Any piece can be tilted (R picks the axis, Q levels it).
• Studio (Config.Decor). Paint, wallpaper and flooring drawn over a wall or floor you mark (36 tintable materials, priced per m²). Signs and pictures with text, a web image or an in-game photo (portraits), in frames or as neon. Lamps with colour, range and brightness, and one switch for every light in the home. Spotlights you aim, LED strips (steady, pulse, rainbow, flash), effects (fireplace, candles, steam, fog machine, fountains, sparks…, from data/effects.lua), a clock showing city time, and animated signs (pulse, flicker, scroll, rainbow). Colour variants for props that have them.
• Built-in furniture. Furnished MLOs and apartments can be cleared: pick objects one at a time or the whole room, and restore them later. Only the home's residents see the change.
• Doors one by one. MLO homes with several entrances lock each door on its own, with Lock all / Unlock all in Manage.
• Your layout. The decorate panel docks left, right (full height), top or bottom (a full-width strip, so your character stays in view). The HUD and minimap hide while a panel is open (Config.HideHud).

Interiors

Type	What it is	Copies
Shell	any shell model the server streams (data/shells.lua); unknown models are hidden	private copy per home (routing bucket)
Base-game interior	the interiors in data/interiors.lua	private copy per home
MLO	a real door in a map you run, locked through the game's door system; no teleport	the world itself, one home

Requirements

• oxmysql
• Optional, detected at runtime:
  • Interaction: lumo-interact, qb-target or ox_target. Without one, a built-in key prompt is used.
  • Storage: lumo-inventory, ox_inventory, qb-inventory, ps-inventory or lj-inventory.
  • Wardrobe: lumo-clothing, illenium-appearance or qb-clothing.
  • Garage: qb-garages.
  • Shell packs and MLO maps are sold by their creators and are not included.

Configuration

Everything is in config.lua:

• Framework, interaction, inventory, wardrobe and garage providers ('auto' by default).
• Admin groups and ACE, and the command names.
• Tax and broker fees, the bank buy-back, player listings, rent period and grace.
• Mortgage deposit, interest, number of instalments and grace.
• Police raid jobs and grades, duty, breach time and an optional item.
• Storage upgrade tiers and how long the activity log is kept.
• Keys, storage size, doorbell time, and the shell origin and bucket range.
• Furniture limits, blips and realestate offices.
• Studio (Config.Decor): tilt, lights, pictures and photos, allowed image hosts, surfaces and their price, hiding built-in objects and how many.
• Radial menu entries (Config.Radial) and the UI theme (Config.Theme).
• Realtor jobs that may use the house creator (Config.Realtor), and house tours (Config.Tour).
• Custom hooks if your inventory, wardrobe or garage is not listed.

Shells are in data/shells.lua, interiors in data/interiors.lua and the furniture catalogue in data/furniture.lua. Texts are in locales/en.lua.

Furniture pictures (optional). Put nui/src/furniture/<model>.webp next to the source and rebuild the UI (open-source edition). Only the files that exist are bundled. Pieces without a picture show their name.

Build kit

stream/ holds Lumo's own building pieces (lumo_hb_*): walls, walls with door and window openings, windows, door frames and doors, stairs, railings, floor slabs and trims. They are listed in data/buildkit.lua (prices, tabs, and which piece fits into which). Sizes follow a 0.5 m module and the placer's 0.25 m grid (X), so walls line up edge to edge; a window, frame, door or stair railing snaps into the wall, frame or stair it belongs to.

Commands

Command	Who	What
/houses	everyone	Open the realestate browser.
/decorate	residents	Furnish the home you are in.
/housecreator	admins	Create and edit houses.
/housecoords	Config.Debug	Print your position, for shells, interiors and offices.

Rename or turn off ('') the first three in Config.Commands.

For developers

• A home id is "<house name>:<unit>". Unit 0 is a house without units.
• Server exports (exports['lumo-housing']):
  • HasKey(identifier, nameOrHomeId)
  • CheckHasKey(license, citizenid, house, src) (the qb-garages signature)
  • GetHomes(identifier) returns { home, role }
  • IsInside(src)
  • StoreAllDecorations(apartmentName)
  • GetListings() returns { name, label, price, tier, owned, coords } for every home on sale
• Client exports: IsInside(), GetAccess(), OpenBrowser(), OpenDecorate(), SetWalkInHouse(name), OpenWalkInDecorate(name), getCurrentHouse(), getEnteredHouse().
• Client events for radial menus (while inside): lumo-housing:client:homeMenu, lumo-housing:client:leave, qb-houses:client:toggleDoorlock.
• Events other resources use:
  • Phone callbacks: qb-phone:server:GetPlayerHouses, GetHouseKeys, TransferCid and MeosGetPlayerHouses.
  • qb-houses:client:LastLocationHouse / enterOwnedHouse (spawn menus).
  • qb-garages:client:houseGarageConfig / setHouseGarage.
• Hooks you can listen to:
  • client: lumo-housing:client:entered / left (home id), lumo-housing:client:synced
  • server: lumo-housing:server:changed (house name)
• Tables:
  • lumo_houses, lumo_house_homes, lumo_house_keys, lumo_house_favorites, lumo_house_payouts, lumo_house_furniture, lumo_house_mortgages, lumo_house_upgrades and lumo_house_log.
  • With Config.Compat.qbHousesTables, houselocations and player_houses are mirrored for spawn menus and phones.
• Every framework call is in framework/server.lua and framework/client.lua.

Credits

Lumo — https://lumo-server.tebex.io/ Fonts: Barlow Semi Condensed, Barlow Condensed and Oxanium (SIL Open Font License). Icons after Lucide (ISC). Surface materials from ambientCG (CC0). See Third-party notices.

Home services (1.1.0)

• Realtors use /realtor or the office's Realtor desk option: viewing requests, market, open houses, bank auctions, commission earnings, and an admin audit log. Showings and door options are on J at the entrance (choose a unit in buildings).
• Manage has Bills, Security, Mail and Gallery tabs. Keys includes room rentals and co-owner invitations; the invited player must accept nearby. Co-owners manage the home and decorate; selling and handing over stay with the deed holder.
• The home console adds rest, safe, party, pets and visitor voting. Place cookers, speakers, TVs and planters from the catalogue and interact with them using E.
• Decorate → Room saves layouts, loads matching interiors at the saved cost, and applies free material styles. Loading adds furniture; it respects the piece limit.
• Open houses and parties show map blips. For-sale signs appear near listed homes; SOLD labels last Config.Signs.soldDays. Browser cards show galleries, auctions, last week's winning home and this week's top three.

Configure the matching Config.* blocks in config.lua. Bills, room rent and insurance reconcile at startup and every ten minutes; auctions and public entry flags reconcile every thirty seconds. Week boundaries use UTC Monday. Home data, layouts, bids and votes persist in MySQL. Insurance and room rent need a framework with money and inventory support. Standalone keeps its existing free-money policy.

Optional integrations: qb-minigames for Lockpick/SafeDial, lumo-emotes for rest and petting, ps-dispatch for alarm dispatch (on-duty police are also notified), screenshot-basic for gallery photos, and the configured phone/inventory adapters. Map recipe ingredients, outputs, seed items and watering cans to items in your inventory. Media uses HTTPS allowlisted hosts; YouTube and direct audio/video need network access and playable content in FiveM CEF. A TV with an unsupported tvscreen target is skipped. MLO guest voting and safe cracking require a configured interior boundary so the server can verify the visitor is inside. Shell/IPL homes use their server-owned instance.

Set lumo_housing_webhook as a server convar to mirror audit actions to Discord. The four service tables are created automatically and are mirrored in sql/install.sql. The weekly prize marker lives in the resource KVP store; preserve it alongside the DB.

The housing radial includes Manage home inside your home, in an accessible MLO, or within 5 m of your entrance. Home menu remains available inside shell/IPL homes.