Jixryo Skills

Jixryo Skills is the resource jixryo_advancedskills, version 1.0.0. It keeps 22 skills in four categories (crime, drugs, trades, body), each with levels 0 to 10, rank names and one line of perks. A perk is a set of named effects such as lockpick.break = -0.25, and any script in the suite reads the effects it cares about through Jixryo Core. XP comes only from server code that each skill names; the body skills also level from what players do, through a report the server checks against what it saw itself. The body skills set GTA's own stats.

#What players get

• The menu. /skills, or the K key, opens the skills menu with the game blurred behind it: tabs for CRIME, DRUGS, TRADES and BODY (Q and E), the skills on the left (the arrows) and the selected one on the right: level and rank, the next rank, XP through the level, the perk line (every level a station, the perks as cards under it: yours, next, locked), what it does for you now in words, what the next level adds, how to train it, today's XP against the full-XP cap, and recent gains. Esc closes it.
• XP as it comes in. An XP chip top centre ("LOCKPICKING +18 XP", the bar filling; gains on the same skill add up), a level-up banner with GTA's rank-up sound and every perk it unlocked, a "new skill found" banner, and a banner for everyone when staff start an XP event.
• Hidden skills. Crime and drugs skills show only once you have earned XP in them; the menu counts the rest ("2 more crime skills to find"). Trades and body skills always show.
• Perks that other scripts read. Each skill has perks at levels 2, 4, 6, 8 and 10, plus small per-level scaling on some (Lockpicking picks 2% faster a level, Cultivation harvests 1% heavier a level). Effects add up across perks.
• Body skills that change the game. Stamina, Strength, Lung Capacity, Shooting, Driving and Flying set GTA's own stats: 20 at level 0 plus 8 a level, 100 at level 10. Their XP comes from doing it: sprinting and swimming, time under water, melee hits landed, driving fast, flying. Shooting XP comes from range scripts (Jixryo Police is its source).
• A soft daily cap. Full XP up to 1,500 a skill a day (the server's day), then a quarter of it. There is no hard wall.
• Rust on body skills. A body skill unused for 7 days fades 5% of the current level's span a day, never below the start of the level: nobody loses a level.
• Boosts and XP events. Staff can boost one player (or a listed script can, such as a skill book) and start server-wide XP events; both multiply, and the menu shows how long they have left.

#What staff get

The STAFF tab of the same menu, for anyone with group.god, group.admin or the ACE jixryo.skills:

• Find a player in the city by name, citizen id or server id, or open anyone by citizen id when offline (read straight from the database).
• Set a level, give or take XP, reset one skill or all. Staff edits skip boosts, caps and the day's count, write to the database at once, and raise the level-up event for other scripts when a level goes up.
• Boost a player in the city: a multiplier from 1.05 to 5 on one skill or all, for up to 24 hours, kept in the database.
• Start or stop an XP event for everyone: a multiplier from 1.05 to 5 on some skills or all, for a quarter of an hour up to 72 hours, with a label. It is kept across restarts in the resource's KVP and shows as a banner to everyone in the city.
• Every change needs a reason and goes to Jixryo Core's audit log with it. Looking things up does not.

#Install

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

2. Upload the folder whole. The page is already built in web/build.

3. Order in server.cfg. It needs ox_lib, oxmysql, qbx_core and Jixryo Core 1.2.0 or later.

   ensure ox_lib
   ensure oxmysql
   ensure qbx_core
   ensure jixryo_core
   ensure jixryo_advancedskills

   Copy

4. Staff. group.god and group.admin already pass. To give someone else the STAFF tab:

   add_ace group.mod jixryo.skills allow

   Copy

5. Items. None. It adds no items and reads no inventory.

6. The database. The tables jixryo_skills, jixryo_skills_log and jixryo_skills_boosts are made on the first start through Jixryo Core's migrations, in one step. If they cannot be made, the console says so and skills stay off.

7. Full restart. If the resource alone is restarted while people play, it loads every character already in the city, and each game asks for its skills again.

#How other scripts' calls behave

Jixryo Skills does not stand in for any other skills resource. Every script in the suite reaches it through Jx.skills in Jixryo Core, which works whether or not this resource runs: off, levels and effects are 0 and adding XP answers false, 'no_skills'.

-- server
Jx.skills.add(src, 'lockpicking', 18, 'Picked a car door')   -- true, gained | false, why
Jx.skills.level(src, 'cultivation')                          -- 0..10
Jx.skills.has(src, 'chemistry', 3)                           -- a recipe that needs Chemistry 3
local yield = grams * (1 + Jx.skills.effect(src, 'grow.yield'))
Jx.skills.boost(src, 'chemistry', 1.5, 30, 'Chemistry notes') -- needs the resource in Config.boostSources

-- client (for feel and showing things; the server decides)
local zone = 50 * (1 + Jx.skills.effect('lockpick.zone'))
Jx.skills.open()

• A script must be named in the skill's sources in config.lua to give it XP. Anything else is refused with not_allowed and printed once in the console (<resource> tried to give <skill> XP: add it to the skill's sources in config.lua to allow it). The invoking resource is read by the server, so a script cannot claim to be another.
• One call gives at most 100 XP (maxPerCall, a skill can set its own), and a skill takes at most 20 gains from one player in 10 seconds; the 21st answers too_fast. XP that arrives while a character is still loading is queued and applied once loaded.
• Boosts from a script need the resource in Config.boostSources (only this resource by default); staff boosts from the menu are always allowed.
• Level ups raise a server-only event other resources can listen for (never a net event):

AddEventHandler('jixryo_advancedskills:levelUp', function(src, skill, level, before) end)

• XP events are published in GlobalState.jxSkillsEvent (mult, ends, label, skills), so any script can read whether one is on.
• Who gives XP today. The resources each skill names are in the configuration table below. Jixryo Criminal's dialogue XP action goes through this resource (its suite proves the call); the README of this build still describes only the body skills as wired, so check each other script's own doc for what it gives [inferred: which named sources already call Jx.skills.add is not re-checked against their code in this pass].

The effects each skill's perks carry, for a script to read:

Fractions are percents (0.25 is 25%); whole numbers are counts (one pin fewer, one extra try).

#Its own API

Server exports (what Jx.skills calls; use them directly without Jixryo Core):

Client exports:

Callbacks (ox_lib):

Events:

State: GlobalState.jxSkillsEvent holds the running XP event, or nothing.

Database: jixryo_skills (one row per character and skill: XP, the day and its XP, last used, last rusted), jixryo_skills_log (recent gains, merged by skill and reason within 10 minutes, 50 kept per character), jixryo_skills_boosts.

Audit actions: skills.set, skills.give, skills.reset, skills.boost, skills.event, skills.event.stop.

#Commands and keybinds

#Configuration

The resources each skill names as XP sources in this build:

#Security

• XP only from server code. No event a player's game can send adds XP, except the body report: once a minute (the server refuses one sooner than 50 seconds after the last), every number is capped to what a minute can hold, metres on foot and at the wheel are capped to what the server's own position samples saw the player cover (with a little slack for corners), flying to the time the server saw them at an aircraft's controls, and then the daily cap applies. Garbage values (negative, text, NaN, infinite) add nothing. A cheat gets no more than a player who never stops running.
• Each skill names the resources that may give it XP, read from the invoking resource; a per-call cap and a burst limit stop a looping script without stopping the server.
• A player's skills go to their own game only. The client's copy is for showing things and feel; outcomes that matter are decided on the server with Jx.skills there.
• Staff tools re-check the ACE on every call, validate every value (level within the skill's range, XP from -20,000 to 20,000, multipliers and durations within the staff limits), refuse odd citizen ids before the database is asked, require a reason for every change and audit it.
• Rate limits through Jixryo Core: the menu view once every half second, staff calls once every quarter second, the hello once every 5 seconds, the body report once every 50 seconds.
• In memory while a character plays, written in batches every 15 seconds and on logout, drop and resource stop; a character switch on the same player keeps each character's skills apart.

#Tests

The suite runs the real server on a real database (the resource's own SQL on SQLite) with Jixryo Core's real validate, db, rate, perm, audit and player 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_advancedskills tests/jixryo_advancedskills.lua

A filter word after the suite name runs only the tests whose name has it. The README records 15 planted bugs, all caught, and the built page checked through dev-tools/nui/cdp-game.mjs (opening, rows, keys, Esc, chips merging, banners, sounds).

#Check it in game

1. /skills and K open the menu with the game blurred; Esc closes it. The CRIME and DRUGS tabs count the skills you have not found yet.
2. Sprint for a minute: within the next minute the Stamina chip shows the XP, and the recent gains list "Sprinting and swimming".
3. With Stamina a few levels up, the stamina bar lasts longer; the BODY tab shows the GTA stat value and the next level's.
4. Have a script that a skill names give XP (Jixryo Criminal's XP action is one): the chip shows, and at level 2 the level-up banner names the perk with GTA's rank-up sound.
5. STAFF tab as staff: find a player, set a level with a reason; without a reason it refuses. Check the entry in Jixryo Core's audit log.
6. Start an XP event (x2, 1 hour): everyone sees the banner and gains double; stop it and gains return to normal. Restart the resource during an event: it is still on.
7. Open an offline character by citizen id and set a level; log that character in and see it.