Installation Guide

Generic install hub for oxide-medical — SQL tables, cure item registration, item images, configuration, and the /med self-test.

Generic install hub for oxide-medical. For framework-specific item registration, see the per-framework guides linked at the bottom. Follow this page first, then the guide for your framework.

Prerequisites

Required resources

Resource	Purpose
`ox_lib`	Shared library
`oxmysql`	Database persistence
`o-link`	Framework abstraction (character, inventory, notify, progress bar, death, needs, weather, logging)

Recommended and optional resources

Resource	Purpose
`oxide-ems`	Recommended. The EMS job that acts on the record — examines patients, runs the surgery pipeline, and treats every condition marked medic-only
`oxide-police`	Optional. Consumes the blood-evidence event and turns non-firearm bleeds into DNA-linked forensic evidence
`oxide-needs`	Optional. Pushes hunger, thirst and stress changes directly. Without it, the same values are read from character metadata through `o-link` on a poll
`oxide-weather`	Optional. Reports temperature and cover through the `o-link` weather bridge, which hypothermia needs and rain exposure asks first. Without a weather resource, rain falls back to the game's own weather and hypothermia does nothing
A resource that reports smoke, such as a fire resource	Optional. Reports players breathing smoke through `ReportExposure`, which becomes smoke inhalation. Without one, smoke inhalation never happens

What this resource is, and what it is not

oxide-medical is a system layer. It draws no interface of its own. It decides what is wrong with a player, keeps that state, applies the physical consequences, and exposes it all for other resources to read.

The visible parts a player experiences — limping, aim drift, blood on the ground, coughing, screen sway, vague "something is wrong" messages — come out of it directly. The diagnosis interface, the examine overlay, the operating table and the treatment economy live in oxide-ems.

You can run oxide-medical on its own. Players will get injured, bleed, fall ill, feel it, and be able to self-treat the simpler things with cure items. What they will not be able to do is get the serious injuries fixed, because those are deliberately marked medic-only.

`o-link` expectations

This resource depends on your server's o-link setup for:

player-ready and player-unload lifecycle events
the character identifier (the key every medical record is stored against)
inventory reads, item removal and usable-item registration for cure items
notifications and the treatment progress bar
downed and dead state, so the system pauses on an incapacitated player
hunger, thirst and stress (character metadata on every framework)
structured logging

Installation

Place the resource

Place oxide-medical inside your server's resources folder.

Add startup order

Start dependencies before the resource:

server.cfg

ensure ox_lib
ensure oxmysql
ensure o-link
ensure oxide-medical
ensure oxide-ems     # recommended — the EMS job that treats what this tracks

o-link must start before oxide-medical, and oxide-medical before oxide-ems.

The database

You do not need to import anything. oxide-medical creates its two tables the first time it starts:

medical_records — one row per character: blood type, DNA hash, immune stat, allergies, immunity windows, chronic conditions.
medical_conditions — one row per injury or illness: category, type, body part, severity, onset, expiry, and who treated it.

The database user in your mysql_connection_string (in server.cfg) needs permission to create tables, because oxide-medical checks its tables every time it starts. sql/install.sql is a reference copy of the same tables; you do not need to import it.

Starting a new version never changes the tables you already have. If you are upgrading from an earlier pre-release build, run sql/migrations/001_add_immune_system.sql. It is written to be safe to run more than once — it checks whether the column already exists and does nothing if it does.

A fresh install needs no migration.

Register the cure items

Register these item names in the inventory system behind your o-link.inventory adapter. Item registration syntax is framework-specific — see the per-framework guides for copy-paste examples.

All six cure items:

Item	Cures
`antibiotics`	Wound infection, and pneumonia (medic only)
`antiviral`	Influenza, and hepatitis (medic only)
`antacid`	Nausea, food poisoning
`painkillers`	Fever
`medical_bandage`	Gunshot wounds, lacerations
`medical_splint`	Broken arms, hands and feet — and broken legs when a medic does it

Check all six, including painkillers. It ships as a stock item on QBCore, ESX and Qbox, so it is usually already there — but plenty of servers run a trimmed or hand-written item list, and a missing painkillers entry is silent: using it does nothing and no error appears anywhere. Search your item list for each of the six names before you assume it is present.

medical_bandage and medical_splint are shared with oxide-ems. If you are installing both (the normal setup) you will be registering those two for oxide-ems anyway — register them once, not twice. If you are running oxide-medical on its own, register them here.

Copy item images

Images for all five items that are not stock ship inside itemimages/ in this resource: antacid, antibiotics, antiviral, medical_bandage and medical_splint. Copy the .png files into the image directory used by your inventory resource:

qb-inventory/html/images/
ox_inventory/web/images/

Every image file is named after its item. painkillers is a stock item on every supported framework and already has its own image — if yours is missing one, it came from your inventory resource, not from here.

Review configuration

oxide-medical is configured almost entirely in files, and there is no settings UI. Edit a file, restart the resource, and the change is live. The one exception is the hypothermia tuning in shared/config/weather.lua, which is copied into the oxide_settings table on first start and read from the database after that — see WeatherIntegration.

File	What it holds
`shared/config.lua`	System toggles: the immune stat, damage over time, blood decals, treatment, and the trigger layer
`shared/config/wounds.lua`	Weapon-to-class and bone-to-body-part maps, and the fracture rules
`shared/config/woundtypes.lua`	The wound catalog, and which weapon class produces which wound
`shared/config/fractures.lua`	The fracture catalog: body part, severity, physical effects, cure
`shared/config/diseases.lua`	The disease catalog: stages, symptoms, contagiousness, cure, immunity window
`shared/config/sickness.lua`	The sickness catalog, and the needs rules that trigger them
`shared/config/symptoms.lua`	What each symptom token does on screen
`shared/config/weather.lua`	First-start defaults for hypothermia from cold weather (database-backed after that)
`shared/config/exposure.lua`	Hazards other resources report, such as smoke, and what each dose does
`shared/config/vitals.lua`	The pulse, blood pressure, blood oxygen and cardiac arrest model
`shared/config/notifications.lua`	Every vague message a player can receive

Full per-setting reference: Configuration.

Everything worth tuning is in these files, and none of it needs code changes. The one setting most servers should look at first is Config.Damage — how much health severe untreated injuries drain, and how fast.

Make sure your admins can use `/med`

/med is admin-only. A player counts as an admin if they are in a group that has the admin permission.

If you have already set up admins for other Oxide resources (or for txAdmin), you are done. If not, add these two lines to your server.cfg, replacing the licence with your own:

server.cfg

# 1. Put your account in the "admin" group
add_principal identifier.license:abc123 group.admin

# 2. Give the "admin" group permission to use admin tools
add_ace group.admin admin allow

Save and restart. There is one admin level, and it works the same on QBCore, ESX and Qbox.

Verification

Join the server with an admin account and run:

/med test

This runs a self-test against your own character covering the whole export surface — record creation, blood type, DNA, the immune stat, adding and treating and removing conditions, expiry, offline reads, vitals and cardiac arrest — and prints a pass/fail line per check to the server console, ending in a summary.

If every check passes, the system is installed correctly.

Then check the parts a self-test cannot assert, because they are visual:

/med sim fracture — you should limp, move slower, and your aim should drift while shooting.
/med sim symptoms — you should start coughing periodically and the screen should sway.
/med sim bleed — you should leave blood decals on the ground as you walk, and lose health slowly.
/med record — should list everything you have just given yourself, and you should be getting vague notifications about it without ever being told what it is.
/med sim infection, then /med give me antibiotics and use the item — a progress bar should run and the infection should clear.
/med sim reset — should put you back to healthy.

If you are also running oxide-ems, have a medic examine you while you are carrying the injuries from step 1 — that overlay is where all of this becomes visible to a player.

Framework-Specific Setup

The steps above are generic. The exact item registration syntax differs per framework:

QBCore install guide — qb-core item entries.
ESX install guide — ox_inventory item entries.
Qbox install guide — ox_inventory item entries.

Notes

There is nothing to build. oxide-medical has no frontend.
oxide-medical does not talk directly to framework or inventory resources. Those integrations are expected to be handled by o-link.
Medical records are keyed on the character identifier, so each character on an account has their own separate record — injuries do not follow a player between characters.
Untreated conditions persist across disconnects and server restarts. That is deliberate: an injury you walk away from is still an injury tomorrow.

On this page