Jixryo HUD

Jixryo HUD is the player HUD in the suite's slant: see-through black, italic capitals, everything leaning like the slash, colour only when it means something. It is client only. It shows, and it never decides.

#What players get

• Top right: the radar. With Jixryo Map running it is the suite's own: a map of San Andreas drawn inside a ring of compass ticks, or in a square frame, each player's pick. It turns with the camera or stays north up, you are the white arrow in the middle, and it zooms out as you go faster (on foot, driving, on a boat, flying higher). On it: every blip any script made that GTA would show on its radar, in the blip's own colour with the suite's icon for it (far ones sit on the edge, short-range ones only show near), your waypoint and GTA's route to it as a purple line. Under a tunnel or inside a building the map dims, zooms in and says so. N, E, S and W ride the ring and your heading sits over it. Under it, with no box: the area, the street and cross street, the postal code and the time. Notifications and dispatch cards stack under it. Without Jixryo Map the HUD puts GTA's own radar in the square frame instead.
• Bottom left: one row of slanted tags, each with a thin slanted bar under it. Your voice first: the mic, its bar your range (a third, two thirds, all); while you talk the tag turns white and the bar moves with your voice; changing range writes the range's name for a moment; dead or down, the mic is crossed out in red. On a radio channel the mic becomes a handheld radio with the channel, white with TX while you transmit, green with who is talking while someone else does. A phone call adds a green tag with how long. Then HEALTH and ARMOR in white tags (armour while you wear some; health turns red and beats when low), and the needs as icon tags: food, water, stress, stamina while you run, oxygen under water. Then what is acting on you: the smoke (the joint burning down along its bar, the hits) and each drug, drink or buff from other scripts with its time left (green good, amber bad, red dangerous, chevrons while it makes you faster). On foot the weapon sits over the row with its rounds; money changes pop over it.
• Bottom right, in a vehicle: the speedometer. A ring of slanted rev ticks going red at the end, the gear in a white tag, the speed, the unit, and the lamps: seatbelt (amber and blinking when unbuckled) or harness, helmet on a motorcycle, anchor on a boat, fuel with its gauge, the engine once damaged, lock, cruise with its set speed, the indicators. Over it: "Buckle up", "Ejection risk" in red past the eject speed, "2 unbuckled" for passengers, "No helmet", "Anchor down", "Low fuel". A motorcycle shows its lean. In a helicopter or plane: airspeed in knots, altitude over the ground and the climb, an attitude indicator, fuel, engine, the main rotor or the landing gear, and "Pull up", "Stall", "Rotor damage".
• Bottom centre while you drive: the vehicle's keys.
• The edges pulse red when your health runs low. The HUD fades out while the pause menu is open, while the screen is faded out, before your character loads, and while another script asks it to.
• Your own HUD with /hud, saved on your PC: the gauges' look (Bars, Rings, Cells, Hex), their layout (Row, Stack, Stair, Grid), numbers on the tags, the radar round or square, north up or turning, blips on or off, the radar's zoom and size, which parts show, when the needs show, MPH or KM/H, the HUD's size and glass darkness, and the layout (Full, Minimal, Cinematic).

#What staff get

• Nothing to run on the server. The resource has no server scripts and no database; each player's settings live on their own PC.
• A hook for cutscenes and screens. Any resource hides the HUD for a reason of its own and lets it show again, and a resource's reasons go when it stops.
• Effects and the smoke from your own scripts show on the row through two exports, up to 12 at a time; the HUD only shows them.
• Only changes travel. One thread looks at the game a few times a second and sends the page only the sections that changed, in one message; one thread hides GTA's own HUD pieces every frame. The radar's parts each run on their own clock and send only when something moved. The page draws frames only while something moves.
• The notification stack. The HUD tells the Jixryo ox_lib fork where its top-right column ends and how much room the bottom right needs, so notifications and dispatch cards start under the radar and stop above the speedometer. It is sent again when any of that changes or ox_lib restarts, and taken back when the HUD stops.
• A guard for half-done updates. When client/radar.lua is missing from the running script list (new files restarted without refresh), the HUD says so once in the F8 console and uses GTA's radar in the frame until you do.

#Install

1. What it replaces. Your old HUD: qbx_hud, ps-hud or qb-hud. Stop it; it draws over the same corners and moves the radar its own way. A map mod that streams GTA's radar textures does nothing to this radar.

2. Order. Copy jixryo_hud and jixryo_map into your resources; the page is already built in web/build. Start the HUD after what it reads from, with the map before it. Jixryo Map is not in the store today. The manifest depends on ox_lib and qbx_core.

   ensure ox_lib
   ensure qbx_core
   ensure pma-voice
   ensure ox_inventory
   ensure qbx_seatbelt
   ensure jixryo_map
   ensure jixryo_hud

   Copy

3. Items and database. None.

4. Optional convars. setr voice_syncPlayerNames 1 so the radio shows who is talking; without it the HUD says "Receiving", never a player's OOC name. setr voice_enableUi 0 so pma-voice stops drawing its own range in the bottom-right corner.

5. Restart the server. Updating a running server instead: copy the new files, run refresh, then ensure jixryo_map and restart jixryo_hud. restart alone keeps the manifest the server read at start, so a script file a new version adds is never loaded.

#How other scripts' calls behave

• It answers as itself only. Its exports live under jixryo_hud; it answers no other HUD's names.
• What it reads, and from where. Health, armour, stamina and oxygen from the game. Food, water and stress from qbx_core's hunger, thirst and stress statebags, else its metadata. Muted from qbx_core's isdead and inlaststand metadata, else the game. Voice range, talking and loudness from pma-voice's proximity statebag and the game. The radio from pma-voice's radioChannel statebag and its radioActive, syncRadioData, addPlayerToRadio, removePlayerFromRadio and setTalkingOnRadio events. A phone call from lb-phone's onCallWith statebag. Money, job and duty from qbx_core's player data (QBCore:Player:SetPlayerData, taken from qbx_core only). The weapon and the rounds you carry from ox_inventory (ox_inventory:currentWeapon, getCurrentWeapon, the ammo counted once a second). The radar's map from Jixryo Map's info export. Fuel from the vehicle's fuel statebag, else the game. Seatbelt and harness from qbx_seatbelt's seatbelt and harness player statebags, yours and your passengers'. Cruise from a cruise player statebag. The postal from a postal resource's export (nearest-postal, getPostal by default). Everything else from the game.
• Blips. Make them as you would for GTA's radar (AddBlipForCoord or AddBlipForEntity, sprite, colour, display, short range). The radar reads them within a quarter of a second of GTA's blip count changing, and every 10 seconds anyway. It draws what GTA's radar would: displays 2, 5, 6, 8, 9 and 10 and over, radius blips, your own arrow and the waypoint left out.
• Jixryo MDT asks units for the player's speed units on its dispatch cards.
• It starts and stops with the character (QBCore:Client:OnPlayerLoaded and OnPlayerUnload), and switches between its own radar and GTA's by itself when Jixryo Map starts or stops.

#Its own API

Client exports:

A resource's effects, smoke and hide reasons go when it stops. The HUD fires no network events of its own; it tells the Jixryo ox_lib fork where the notification stack goes through a local event, and takes it back when it stops.

#Commands and keybinds

There are no keybinds. The vehicle keys and the belt key the HUD shows are only pictures of your server's binds; set Config.vehicleKeys and Config.seatbeltKey to the real ones.

#Configuration

config.lua:

#Security

• Client only. It has no server side and moves nothing: no money, no health, no items. Every number it shows is read from the game, a statebag or another resource, and a value nobody knows is left out rather than guessed.
• Settings are checked field by field, from the save and from the page: choices from the lists, numbers stepped and clamped to their ranges, switches as booleans, unknown fields dropped.
• Effects and the smoke belong to the resource that set them. Ids are per resource, text is cut to length, tones and kinds come from the lists, levels and changes are clamped, 12 effects at most, and everything a resource set goes when it stops.
• Player data is taken from QBCore:Player:SetPlayerData only when qbx_core sent it, as qbx_core itself checks.
• Names on the radio show only when the server syncs them; otherwise "Receiving", never a player's OOC name.
• GTA's radar stays hidden every frame while the suite's own shows, even after another script turns it back on.
• The harness shows without a wear gauge: its wear is the item's, kept on the server by qbx_seatbelt, so the HUD shows no made-up number.

#Tests

dev-tools/luarun/tests/jixryo_hud.client.lua runs the real client in a stand-in game. Run on 2026-10-31: 19 passed, 0 failed.

They cover start-up with the page's config and settings; the first state (body, voice, place, night); talking with loudness and muted; the radio (channel, members, who talks, names only when synced, TX); a phone call; a car (kind, belt, harness, a passenger unbuckled, indicators, lights, cruise, getting out); a motorcycle (helmet, lean, no belt); a boat, a helicopter and a plane (altitude, climb, attitude, rotor, gear); effects (added, checked, not resent while unchanged, wearing off, cleared, capped, gone with their resource); the smoke; settings checked and saved; GTA's radar in the frame without the map, /hudmap and a new resolution; the suite's radar (the page gets the map, GTA's radar hidden every frame); where you are (sent while you move or turn, not while still); blips (what GTA's radar would show, colours, followed on the move, read again when the count changes, off in /hud); the GPS line and a tunnel or a building; Jixryo Map starting and stopping mid-game; the notification stack's place and units; and client/radar.lua missing from the running script list.

cd dev-tools/luarun
node run.mjs ../../jixryo_scripts/jixryo_hud tests/jixryo_hud.client.lua

The README also records that 22 of 22 planted bugs were caught (2026-10-31), and that the built page was driven with the Lua's messages: the radar drawn from the map's tiles, near and far blips, the route, the waypoint, "Tunnel", broken messages dropped, and back to the square frame when the map leaves.

#Check it in game

1. The radar is the suite's: round inside the ring, the map turning with the camera, your arrow in the middle. GTA's radar never shows, even after the character screen.
2. It zooms out as you drive faster and fly higher. /hud: Radar zoom, Radar size, North up and Square all change it at once.
3. Shops, garages, the police station and job blips show with icons in their colours; a far job blip sits on the edge; Blips off in /hud hides them.
4. Set a waypoint on the pause map: the purple line runs along the roads to it and the purple dot sits on it or on the edge.
5. Drive through a tunnel: "Tunnel" and the map dims. Walk into an interior: "Inside".
6. Voice: the bar is your range at rest; talking turns the tag white and the bar follows your voice. Join a radio channel and talk (white, TX); someone else talks (green, their name with names synced, else "Receiving").
7. Seatbelt: B turns the lamp white; unbuckled over 10 MPH "Buckle up", over 45 "Ejection risk"; a harness shows the harness lamp; an unbuckled passenger shows "1 unbuckled".
8. A motorcycle (helmet, lean), a boat (anchor), a helicopter (altitude, climb, attitude, rotor), a plane (gear up and down, "Stall" slow and high with the gear up). A call with lb-phone shows the call tag and its time.
9. Notifications stack under the street, not over the radar; in a vehicle they stop above the speedometer; after restart ox_lib they go back under the radar within a moment.
10. stop jixryo_map: GTA's radar appears in the square frame within a second; ensure jixryo_map: the suite's again. stop jixryo_hud puts GTA's radar back bottom left. resmon 1 while standing still and while driving.