Aller au contenu
ATY ScriptsDocsHousingHome security

Home security

aty_housing: Home security

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

Home security

Owners can fit a property with CCTV cameras, an alarm with a keypad, and a camera at the front door. Everything is checked on the server. Config.Security.enabled = false switches the whole feature off; cameras.enabled, alarm.enabled, doorCam.enabled and keypad.enabled switch the parts off separately.

New key permission security: view the cameras, arm and disarm the alarm without a PIN, set the PIN, buy the alarm, place, rename and remove cameras, read the security history. The owner or tenant always has it, the co-owner preset has it, roommate and guest do not. A co-owner key saved before this feature gets security automatically; other roles do not. Tick or untick it in the tablet's access matrix like any other permission.

Cameras

Kind How you get it Limit per property
Indoor camera (IPL / shell) Place a Security Camera from the Decor Studio catalog (Electronics > Security; five models, 1,200 to 1,500 each) inside the property Config.Security.cameras.maxPerTier: { 2, 4, 6 } for low, mid and high tier interiors
Indoor camera (MLO) The same catalog items, placed anywhere inside the MLO area cameras.mloMax (default 6)
Outdoor camera Tablet > My properties > Security > Place outdoor camera, at the entrance (any property type), cameras.exteriorPrice (default 1,500) cameras.maxExterior (default 2)
  • Indoor cameras are furniture: place, move and remove them in the Decor Studio like any other piece (the Studio refuses a camera over the limit). Rename them and switch their motion sensor in the Security tab.
  • Outdoor cameras are placed from the tablet: the tablet hides, you aim at a surface (arrow keys rotate the camera, E places it, Backspace cancels). You must stand outside, on foot, within cameras.placeDistance (6 m) of the spot, and the spot must be within cameras.exteriorRadius (12 m) of the entrance (for an MLO: anywhere in its area). The price is not refunded when you remove the camera in the Security tab. A police seal blocks placing.
  • Watching: Tablet > My properties > Security > Watch cameras / View, or a Security Monitor / CCTV Monitor piece from the Decor Studio (press E at it, Watch cameras; at most 2 per model). You need the security permission. Controls: drag the picture or use the arrow keys / WASD to look around (inside view.yawLimit, pitchMin, pitchMax), mouse wheel or + / - to zoom (fovMin to fovMax), Q / E to switch camera, 1 to 4 to pick a filter (CCTV, night vision, mono, clear), Esc to leave. A view ends after view.maxSeconds (default 300), when you take damage, die, ragdoll or lose the permission, when a seal is placed, or when the camera is removed. You cannot start a view in a vehicle.
  • Where you can watch from: an indoor camera of an IPL or shell property can only be watched from inside that same property. Outdoor cameras, MLO cameras and the door camera can be watched from anywhere in the open world. When you watch one of those from inside an IPL or shell property, the server moves you to the open world for the duration of the view (view.worldFromInstance, on by default; set false to refuse instead): your character stays where it is, frozen, invincible and invisible, and you are put back when the view ends. In any other situation (for example while in jail or on the character selection) the view is refused.
  • Far cameras: while you watch one that is more than 300 m away, your streaming radius is raised to the distance plus view.cullingExtra (capped by view.cullingMax), so players near the camera show up. Not verified on a live server.
  • Motion sensor (per camera, Security tab): with the alarm armed, a player without security who comes within cameras.motionRadius of a camera whose sensor is on sets the alarm off. New indoor cameras have it on, new outdoor cameras off.
  • Camera model and angle: the lens position and tilt per prop model are in cameras.models (a default entry covers every model). They are estimates and may need tuning for your server.

Alarm

  1. Install it in Tablet > My properties > Security > Install alarm (alarm.price, default 7,500, charged to Config.MoneyAccount). Owner, tenant or a security member can buy it. It belongs to the property: it stays after a sale, but the PIN is cleared and the alarm is disarmed for the new owner.
  2. Set a PIN (alarm.pinLength, 4 to 6 digits). The PIN is only needed by people who do not have security; it is stored salted and hashed and never sent back to anyone. Without a PIN only security members can use the keypad.
  3. Arm from the tablet, or from the keypad. The alarm is arming for alarm.exitDelay seconds (default 30) so everyone can leave, then armed. When you arm it, the tablet warns how many people without security are still inside.
  4. Keypad: at the entrance prompt the entrance card has a Keypad button; inside the property, the exit prompt has the keypad as its second action (default G, rebindable). Members with security arm and disarm without typing a PIN. Everyone else types the PIN: alarm.wrongPin.max wrong tries within window seconds lock that character out of that property's keypad for lockout seconds (default 3 tries, 300 s, 300 s); while the alarm is armed, the lockout also sets it off (wrongPin.trigger).
  5. Disarm the same ways (disarming also stops a sounding siren).

What sets the alarm off (each switchable in alarm.triggers):

Trigger When Default
forced A robber wins the lock-pick game on the door on
policeBreach Police force the door with a raid (an open-door raid never triggers) off
entry A player without security enters while it is armed: they get alarm.entryDelay seconds (default 20) with a countdown and a beep to disarm at the keypad, otherwise it sounds. Doorbell guests, robbers and police have their own rules on
doorUnlock MLO door unlocked by a player without security while armed (same entry delay) on
motion A player without security near a camera with its motion sensor on (checked every alarm.motionCheckMs) on

Entering with a key is not an alarm by itself for security members: they walk in and may disarm in peace. Previews, doorbell guests (let in by a member) and, for MLO, guests holding a doorbell pass never set off the motion sensor.

When the alarm sounds (alarm.sirenSeconds, default 120; afterwards it stays armed and cannot sound again for alarm.retriggerSeconds, default 60):

  • A siren (synthesized in the UI, no game audio needed) plays for everyone within alarm.siren.range metres of the entrance (volume falls with distance, siren.volume) and at the full siren.volume inside the property, with a flashing red light (siren.lights, siren.lightRange).
  • The owner and the security members get a critical notification in the tablet's notification center with a link to the Security tab (alarm.notify).
  • With alarm.dispatch on, police are alerted through the same adapter as house robberies (Config.Robbery.dispatch), at most once per property per alarm.dispatchCooldown seconds (default 300).
  • Robbery interaction: an alarm that sounds during a robbery cuts the robbery's remaining time down to alarm.robbery.lootSeconds (default 90, it only ever shortens) and switches the robbers' alarm on. A robbery that starts while the alarm already sounds starts with the same cut. A robber who forces the door while the alarm is disarmed gets no siren; the attempt is only written to the history.
  • A police seal disarms and silences the alarm and blocks arming and watching until the seal is lifted.

The Security tab also shows the armed-by name and time, the exit and entry delays, the history (last 30 events of alarm.logKeep, default 100, per property) and who is inside without the permission.

Door camera

When a visitor rings the doorbell, the ring card of the people inside gets a Camera button (key H by default, Config.Doorbell.keys.camera) that opens the live view of the property's door camera with Let in and Ignore buttons. The door camera is the outdoor camera marked as door camera in the Security tab (one per property), otherwise the first outdoor camera; for an MLO also an indoor camera marked as door camera. With doorCam.virtual = true a property without any camera shows a view from the entrance point instead; otherwise there is no Camera button. Who may watch: players who hold doorCam.permission (default enter) and either got the ring card or have security, only while the ring is pending. The tablet's Security tab shows a Someone is at the door banner during a ring.

Configuration (Config.Security)

Option Type Default Description
enabled boolean true Whole feature on or off
cameras.enabled boolean true Cameras on or off (the Studio refuses camera furniture while off)
cameras.maxPerTier table { 2, 4, 6 } Most indoor cameras of an IPL or shell property for low, mid and high tier interiors
cameras.mloMax number 6 Most cameras of an MLO property
cameras.maxExterior number 2 Most outdoor cameras per property
cameras.exteriorRadius number 12.0 An outdoor camera must be within this many metres of the entrance (MLO: or inside its area)
cameras.exteriorModel string 'prop_cctv_cam_01a' Prop model of outdoor cameras
cameras.exteriorPrice number 1500 Price of an outdoor camera (0 = free)
cameras.placeDistance number 6.0 The player must stand this close to the spot while placing
cameras.motionRadius number 6.0 Motion sensors react to players this close (metres)
cameras.models table measured entries for the 5 catalog cameras; default = { lens = { x = 0.0, y = -0.3, z = 0.0 }, yaw = 180.0, pitch = -20.0 } Lens offset (metres from the prop), yaw offset and tilt per prop model; add an entry per model name to override default
view.maxSeconds number 300 A live view ends after this many seconds
view.worldFromInstance boolean true Allow watching outdoor / MLO / door cameras from inside an IPL or shell property (the player is moved to the open world during the view)
view.yawLimit number 70.0 Most degrees to look left or right of the camera's own direction
view.pitchMin / view.pitchMax number -60.0 / 15.0 Look-down and look-up limits
view.fovMin / view.fovMax / view.fovDefault number 20.0 / 70.0 / 55.0 Zoom range and start value (field of view in degrees)
view.filters table { cctv = 'CAMERA_secuirity', bw = 'CAMERA_BW' } Timecycle modifiers of the CCTV and mono filters (the night filter is night vision)
view.cullingExtra number 150.0 Extra metres added to the streaming radius for far cameras (0 = off)
view.cullingMax number 1000.0 Highest streaming radius used for a view
view.snapshots boolean true Preview image per camera in the tablet: the last frame a member with security watched (needs screenshot-basic; without it the list shows icons)
view.snapshotEvery number 120 Seconds before a camera's preview may be taken again
alarm.enabled boolean true Alarm on or off
alarm.price number 7500 Price of the alarm
alarm.pinLength table { 4, 6 } Shortest and longest PIN (digits)
alarm.exitDelay number 30 Seconds between arming and armed
alarm.entryDelay number 20 Seconds a player without security has to disarm after coming in (0 = sounds at once)
alarm.sirenSeconds number 120 How long the siren sounds
alarm.retriggerSeconds number 60 After the siren stops, the alarm cannot sound again for this long
alarm.wrongPin table { max = 3, window = 300, lockout = 300, trigger = true } Wrong PIN tries, the window they count in, the keypad lockout (seconds) and whether the lockout sets off an armed alarm
alarm.triggers table { forced = true, policeBreach = false, entry = true, doorUnlock = true, motion = true } Which events set the alarm off
alarm.motionCheckMs number 2000 How often motion sensors are checked
alarm.notify table { owner = true, security = true } Who is notified when it sounds
alarm.dispatch boolean true Alert police through the robbery dispatch adapter
alarm.dispatchCooldown number 300 Seconds between two police alerts of one property
alarm.robbery.lootSeconds number 90 Remaining robbery time when the alarm sounds during a robbery (0 = no cut)
alarm.siren table { range = 60.0, volume = 0.6, lights = true, lightRange = 14.0 } Siren hearing range (metres), volume (0 to 1), flashing red light on or off, light range
alarm.logKeep number 100 Security history rows kept per property
doorCam.enabled boolean true Door camera on or off
doorCam.permission string 'enter' Permission needed to watch the door camera of a pending ring
doorCam.virtual boolean false Show a view from the entrance when the property has no camera
keypad.enabled boolean true Keypad on or off (the alarm can then only be armed from the tablet)

The security tables (aty_housing_upgrades, aty_housing_security, aty_housing_security_cams, aty_housing_security_camset, aty_housing_security_log, aty_housing_security_snaps) are created automatically.

Integration

Server exports (propertyId = the property's numeric id; see Server exports):

Export Returns
GetSecurityState(propertyId) { installed, mode, cameras }; mode is 'none' (no alarm), 'off', 'arming', 'armed' or 'sounding'; cameras = how many. nil for an unknown property or when home security is off
SetAlarmArmed(propertyId, armed) true, message or false, reason. Arms (true) or disarms (false) without any permission or PIN check (the calling resource decides); written to the history as api. Fails when there is no alarm, the property is unowned, or (arming) sealed
TriggerAlarm(propertyId, reason?) true or false, reason. Sets off an armed alarm, for example from a glass-break sensor of another resource. reason is a short word for the history (letters, digits, underscore, 24 characters at most; default 'api')
GetSecurityCameras(propertyId) [{ key, kind, space, label, x, y, z, heading }] (kind = 'studio' or 'exterior', space = 'world' or 'instance', position = the lens), or nil
HasSecurityUpgrade(propertyId, name?) The upgrade's level, 0 = not installed. name defaults to 'alarm'

Server events (listen with AddEventHandler only):

Event Arguments
aty_housing:alarmTriggered (propertyId, reason, charId); reason is forced, police, entry, door, motion, tamper or the word given to TriggerAlarm; charId is the intruder when known, else nil
aty_housing:alarmChanged (propertyId, state, charId); state is off, arming, armed or sounding

Hooks (RegisterHook):

Hook data Behaviour
canArm { source, propertyId, charId, armed } Before a player arms (armed = true) or disarms (false) from the tablet or the keypad. Return false, message to refuse. Not asked for the SetAlarmArmed export
onAlarm { propertyId, reason, charId, source } After the alarm started to sound, on its own thread. Cannot veto
-- Add your own dispatch when a house alarm goes off:
AddEventHandler('aty_housing:alarmTriggered', function(propertyId, reason, charId)
    local prop = exports.aty_housing:GetProperty(propertyId)
    if prop then exports['my_dispatch']:Alert(prop.entrance, ('House alarm: %s (%s)'):format(prop.label, reason)) end
end)

-- Arm property 12 from your own script (no permission or PIN check):
exports.aty_housing:SetAlarmArmed(12, true)