Witnesses

Overview#

When a player commits a crime in town, a nearby townsperson sees it. They flinch, point and shout (or put their hands up if you are armed), then run. If they get far enough away and stay away long enough, they report it, and the on-duty law gets an alert with a blip, an area circle and a route to the spot. Stop the witness first and nobody hears about it.

When no lawman is on duty, an optional posse of NPC lawmen can ride in instead. Players can fight, flee or surrender to it.

• Crimes it notices: shooting (including a shot fired in town near nobody), threatening someone with a weapon, fist fights and melee, lassoing, trampling, stealing a horse or wagon, riding with a hogtied person, looting a body and poaching. Each one can be switched on or off and has its own chance.
• Law alerts say what happened, where (the town, or the nearest one) and at what time. The same crime by the same player alerts the law at most once a minute.
• Duty from your law script: ready-made settings for outsider_policeman, vorp_police, rsg-lawman, qbr-policejob and bcc-law, picked automatically, plus a custom option for any other duty script.
• Call commands for players: /callpolice, /calldoctor, /undertaker, /calltrain, and any you add for other jobs.
• Alerts for your other scripts: robbery, break-in, bounty, drug sale and more, fired by those scripts.
• Blips that wait until the responder arrives, if you want them.
• Where it works: only inside the towns you list, or everywhere, with areas where nothing is ever noticed (Sisika, Van Horn and Wapiti by default).
• NPC law response (off by default) and a built-in Sisika jail for NPC arrests (off by default).
• English, Spanish and French.

Requirements#

No database tables are needed. The built-in jail keeps its sentences in the resource's own server storage.

The NPC law response needs the server to allow entities made by players' games. With sv_entityLockdown set to strict or relaxed the posse cannot appear, and the server console says so.

Installation#

1. Install and start poggy_core and PolyZone.
2. Download Witnesses from your Cfx.re portal and put the poggy_witnesses folder in your resources folder.
3. In server.cfg, start it after poggy_core and PolyZone:

   ensure poggy_core
   ensure PolyZone
   ensure poggy_witnesses

4. Restart the server.
5. Check your law job names and grades (see Configuration), then type /witnessduty in the server console to see which duty script it found.

Coming from the old Witnesses folder

From 1.2.0 the folder is called poggy_witnesses.

1. Copy your settings out of the old config.lua and config_npc.lua (and translations.lua if you changed any text).
2. Delete the old Witnesses folder and put poggy_witnesses in its place.
3. In server.cfg, change ensure Witnesses to ensure poggy_witnesses.
4. Put your settings back: config.lua is now config/config.lua, config_npc.lua is now config/npc.lua, and translations.lua stays next to fxmanifest.lua.
5. If another script used exports.Witnesses:... or the witnesses:... server events, change them to exports.poggy_witnesses:... and poggy_witnesses:....

Configuration#

Every setting can be changed in game: type /poggy and choose Witnesses. Each setting has a description. Changes need a restart of the script, which the hub offers. Some settings only show with Show advanced on.

If you prefer editing files:

Witnesses (General tab)

Fleeing and reporting (Config.WitnessEscape):

Three optional keys can be added to Config.WitnessEscape by hand. All are on when left out: Reactions (flinch, point, shout or hands up before running), Shout (witnesses shout as they react and run) and IgnoreScriptPeds (NPCs that belong to other scripts, such as shopkeepers and job NPCs, never become witnesses).

Crimes

Each crime in Crimes witnesses notice (Config.Checks) has an on/off switch, a chance (percent) and the alert it sends.

Locations

To add a town in game: stand in the middle of it, open the Towns list, choose Add town, give it a name, use Use my position on Centre and set the radius. The town's name also picks the NPC lawmen for that town (see NPC law response below).

Law jobs and duty (Access & permissions tab)

The older Config.DutyExportCall (a line of Lua that returns true when on duty) still works while the preset is "auto" or "custom". It runs as code, so it can only be changed in the file.

Alerts

Alerts say where and when the crime happened. To leave that out, add Config.AlertDetails = false to config/config.lua.

Job alerts (Config.Alerts) is the list of every alert and its command. Each row has a title, a command (without the slash), the message to responders, the message to the caller, the jobs and grades alerted, the blip, how long the blip stays, whether to set a route, and optionally a cooldown in seconds, Stay until reached and Ignore duty (law jobs get it even off duty). Every command must be unique. A job in the row with no grades listed only alerts grade 0.

To add your own call command, such as /callblacksmith: open the Job alerts list, duplicate a close one such as NEED DOCTOR (or choose Add alert), fill in the row, save and restart Witnesses.

NPC law response (config/npc.lua)

Off by default. When on, a posse of NPC lawmen rides out after a witness reports a crime and no player lawman is on duty.

Posse by severity (ResponseTypes):

Optional fine-tuning keys can be added to Config.LawResponse in config/npc.lua. Without them these defaults apply:

WarnBeforeFiring = true,  -- call out and hold at gunpoint before firing
WarnDistance = 25.0,      -- metres at which they call out
WarnTime = 6,             -- seconds to surrender before they open fire
DismountDistance = 20.0,  -- a rider gets off when the player is on foot this close
Accuracy = nil,           -- 0-100; nil = by severity (about 30 low to 55 high)
RepositionStuck = true,   -- a stuck officer out of sight is moved nearer
EscapeTime = 10,          -- seconds beyond DespawnDistance to escape
DespawnTimeout = 30,      -- seconds to leave out of sight before being removed anyway
Speech = true,            -- officers call out and shout orders

The built-in Sisika jail

Off by default so it never fights a jail script you already run. Turn it on in /poggy → Witnesses → NPC law response → Use the built-in Sisika jail, or in config/npc.lua:

BuiltinJail = {
    Enabled = true,
},

Every other key is optional and can be added under BuiltinJail by hand:

Advanced

Commands#

The call commands come from the Job alerts list, so the names above are the ones it ships with; you can rename them or add more.

The same list also holds alerts meant for your other scripts to fire (robbery, break-in, bounty, drug sale, explosives, kidnapping, prisoner escape, train robbery, grave robbing and more). They have odd names on purpose. In 1.4.0 any player who knows an alert command can type it, so keep the names of these alerts hard to guess. The crime alerts (witness_shooting_alert and the others) are fired by Witnesses itself when a witness reports; a player who types one only starts a witness against themselves.

There are no keybinds.

Permissions#

Staff commands use the standard ACE permission command.<name>, and all of them also work from the server console. Give them to your admin group in server.cfg:

add_ace group.admin command.witnessduty allow
add_ace group.admin command.witnesstestalert allow
add_ace group.admin command.jail allow
add_ace group.admin command.unjail allow
add_ace group.admin command.dumpalertgroups allow
add_ace group.admin command.debugalertsgroups allow

If you renamed the jail commands, or vorp_police is running, use the command's real name (for example command.witnessjail).

Who gets which alert is set by job and grade, not ACE:

• Each row in Job alerts lists the jobs it reaches and, for each job, the grades.
• Law alerts use Law jobs and Law grades that get alerts. With Only alert on-duty law on, a lawman must also be on duty, as your duty script says. A row with Ignore duty on skips that.
• With Law immunity on, witnesses ignore crimes by lawmen on duty.

Using it in game#

For players committing a crime

1. Commit a crime in a town (for example, fire a gun). If a townsperson sees it, they react, then run, and you are told someone saw you. A blip shows each witness.
2. Stop them before they get away: catch them, chase them off, or worse. A witness must get far enough and stay away for a few seconds to report.
3. If they report, on-duty law gets an alert. You are told the law is coming only when a lawman got the alert or a posse rides out.
4. Once witnesses start, nothing new is noticed until that event is over (every witness stopped, or the posse has arrested you, killed you or lost you). Then the witness cooldown starts.

A player the duty script says is in jail is not reported and no posse is sent after them. outsider_policeman and rsg-lawman (with rsg-prison) can say this, and so can the built-in jail. They can still call for help.

For lawmen and other jobs

An alert shows a popup with what happened, where and when, a blip, an area circle and, if the row says so, a route. /clearalerts clears it all; /clearwaypoint clears just the route. Players call you with /callpolice, /calldoctor and the others.

The NPC posse

• Officers appear at least 70 m away, out of your sight, on a road where there is one. Riders arrive in the saddle.
• Within about 25 m they call out and hold you at gunpoint for a few seconds. Shooting, drawing on them, running or waiting it out starts the fight.
• They fight only you, never bystanders or other lawmen, and get off their horses to chase you on foot.
• Get far enough away for about 10 seconds and you have escaped. Kill them all and it ends. When it is over they ride or walk off and vanish out of sight.

Surrendering and jail

1. On foot, with the posse close, hold the surrender prompt. Your hands go up.
2. The officers hold fire and walk in with guns drawn. One walks round behind you, takes hold of you, and only then are you cuffed. Moving too far or drawing a weapon breaks the surrender.
3. You are jailed for Jail time by severity minutes if something can jail you, tried in this order:
   • Jail call (JailExportCall in config/npc.lua). src, charId and timeInSeconds are replaced with real values, for example "exports.another_jail:JailPlayer(src, timeInSeconds, 'Arrested by law')".
   • Your own jail export, added by hand to Config.Duty.Custom in config/config.lua as JailExport = "JailPlayer" (with Resource set). It is called with the player, minutes and a reason.
   • The built-in Sisika jail, when it is on.
4. With nothing that can jail, the officer takes the cuffs off after a moment, you are let go with a warning, and the posse leaves.

None of the supported duty scripts can jail from another script, so on a fresh install with the built-in jail off, arrests end with a warning.

The built-in Sisika jail

An arrested player fades out and wakes in Sisika Penitentiary in the prison uniform, weapons put away, with the time left at the bottom of the screen. Walking off the grounds, or respawning elsewhere after dying inside, brings them back. Time only counts while they are online, and it is kept over a relog and a server restart. When it is up their own clothes come back (on VORP automatically; on RSG and QBR set RestoreCommand) and they are faded to the far bank of the river, south-east of Saint Denis.

To try it: turn it on, restart Witnesses, then type /jail me 1.

For your own jail script, Witnesses can tell who is jailed if you add IsJailedExport = "IsJailed" (an export that takes the player) or JailedStateBag = "jailTime" to Config.Duty.Custom.

For developers#

Police alerts from other scripts

Raise a police alert from any server script. It goes to on-duty law only, uses the alert cooldown, and brings the NPC posse when nobody is on duty and the crime is in EngagedCrimes.

local ok, info = exports.poggy_witnesses:PoliceAlert({
    src      = source,                 -- the suspect (their position is used; they are told)
    coords   = vector3(x, y, z),       -- or a position, when there is no suspect
    title    = "BANK ROBBERY",
    message  = "The Valentine bank is being robbed!",
    crime    = "Robbery",              -- the cooldown key and the posse's crime
    -- optional:
    alert    = "robbery198sd99720",    -- start from a Job alerts row (its icon, blip, text)
    jobs     = { "sheriff" },          -- default: the Law jobs list
    blip     = "blip_cash_bag", blipTime = 120000, waypoint = true,
    npcLaw   = false,                  -- true: posse even if the crime is not engaged; false: never
    notifySuspect = false,
    suspectMessage = "Someone saw you!",
})
-- ok = false with info "cooldown", "no_position" or "jailed" when nothing was sent;
-- otherwise info = { sent = n, lawSent = n, npcLaw = true/false }

The same from a server event: TriggerEvent('poggy_witnesses:policeAlert', data) (server side only).

Send an existing Job alerts row as it is (no posse unless you name a crime):

exports.poggy_witnesses:TriggerAlertForPlayer(src, "graverobbing8x2kp19")
exports.poggy_witnesses:TriggerAlertForPlayer(src, "robbery198sd99720", { crime = "Robbery" })

Duty, jail and the posse

exports.poggy_witnesses:IsOnDuty(src)            -- true when that lawman is on duty
exports.poggy_witnesses:GetOnDutyLaw()           -- every on-duty lawman's server id
exports.poggy_witnesses:SetOnDuty(src, true)     -- your duty script tells Witnesses (nil hands it back to the preset)
exports.poggy_witnesses:GetDutyPreset()          -- "outsider_policeman", "vorp_police", ...
exports.poggy_witnesses:IsJailed(src)            -- true when the built-in jail or the duty script says so
exports.poggy_witnesses:StartLawResponse(src, "Robbery", true)  -- send the posse now (true: skip EngagedCrimes)
exports.poggy_witnesses:EndLawResponse(src)
exports.poggy_witnesses:IsWantedByNpcLaw(src)

The full witness flow for your own crimes

A witness must see it and get away before the alert is sent.

-- Server
local requestId = exports.poggy_witnesses:CreateWitness(source, "GraveRobbing", {
    alertCommand       = "graverobbing8x2kp19", -- a command from Job alerts
    triggerLawResponse = true,                  -- send the NPC posse if reported
    lawActionType      = "Shooting",            -- the crime the posse is sent for
})

-- Client
exports.poggy_witnesses:CreateWitnessLocal("GraveRobbing", { alertCommand = "graverobbing8x2kp19" })

The full option list is at the top of shared/api.lua, which is readable.

Server events

Troubleshooting#

Lawmen get no alerts

Check the job name is in Law jobs (exact, capital letters matter) and the grade is in Law grades that get alerts; grades that start at 1 or go above 5 must be added. With Only alert on-duty law on, they must be on duty: /witnessduty shows which duty script is read and what it says for each lawman. Remember the alert cooldown: the same crime by the same player alerts once a minute.

Nothing is ever witnessed

With Only in towns on, crimes only count inside enabled towns. Check you are not in a blacklisted area, the crime is switched on with a chance above 0, and you are not a lawman on duty with law immunity on. Stand where it should happen and type /witnesscheck: it prints every one of these checks to F8. To see the zones on screen, add Config.ShowZones = true to config/config.lua.

Aiming a lasso or camera starts a witness

Add the weapon name to Items that are not threatening. /getmyweaponhash_cl shows the name the script sees.

A job NPC from another script runs off to report

Add its model name to NPCs that never witness.

The NPC posse never comes

The law response must be enabled, the crime must be in Crimes that send NPC law, and with Player lawmen first on, no player lawman may be on duty (/witnessduty). When nothing on the server can say who is on duty, every law job counts as on duty by default (When the duty script cannot say), so the posse stays home while a lawman is online. It sets out after Response time. With sv_entityLockdown on, the server will not let it appear.

Arrested players are let go with a warning

Nothing on the server can jail them. Turn on the built-in Sisika jail, or set a Jail call or jail export for your own jail script.

/jail does something else

vorp_police has its own /jail. With it running, Witnesses uses /witnessjail and /witnessunjail, or set your own names with JailCommand and UnjailCommand.

Released prisoners stay in the uniform on RSG or QBR

Set RestoreCommand under BuiltinJail to your server's command that reloads a player's clothes.

Two alerts for one crime

Another script (a dispatch system) also detects shots or fights. Turn its detection off, or have it call PoliceAlert instead.

A setting shows as read-only in /poggy

It is built from another setting (a job alert that uses the law jobs list or a translation), or it runs as code. Change the setting it comes from, or edit the file.

Updating#

Witnesses updates through poggy_core like every Poggy script: see Updates. Your config and translation files are merged, so new settings arrive with their defaults and your values stay.

If you rename the resource folder, sentences in the built-in jail saved under the old name are no longer seen, because they belong to the resource's own storage.