Burglary System

How it worksCopy Anchor Link

When a locked home's door is picked open by a robber, the system temporarily turns the interior's placed furniture into searchable ransack spots.

1. Forced Entry: A lockpick success opens a timed ransack window.
2. Search Spots: The robber enters and approaches placed furniture items inside.
3. Looting: Robbers search the spots (progress bar) to find items, valuables, or cash.
4. Security Alert: Searching can trigger the property/housing unit's installed security alarms and alert police.
5. Cooldown: The property/housing unit goes on a lock-out cooldown to prevent refarming the same home.

Configuration Reference (shared/burglary.lua)Copy Anchor Link

The entire system is customized in the configuration file shared/burglary.lua.

Config.Burglary = {
    Enabled = true,

    -- Methods that open a looting session
    OpenOn = {
        lockpick = true,
        raid     = false, -- Lawful police raids don't turn officers into looters
    },

    -- How long the session stays open (seconds)
    OpenWindow = 900,

    -- Anti-refarm cooldown (seconds)
    Cooldown = 10800, -- 3 hours

    -- Maximum searchable furniture pieces per session
    MaxSpots = 6,

    -- Search action parameters
    SearchTime   = 6000, -- progress-bar duration (ms)
    SearchRadius = 2.5,  -- max distance from furniture to search (meters)
    RequireItem  = false, -- item required to search (e.g., 'lockpick')

    -- Loot rolls
    RollsPerSpot = 1,
    EmptyChance  = 0.35,

    -- Loot table (item name, min/max count, chance)
    Loot = {
        { item = 'money',    min = 25, max = 300, chance = 0.45 },
        { item = 'phone',    min = 1,  max = 1,   chance = 0.10 },
        { item = 'lockpick', min = 1,  max = 2,   chance = 0.10 },
        { item = 'goldbar',  min = 1,  max = 1,   chance = 0.03 },
        { item = 'rolex',    min = 1,  max = 1,   chance = 0.04 },
    },

    -- Trigger the alarm/police dispatch on searches
    AlertOnSearch = true,
}

Core MechanicsCopy Anchor Link

1. Placed Furniture DependencyCopy Anchor Link

Ransack spots are drawn directly from the property/housing unit's placed furniture list. Up to MaxSpots (default 6) pieces of placed furniture are randomly chosen as loot targets.

• Bare Homes: If a home is completely empty (no furniture placed), no search spots will spawn. This encourages targeting furnished, active player houses.

2. Anti-Refarm CooldownCopy Anchor Link

Once a property/housing unit has been burglarized:

• The cooldown (Cooldown, default 3 hours) is stamped onto the database row (burglarized_at in the kp_properties table).
• Since the cooldown is persisted database-side, a server restart cannot be used to bypass the cooldown or reopen a home that was recently cleaned out.

3. Alarm AlertsCopy Anchor Link

If AlertOnSearch is set to true:

• Searching a furniture spot sends a break-in signal to the Security Subsystem.
• The property's alarm tier determines whether it causes a local alarm ring, issues a silent police dispatch, or alerts the property owner's tablet/phone.