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,
Eplaces it,Backspacecancels). You must stand outside, on foot, withincameras.placeDistance(6 m) of the spot, and the spot must be withincameras.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
Eat it, Watch cameras; at most 2 per model). You need thesecuritypermission. Controls: drag the picture or use the arrow keys /WASDto look around (insideview.yawLimit,pitchMin,pitchMax), mouse wheel or+/-to zoom (fovMintofovMax),Q/Eto switch camera,1to4to pick a filter (CCTV, night vision, mono, clear),Escto leave. A view ends afterview.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; setfalseto 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 byview.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
securitywho comes withincameras.motionRadiusof 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(adefaultentry covers every model). They are estimates and may need tuning for your server.
Alarm
- Install it in Tablet > My properties > Security > Install alarm (
alarm.price, default 7,500, charged toConfig.MoneyAccount). Owner, tenant or asecuritymember 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. - Set a PIN (
alarm.pinLength, 4 to 6 digits). The PIN is only needed by people who do not havesecurity; it is stored salted and hashed and never sent back to anyone. Without a PIN onlysecuritymembers can use the keypad. - Arm from the tablet, or from the keypad. The alarm is arming for
alarm.exitDelayseconds (default 30) so everyone can leave, then armed. When you arm it, the tablet warns how many people withoutsecurityare still inside. - 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 withsecurityarm and disarm without typing a PIN. Everyone else types the PIN:alarm.wrongPin.maxwrong tries withinwindowseconds lock that character out of that property's keypad forlockoutseconds (default 3 tries, 300 s, 300 s); while the alarm is armed, the lockout also sets it off (wrongPin.trigger). - 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.rangemetres of the entrance (volume falls with distance,siren.volume) and at the fullsiren.volumeinside the property, with a flashing red light (siren.lights,siren.lightRange). - The owner and the
securitymembers get a critical notification in the tablet's notification center with a link to the Security tab (alarm.notify). - With
alarm.dispatchon, police are alerted through the same adapter as house robberies (Config.Robbery.dispatch), at most once per property peralarm.dispatchCooldownseconds (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)