İçeriğe geç
ATY ScriptsDokümanlarHousingApartments, buildings and motels

Apartments, buildings and motels

aty_housing: Apartments, buildings and motels

Overview · Installation · Configuration · Features and commands · Living · Home security · Economy, upgrades and the player market · Furniture, lighting and yards · Apartments, buildings and motels · Exports and events · Webhooks and migration · Troubleshooting

Apartments, buildings and motels

A building is one shared entrance (a lobby, and optionally a stop for each floor) with many units. Every unit is a normal property: its own interior, owner, keys, stash, decor, finance, upgrades, security, police and robbery rules, and (for apartments) the player marketplace. The building adds one map blip, one prompt with a unit directory, an elevator and two optional modes: a motel (rooms rented by the night) and a starter apartment for new characters. Admins create buildings in game with /housingbuilding; there is no file to edit. The options are in Config.Buildings in shared/config.lua. Config.Buildings.enabled = false switches the whole feature off (no directory, motel or starter mode).

For players

Walk to a building (map blip Apartment buildings) and use its prompt: E at the marker, or the target eye, labelled Directory. The directory opens when you stand within interactRange of the lobby or a floor stop and closes when you walk away, die or go inside.

  • Directory. Units by floor with a search box (unit number or the resident's name) and the filters All, Available and Mine. Each unit shows its state: yours, rented by you, a key, for sale, for rent, for sale or rent, a free motel room, occupied or not available, plus Sealed and Open house now badges and the prices. Occupied units show the resident's tablet display name when directory.showNames is on and the resident set one.
  • Unit actions. Enter (your own units, or an owned unit that is unlocked), Visit (a timed preview of a unit on the market, when Config.AllowPreview is on), Ring the doorbell of an occupied unit, Details (the normal property card, where you buy, rent or take a loan), Waypoint, and in a motel Check in, Extend and Check out.
  • Elevator. A building with floor stops (the Elevator stop of a floor, set by an admin) lists its floors; Go fades the screen and takes you to the lobby or that floor's landing. You cannot use it in a vehicle. With elevator.restricted = true you may go to a floor only when you hold a unit or a key there, a unit there is on the market, a motel room there is free, the floor has no units, or you are police, a realtor or an admin. Leaving a unit puts you back at the lobby or the landing of its floor.
  • Units look like any other listing in the tablet's Explore tab (the unit's own entrance prompt, zone and blip are hidden; the building's point is used). Buying, renting, loans, keys, the stash and the Decor Studio work as everywhere else.

Motels

In a motel building every room is rented by the night, at a price per night set on the building. The reception is the directory at the lobby.

  1. Check in. Choose First free room (lowest floor and number) or a specific free room, pick the number of nights (1 up to the longest stay) and confirm. The price is the nightly price times the nights, charged to Config.MoneyAccount. You become the tenant, the room is locked, its stash is new and the stay ends at the paid time. Rooms are only rented at the reception (a room cannot be bought, rented or listed any other way), and the usual checks apply: ownership limits, the canBuy hook and police seals.
  2. Extend. Pay for more nights in the directory. The stay can never run longer than the longest stay from now. The weekly rent of the tablet is not used for motel rooms.
  3. Warning. warnMinutes before the end the tenant gets a notification.
  4. End. When the paid time is up the stay ends at once, with no grace period: everyone inside is moved out, the room is free again, the stash is emptied when motel.clearStash is on (aty_inventory only; with other inventories the items stay under the old stash id) and the tenant is notified. A sealed room waits until the seal is lifted. Check out ends the stay earlier, with the normal end-of-rental rules (the prepaid nights are not refunded).
  5. Room key item. With motel.keyItem set to an item name, check-in gives that item (its metadata holds the room, the building and the end time) and the end of the stay removes one; with requireKeyItem = true the tenant and key holders also need it in the inventory to go in (canEnter hook, message You need the room key). The item must exist in your item list.

Starter apartments

With starter.enabled = true a new character gets a free unit in a starter building at its first login. Characters that existed before never get one, even without a home. Tick Starter building on an apartment building in the manager (a motel cannot be one). The unit is the first vacant unit (lowest floor and number) of the first starter building that has one, not an MLO, not sealed, with its interior present.

How a new character is recognised: no framework marks a newly created character, so on its first start aty_housing writes a list of every character that exists (qb-core players.citizenid, es_extended users.identifier; set starter.characterTable and starter.characterColumn if your framework table has another name) into aty_housing_characters, and the console says so once. A character that logs in later and is not on that list was created afterwards: that is its first login. Logins are seen through qb-core's QBCore:Server:PlayerLoaded and a check of the online players every few seconds (any framework). If the list cannot be written (unknown framework, wrong table name) nothing is tracked and no starter is given; the console says why. A character whose first login happens while starter mode is off does not get a unit later. The spawn selector (GetSpawnPoints) only reads.

  • tenure = 'owned': the unit is the character's own for free (a sell-back pays nothing); 'rented': the rent is prepaid for freeDays days, then the unit's normal rent applies.
  • onlyWithoutHome = true: only characters that own no property and hold no key. The unit becomes the "wake up here" spawn with spawnDefault = true. A welcome notification is sent.
  • Each character gets one starter unit, ever (table aty_housing_building_starters), even if they give it up later. When no vacant unit exists at the first login the character is owed one: it is given at a later login once a unit is vacant (or when a script calls EnsureStarterApartment), unless the character has a home by then. The console says so once per character and session.
  • Ownership limits and the canBuy hook (via = 'starter', price 0) are respected.

Building manager (admins)

/housingbuilding opens the manager for housing admins (Admin permission); from the server console it prints every building (id, name, type, floors, units, owned). Tabs: Units, Floors and Settings.

  • Create. Stand at the lobby and choose New building: name, type (Apartments or Motel), number of floors and units per floor (0 is allowed), numbering (By floor 101, 102... or In order 1, 2, 3...), the unit word (default Apt, for a motel Room), the unit interior (an IPL or shell from the catalog, present on your server), sale and rent price (a motel: the price per night and the longest stay), stash size, map blip, Utilities included and Starter building. The lobby must keep Config.Creator.minEntranceDistance (2 m) from every other property entrance and interactRange plus 1 m from the points of other buildings. Units are created one by one through the normal creator (so audit, listing data and furniture sets run as usual), named <building> <word> <number>; progress shows in the manager and one building generates at a time. If it stops, Add units finishes it.
  • Floors. Elevator stop: stand at the landing of a floor and set it (or clear it). A building with at least one stop has an elevator. Units of that floor move to the landing; the lobby can be moved too and the units without a stop follow it.
  • Units. Add units to a floor, Bulk edit the vacant units of a floor or all (sale price, rent price, interior; owned and MLO units are skipped), Attach property (any existing property, an MLO included, joins at a floor and number; an MLO keeps its own doors and entrance), Detach (the unit becomes a normal property), Remove (deletes a vacant unit), Open in creator.
  • Settings. Name, type, floors, numbering, unit word, price per night and longest stay (capped by motel.maxNights), map blip, Utilities included (the units get no power, water or service bills; property tax stays) and Starter building. A unit's own entrance stays on its building point: the creator refuses to move it. Changing the type needs every unit to be vacant, and a building that becomes a motel takes its vacant rooms off the sale and rent market. Floors can be removed only when empty.
  • Delete. Vacant units are deleted with the building. Owned units block the delete unless you choose Keep units as properties. Teleport takes you to the lobby.

Building configuration (Config.Buildings)

All keys are in Config.Buildings (shared/config.lua).

Option Type Default Description
enabled boolean true false = no buildings, no directory, motel or starter mode
adminCommand string 'housingbuilding' Admin command that opens the building manager ('' = none)
interactRange number 2.0 Metres from a building point for the directory
maxFloors number 60 Most floors of one building (read as 1 to 200)
maxUnitsPerFloor number 40 Most units on one floor (1 to 200)
maxUnits number 400 Most units in one building (1 to 2000)
marketplace boolean true Apartment units may be listed on the player marketplace. Motel rooms never
blip table { sprite = 40, color = 0, scale = 0.8 } Default map blip of a building (a building can turn its own off). Your own buildings use Config.Blips.owned
directory.showNames boolean true Occupied units show the resident's tablet display name
elevator.restricted boolean true false = the elevator goes to every floor. true = see For players
elevator.fadeMs number 400 Screen fade of an elevator ride in milliseconds (0 to 3000)
motel.nightSeconds number 86400 Length of one night in seconds (60 to 30 days)
motel.maxNights number 7 Longest stay in nights (1 to 60); a building may set a lower value
motel.warnMinutes number 30 Notice before a stay ends (0 = none)
motel.checkMinutes number 1 How often stays that ended are checked
motel.keyItem string or false false Item name given at check-in (false = none)
motel.requireKeyItem boolean false The tenant and key holders need the item to go in
motel.clearStash boolean true The room stash is emptied when a stay ends on its own (aty_inventory only)
starter.enabled boolean false New characters (first login) without a home get a unit in a starter building
starter.tenure string 'owned' 'owned' (free) or 'rented' (freeDays prepaid, then the unit's rent)
starter.freeDays number 7 Prepaid days of a rented starter unit (1 to 365)
starter.onlyWithoutHome boolean true Only characters without a property or key
starter.spawnDefault boolean true The starter unit is the "wake up here" property
starter.characterTable / characterColumn string not set Table and id column of your framework's characters, for the list of existing characters (set both, plain names). Not set = qb-core players / citizenid, es_extended users / identifier

Per building (set in the manager, stored in the table aty_housing_buildings): name, type, floors and stops, numbering, unit word, price per night, longest stay, utilities included, starter, map blip. Units are rows of aty_housing_building_units; the starter ledger is aty_housing_building_starters. Deleting a unit's property removes it from the building.

Building integration

Server exports:

Export Returns
GetBuildings() Array of { id, label, mode ('apartment' or 'motel'), points = { { floor, x, y, z, w } }, blip, floors, elevator }; points are the lobby (floor = 0) and every floor stop, blip is { sprite, color, scale } or false. {} while not ready or off
GetBuildingOfProperty(propertyId) { id, label, mode, floor, number } of the building a unit belongs to, or nil
EnsureStarterApartment(charId) The property id given to the character right now, or nil (starter mode off, nothing to do or no vacant unit). Safe to call often; GetSpawnPoints calls it too

Event (server-local, listen with AddEventHandler only): aty_housing:buildingChanged (buildingId, reason) after a building or one of its units changed. reason: checkin, extend, checkout, starter, updated, lobby, landing, generating, generated, bulk, attach, detach, unit_removed or deleted. Units are normal properties, so aty_housing:propertyChanged and aty_housing:ownerChanged fire for them too.

Hooks: units go through the normal hooks. canBuy and onPurchased carry via = 'motel' for a check-in (the price is the stay's total, tenure = 'rented') and via = 'starter' for a starter unit (price 0). canEnter refuses a tenant without the room key when requireKeyItem is on. canMarketList refuses motel rooms, and apartment units when marketplace = false. A motel room can be acquired only by check-in: any other purchase is refused.