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, 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

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.

Install the SQL tables

Run sql/install.sql against your database. It creates two tables:

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.

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.

Fresh installs only need install.sql.

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.

These three belong to oxide-medical:

Item	Cures
`antibiotics`	Wound infection, and pneumonia (medic only)
`antiviral`	Influenza, and hepatitis (medic only)
`antacid`	Nausea, food poisoning

These two are shared with oxide-ems and are named by the fracture and wound catalogs:

Item	Cures
`medical_bandage`	Gunshot wounds, lacerations
`medical_splint`	Broken arms, hands and feet — and broken legs when a medic does it

If you are installing oxide-ems alongside this (the normal setup), you will be registering medical_bandage and medical_splint for it anyway. If you are running oxide-medical on its own, register them here.

One item you almost certainly already have:

Item	Cures
`painkillers`	Fever

painkillers ships as a stock item on QBCore, ESX and Qbox, so there is normally nothing to add.

Copy item images

Images for antacid, antibiotics and antiviral — along with medical_bandage and medical_splint — ship inside oxide-ems/itemimages/, since the two resources are distributed together. 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.

Review configuration

oxide-medical is configured entirely in files, and there is no settings UI and no database-backed configuration. Edit a file, restart the resource, and the change is live.

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/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