Jixryo Criminal

Jixryo Criminal is the resource jixryo_criminal, version 0.2.0. Staff make NPCs in game, place them, give them hours and behaviour, and write what they say. Players find those NPCs in the world and talk to them in a dialogue screen. What a player learns is kept as flags on their character, which later answers, other NPCs and other scripts can ask for. The same builder has a scenario tab: staff make a scenario (one job at one site), build it in the world, and a Live scenario's props stand in every game near it. Running a scenario (test runs, stages, loot, the alarm) is the next phase and is not in this build: the Spawn, Stop and Reset calls answer that test runs come with the scenario engine.

Every NPC, line, answer and scenario lives on the server. A player's game only learns about the NPCs standing within 120 m of it, and only one line of dialogue at a time while talking.

#What players get

• NPCs in the world. An NPC stands at its spot doing what staff set (standing still, a GTA scenario or an animation, with a prop in hand if set). Close up it looks at you and greets you. The Talk option is on the NPC through ox_target.
• A dialogue screen. Talking turns the NPC to you and moves the camera between you onto its face. The screen shows the name, the role, the line typed out along the bottom and the answers on the right. Leave is always last.
• Locked and hidden answers. An answer you do not qualify for either shows locked with what it needs ("Needs: $100 cash", "Needs: 2 more people with you", "Needs: Come back later") or is hidden, as staff chose. Hidden answers never leave the server.
• Payouts that are all or nothing. When an answer takes money, gives an item, sets a flag or calls another script, everything is checked first and then done in order. If one step fails, the steps before it are put back. What cannot be undone (XP, a map mark, mail, a notification, a shop) only happens after all of that worked.
• Documents. An answer can hand over a note with a name and words on it (the presets use stickynote). A later NPC can ask for that exact document by its id and take the whole copy.
• Shops. An answer can open an ox_inventory shop next to the NPC. It opens only for the player the answer let in, for 90 seconds.
• Map marks, mail, notifications and XP. An answer can mark a place on the map for a while (with the GPS set if staff chose), send phone mail from the NPC, show a notification, or give skill XP.
• NPCs with a schedule and a temper. An NPC can be out only in certain hours of GTA's clock, on certain days, or only while the police on duty are within a range. It can refuse on-duty police with its own line. If set to run from a gun, a gun drawn within 15 m sends it off for everyone until it comes back after its minutes.
• Conversations that end cleanly. Walking away, nobody answering for three minutes, getting hurt, the NPC leaving or logging out all end the conversation on the server too.
• Live scenario sites. The props of a Live scenario that are there from the start stand near the site as frozen local objects. Nothing on them does anything yet (that is the scenario engine, the next phase).

#What staff get

Staff with the builder ACE open the builder with /criminal.

• The NPC list. Every NPC with its group (a coloured slash), Live / Draft / Off and its lock. Search, filter by group or state, and pick one to see what talking to it needs (hours, days, police, refuses cops, runs from guns), its first words and its chain: the flags its answers ask for and who teaches them, the flags it teaches and who asks for them. A flag nobody teaches shows in amber.
• Edit, Test, Go live / Take down, Switch off, Lock, Duplicate, Export code, Delete. Delete asks for the name typed. Test runs the dialogue screen with nothing done for real and lists what each answer would do; hidden answers show and say so.
• New NPC opens the editor on a blank NPC in front of you. The editor's sections: Details (name, role, area, group), Appearance (any ped model, Copy my look, Randomise, every clothing part and prop the model really has, and on the online models heritage, face features, hair, beards, makeup and marks), Dialogue (lines and answers with their conditions and actions), Placement (up to 12 spots, used fixed, at random each restart or rotating every few hours), Schedule (hours, days, police on duty) and Behaviour (idle, prop in hand, mood, looks at you, greeting, refuses cops, runs from a gun and the minutes before it comes back).
• Presets. Five NPCs in one chain, each added as a Draft standing in front of you: Lebron sells the Stab City stash location, marks it on the map and sends you to Dutch; Dutch opens his back room shop for people Lebron sent; Vince only talks to people Lebron vouched for and wants a crew; Tiny sells the Paleto guard shift, at night only; Moira draws the vault blueprint (a document) for the people who know the shift.
• Codes. Export code gives a JXC1- code for an NPC; Import code takes one back as a new Draft, checked like anything made in the builder. A broken code, a code of the other kind or an empty paste is refused.
• Versions and locks. Every save carries the version it was opened at. If someone else saved since, the save is refused rather than lost. A locked NPC or scenario can only be changed by its author or by head staff.
• The scenario builder tab. The list of scenarios with group, status, lock and what it takes to start (the crew, the police, its needs). New scenario makes a Draft centred where you stand. The chosen one has Edit, Spawn (for now it says test runs come with the engine), Go live (it needs a stage first) or Switch off, Lock, Duplicate, Export code (a JXS1- code), Delete (type the name), and a budget bar: props, guards and vehicles (600 at most), networked guards and vehicles (50 at most) and what your game already draws near you.
• The catalog. 47 props in 7 categories with their pictures, 10 guard models and 8 vehicles, placed as object, storage, interactive, grabbable, alarm or camera, shop, zone, door, guard, vehicle, or one of your NPCs as a dialogue thing. Picking one puts it in your hand in build mode.
• The scenario editor. The camera goes over the site with everything placed standing there. Sections: Details, Start (where it starts, crew 1 to 4 by default, police, needs, what the world says when a start fails), Stages (up to 12, each with up to 6 objectives on placed things, a clock, and effects when it starts, is done or fails), Things (each thing's settings), Loot (tables of rows), Alarm and Reset. Save checks everything on the server and says what is wrong in plain words.
• Build mode. Walk and aim or fly the freecam; what you hold follows the aim, sits on what it lands on and faces you; the wheel turns it (or sizes a zone); snapping, a grid and lying on the surface; GTA's gizmo for fine moves; Enter places and saves at once with the next one already in hand; pick, move, copy and delete placed things; add one of ox_doorlock's doors near you or aim at a vault door of the map. A locked scenario can be flown round by other staff but nothing can be picked or placed.

#Install

1. Stop nothing. Jixryo Criminal replaces no other resource.

2. Upload the folder whole. The page is already built in web/build, with the catalog's pictures in web/build/props.

3. Order in server.cfg. It needs ox_lib, oxmysql, qbx_core and Jixryo Core 1.3.0 or later (for the clock and the gizmo). It uses ox_inventory (items, shops), ox_target (the Talk option), ox_doorlock (a scenario's doors), lb-phone (mail) and Jixryo Skills (XP) through Jixryo Core when they are running, so start those before it too.

   ensure ox_lib
   ensure oxmysql
   ensure qbx_core
   ensure ox_inventory
   ensure ox_target
   ensure ox_doorlock
   ensure jixryo_core
   ensure jixryo_criminal

   Copy

4. Give staff the builder. The first ACE opens the builder; the second also edits and unlocks NPCs and scenarios someone else locked. group.god passes both without an ACE.

   add_ace group.admin jixryo.criminal allow
   add_ace group.god jixryo.criminal.head allow

   Copy

5. Items. It adds no items of its own. Answers give, take and sell the items your ox_inventory already has, and the server refuses any item it does not know ("there is no item called ..."). The presets use lockpick, advancedlockpick, thermite, usb_drive, stickynote and the crowbar, which the Jixryo ox_inventory fork has.

6. The database. The resource makes its tables itself through Jixryo Core's migrations, in two steps: jixryo_criminal_npcs and jixryo_criminal_flags, then jixryo_criminal_scenarios.

7. Full restart. On start it prints version 0.2.0: N NPCs, N live; N scenarios, N live.

Coming from 0.1.0: upload the whole folder again (the page changed and the props pictures are new), then a full restart. The scenarios table is added by itself; the NPCs and flags stay as they are.

#How other scripts' calls behave

Jixryo Criminal does not stand in for any other resource and provides no other resource's name. What it does for the rest of the suite:

• Its own conditions and actions. Any resource can register a condition or an action with RegisterCondition and RegisterAction. They appear in the builder as "Another script" rows, and they go away when that resource stops: an answer that depended on one hides until the resource is back.
• Flags. HasFlag, GetFlag, SetFlag and ClearFlag read and write the flags on a character by server id or by citizen id, online or offline. They are kept in jixryo_criminal_flags.
• Shops. Each shop action registers an ox_inventory shop called jxcrim_<npc id>_<spot number> at the NPC's spots. An openShop hook with the filter ^jxcrim_ asks this resource before any of them opens, and it opens only for a player an answer let in within the last 90 seconds, while the NPC is out.
• Mail, XP, doors, the Talk option, the clock and the gizmo go through Jixryo Core's phone, skills, doors, target, clock and gizmo modules. XP goes to the crime skills, which list this resource as a source; other skills refuse it.
• Audit. Staff changes and answers that do something are written to Jixryo Core's audit log.

#Its own API

Server exports (who is a player's server id or a citizen id):

Flag names are letters, digits and _ - . :, up to 48 characters. Names starting with @ are this resource's own marks and cannot be set from outside.

Client export:

Callbacks (ox_lib, client to server):

Events:

Codes: an NPC's export code is JXC1-<base64>-<checksum>; a scenario's is JXS1-<base64>-<checksum>. Both are checked for the checksum and then cleaned like anything the builder sends.

Audit actions: criminal.answer, criminal.create, criminal.save, criminal.status, criminal.lock, criminal.delete, criminal.duplicate, criminal.import, criminal.preset, and for scenarios criminal.scenario.create, criminal.scenario.save, criminal.scenario.place, criminal.scenario.unplace, criminal.scenario.status, criminal.scenario.lock, criminal.scenario.delete (with its code), criminal.scenario.duplicate, criminal.scenario.import.

#Commands and keybinds

The keys above are read directly by the resource and are not key mappings, so they cannot be rebound in the game's settings. There are no RegisterKeyMapping or lib.addKeybind entries.

#Configuration

config.lua is listed in escrow_ignore, so it can be edited after upload.

The catalog of props, guard models and vehicles is shared/catalog.lua. The limits are enforced on the server: everything the builder sends is cut to them.

#Security

• Staff calls check the ACE every time. Every action of both builder callbacks and /criminal itself are refused without it ("Staff only"). Changes check the lock and the version, and a stale save is refused rather than written over someone else's.
• Everything the builder sends is cleaned on the server. Text is trimmed and cut to length, numbers out of range go back to their defaults, unknown groups, moods, kinds, conditions and effects are dropped, and an item the server does not have is refused with its name. Import codes are checksummed and then cleaned the same way, so a forged code cannot carry a bad NPC or scenario in.
• A game gets only what stands near it. The stream carries the look, the spot and the behaviour of the Live NPCs within 120 m: never the name (until they talk), the list, their other spots or a word they say. A Live site sends only the models and places of the props there from the start: never the stages, the loot, the guards, the codes or what anything does.
• The dialogue comes one line at a time and hidden answers never leave the server. Every pick is checked again: the player is still there and close enough (reach plus slack), it is an answer on the line the server showed them, and its conditions still pass. On-duty police get the refusal line and no answers.
• Actions are all or nothing with undo for items, money, flags and other scripts' actions; what cannot be undone happens only after all of that worked.
• Shops are gated by the openShop hook: no pass from an answer in the last 90 seconds, no shop, and nobody else's pass works.
• Running off is checked: the server reads the gun in the player's hands and the distance itself, at most once every 4 seconds per game.
• Build mode's placing is checked to be within the leash of you, the ox_doorlock door to exist, and the whole scenario is cleaned again on every change. Delete needs the name typed.
• Audit. Made, saved, status, lock, deleted (with its code), duplicated, imported and preset, for NPCs and scenarios, plus answers that did something, go to Jixryo Core's audit log.
• Rate limits on the talk and answer callbacks come from Jixryo Core's rate module [inferred: the suites load the real rate module and the README says rate limits and one pick at a time stop double answers; the exact limits are not in config.lua].

#Tests

Both suites run the real server on a real database (the resource's own migrations on SQLite) with Jixryo Core's real modules, then the real client in a stand-in game. Run on 2026-10-31.

cd dev-tools/luarun && node run.mjs ../../jixryo_scripts/jixryo_criminal tests/jixryo_criminal.lua

cd dev-tools/luarun && node run.mjs ../../jixryo_scripts/jixryo_criminal tests/jixryo_criminal_scenarios.lua

Both suites share tests/jixryo_criminal.setup.lua. A filter word after the suite name runs only the tests whose name has it.

#Check it in game

1. /criminal as staff opens the builder with the game blurred behind it. Without the ACE: "Staff only".
2. Presets, then Add Lebron where you stand: he appears as a Draft in the list. Edit him: he stands in the world and the camera turns round him (drag, wheel, F, R).
3. Appearance: change his model, then Copy my look and Randomise. Each shows on him at once.
4. Placement: aim, wheel, F for the freecam, Tab for the gizmo, Space, Enter. The page comes back with the spot. Check his feet are on the floor.
5. Save, then Go live. Walk away past 120 m and back: he disappears and reappears, smoking.
6. Walk up: he looks at you and says hi. The Talk option opens the dialogue on his face. With too little cash the paid answer shows locked with what it needs; with the money it takes the cash, marks the map with the GPS, shows a notification and hides itself after.
7. Test from the builder runs the same screen with nothing done for real and lists what each answer would do.
8. On duty as police, Lebron gives the refusal line only. Draw a gun close to him: he runs, for everyone, and comes back after his minutes.
9. Add Dutch, go live, and talk to him after Lebron sent you: the shop opens next to him. Away from him, or without the answer, it does not.
10. Lock an NPC with one staff account and try to save it with another: refused. Head staff can.
11. Export code on one NPC, then Import code: a Draft copy arrives. Restart the resource: the NPCs come back where they were and the flags stay.
12. Scenario builder: type a name and press Enter for a Draft centred where you stand. Catalog, Grabbable, Cash trolley: build mode with the trolley in your hand, following the aim, sitting on the floor and facing you. Wheel, G, Tab; Enter places it ("Cash trolley placed.") and the next is in hand; Esc puts it down; Esc again leaves.
13. Build again and press F for the freecam. Hold Left Alt for the panel's cursor (try the grid and placing as Storage); let go to carry on. Point at the trolley and click: it lights up and is in your hand. Enter saves the move. Ctrl D copies it. Pick the copy, Del, Del: gone.
14. Zone (the wheel sizes the ring), an ox_doorlock door near you (added at once), a vault door of the map (aim and Enter), a guard model (a frozen stand-in), a vehicle, one of your NPCs as itself, a security camera (what it watches drawn in red).
15. Edit the scenario: the camera over the site with everything standing round it. Add a stage with an objective on the trolley and Save; then break something on purpose (an objective with nothing picked) and read what the save says.
16. Go live with no stage: refused. With one: Live. Walk away past about 160 m and back: the props go and come. A thing set to show up at stage 2 is not there for players.
17. Spawn: "Test runs come with the scenario engine (phase B3)."
18. Lock the scenario with one staff account: another can fly round it but not build in it or save it. Export code then Import, and Duplicate: Draft copies. Delete (type the name): gone from every game at once. Restart the resource in build mode: nothing it made is left standing, and the scenarios come back as they were.