Configuration Reference

Config File: shared/config.lua

General Settings

Setting	Type	Default	Description
Config.Debug	boolean	false	Enable debug output to server console with [oxide-weaponprinting] prefix
Config.SpawnDistance	number	100.0	Distance at which placed equipment spawns for clients
Config.RequireOwnership	boolean	true	Only the player who placed equipment can pick it up

Config.Debug = false
Config.SpawnDistance = 100.0
Config.RequireOwnership = true

Per-Player Equipment Limits

Setting	Type	Default	Description
Config.MaxPerPlayer.printers	number	3	Maximum 3D printers a player can have placed
Config.MaxPerPlayer.benches	number	2	Maximum weapon benches a player can have placed
Config.MaxPerPlayer.tables	number	5	Maximum tables a player can have placed

Config.MaxPerPlayer = {
    printers = 3,
    benches = 2,
    tables = 5,
}

Set any value to 0 to disable the limit for that equipment type.

Safe Zones

Setting	Type	Default	Description
Config.SafeZones	table	{}	Array of polygon zones where placement is blocked

Config.SafeZones = {}
-- Example: Block placement in a rectangular area
-- Config.SafeZones = {
--     {
--         points = {
--             vec2(100.0, 100.0),
--             vec2(200.0, 100.0),
--             vec2(200.0, 200.0),
--             vec2(100.0, 200.0),
--         },
--     },
-- }

Printer Settings

Setting	Type	Default	Description
Config.PrinterModel	hash	`prop_3d_printer`	Model hash for the 3D printer prop
Config.PrinterItem	string	'3d_printer'	Item name that places a printer
Config.FilamentItem	string	'printer_filament'	Item consumed during printing
Config.UsbItem	string	'printer_usb'	Item used to load blueprints

Config.PrinterModel = `prop_3d_printer`
Config.PrinterItem = '3d_printer'
Config.FilamentItem = 'printer_filament'
Config.UsbItem = 'printer_usb'

Camera Settings

Controls the camera angle when interacting with a 3D printer.

Setting	Type	Default	Description
Config.Camera.offset	vector3	vector3(0.0, -0.8, 0.6)	Camera offset from printer position
Config.Camera.rot	vector3	vector3(-15.0, 0.0, 0.0)	Camera rotation (pitch, roll, yaw)
Config.Camera.fov	number	70.0	Field of view in degrees
Config.Camera.transitionMs	number	500	Transition duration in milliseconds

Config.Camera = {
    offset = vector3(0.0, -0.8, 0.6),
    rot = vector3(-15.0, 0.0, 0.0),
    fov = 70.0,
    transitionMs = 500,
}

Target Settings

Controls the ox_target interaction zone for printers.

Setting	Type	Default	Description
Config.Target.icon	string	'fas fa-print'	Font Awesome icon class
Config.Target.label	string	'Use Printer'	Interaction label text
Config.Target.distance	number	1.5	Interaction distance in meters

Config.Target = {
    icon = 'fas fa-print',
    label = 'Use Printer',
    distance = 1.5,
}

Bench Settings

Setting	Type	Default	Description
Config.BenchModel	hash	`gr_prop_gr_bench_04b`	Model hash for the weapon bench prop
Config.BenchItem	string	'weapon_bench'	Item name that places a bench
Config.BenchWeaponOffset	vector3	vector3(0.0, 0.0, 0.95)	Offset for the weapon preview model on the bench

Config.BenchModel = `gr_prop_gr_bench_04b`
Config.BenchItem = 'weapon_bench'
Config.BenchWeaponOffset = vector3(0.0, 0.0, 0.95)

ox_inventory users: items prefixed with weapon_ are treated as weapons by ox_inventory, so the default weapon_bench won't work. Rename the item (e.g. weaponbench) when registering it in ox_inventory/data/items.lua and set Config.BenchItem to match.

Bench Camera Settings

Controls the camera angle when interacting with a weapon bench.

Setting	Type	Default	Description
Config.BenchCamera.offset	vector3	vector3(0.0, -1.0, 1.5)	Camera offset from bench position
Config.BenchCamera.rot	vector3	vector3(-20.0, 0.0, 0.0)	Camera rotation
Config.BenchCamera.fov	number	65.0	Field of view
Config.BenchCamera.transitionMs	number	500	Transition duration in milliseconds

Config.BenchCamera = {
    offset = vector3(0.0, -1.0, 1.5),
    rot = vector3(-20.0, 0.0, 0.0),
    fov = 65.0,
    transitionMs = 500,
}

Bench Target Settings

Controls the ox_target interaction zone for weapon benches.

Setting	Type	Default	Description
Config.BenchTarget.icon	string	'fas fa-wrench'	Font Awesome icon class
Config.BenchTarget.label	string	'Use Workbench'	Interaction label text
Config.BenchTarget.distance	number	1.5	Interaction distance in meters

Config.BenchTarget = {
    icon = 'fas fa-wrench',
    label = 'Use Workbench',
    distance = 1.5,
}

Craft Animation

Controls the animation played during weapon assembly.

Setting	Type	Default	Description
Config.CraftAnimation.dict	string	'mini@repair'	Animation dictionary
Config.CraftAnimation.name	string	'fixing_a_player'	Animation name

Config.CraftAnimation = {
    dict = 'mini@repair',
    name = 'fixing_a_player',
}

Label Settings

Controls floating 3D labels above printers and benches.

Setting	Type	Default	Description
Config.Labels.toggleKey	number	74	Key code to toggle labels (74 = J)
Config.Labels.maxDist	number	5.0	Maximum render distance in meters
Config.Labels.scaleMin	number	0.55	Minimum text scale at far distance
Config.Labels.scaleMax	number	1.0	Maximum text scale at near distance
Config.Labels.scaleNearDist	number	1.5	Distance where max scale applies
Config.Labels.scaleFarDist	number	4.0	Distance where min scale applies
Config.Labels.heightOffset	number	1.2	Height above equipment in meters
Config.Labels.updateInterval	number	16	Render update interval in milliseconds
Config.Labels.dataRefreshMs	number	2000	Data refresh interval in milliseconds

Config.Labels = {
    toggleKey = 74,
    maxDist = 5.0,
    scaleMin = 0.55,
    scaleMax = 1.0,
    scaleNearDist = 1.5,
    scaleFarDist = 4.0,
    heightOffset = 1.2,
    updateInterval = 16,
    dataRefreshMs = 2000,
}

Table Settings

Setting	Type	Default	Description
Config.TableModel	hash	`bkr_prop_weed_table_01b`	Model hash for the placeable table
Config.TableItem	string	'placeable_table'	Item name that places a table

Config.TableModel = `bkr_prop_weed_table_01b`
Config.TableItem = 'placeable_table'

Config File: shared/config/blueprints.lua

Defines all weapon blueprints and their printable parts. Each blueprint contains an array of parts with the following structure:

Field	Type	Description
id	string	Unique part identifier within the blueprint
label	string	Display name for the part
item	string	Item name given when the part is printed
model	string	Prop model name for the ghost prop during printing
filamentCost	number	Filament items consumed per print
printTime	number	Base print duration in seconds

Config.Blueprints = {
    pistol = {
        label = 'Pistol',
        parts = {
            { id = 'slide', label = 'Slide', item = '3d_printed_pistol_slide', model = 'prop_pistol_slide', filamentCost = 2, printTime = 1200 },
            { id = 'grip', label = 'Grip', item = '3d_printed_pistol_grip', model = 'prop_pistol_grip', filamentCost = 2, printTime = 1200 },
            { id = 'clip', label = 'Magazine', item = '3d_printed_pistol_clip', model = 'prop_pistol_clip', filamentCost = 2, printTime = 1200 },
        },
    },
    -- ... 60+ weapon blueprints
}

Filament costs and print times scale with weapon tier:

• Tier 1 pistols: 1 filament, 600s (10 min) per part
• Tier 2 pistols: 2 filament, 1200s (20 min) per part
• Advanced pistols: 3 filament, 2100s (35 min) per part
• Rifles: 3-4 filament, 2400-3600s (40-60 min) per part

Config File: shared/config/items.lua

Defines non-weapon items that can be printed directly from the printer without bench assembly. Added in v1.0.1 as a preview feature.

Config.ItemPrints

Each entry defines a printable item. The key is used as the blueprint identifier and in the blueprint metadata field of a printer_usb item.

Field	Type	Required	Description
label	string	Yes	Display name shown in the printer NUI and notifications
item	string	Yes	Inventory item name given when the print is collected
model	string or nil	No	Ghost prop model name for preview during printing. Set to nil to skip preview
filamentCost	number	Yes	Number of filament items consumed when starting the print
printTime	number	Yes	Base print duration in seconds (before nozzle upgrades)

Config.ItemPrints = {
    lockpick = {
        label        = 'Lockpick',
        item         = 'lockpick',
        model        = 'm25_1_prop_m51_lockpick_01a',
        filamentCost = 2,
        printTime    = 900,
    },
    -- radio = {
    --     label        = 'Radio',
    --     item         = 'radio',
    --     model        = nil,
    --     filamentCost = 3,
    --     printTime    = 1200,
    -- },
}

Notes

• Keys in Config.ItemPrints must not collide with keys in Config.Blueprints. If a key exists in both, the weapon blueprint takes priority.
• To gate an item behind a player level, add the key to Config.Progression.blueprintLevels in shared/config/progression.lua.
• To define a ghost prop scale and offset for the preview, add the model name to Config.GhostProps in shared/config/ghostprops.lua.
• Items produced by item prints carry no quality, durability, or serial metadata — they are plain inventory items.

Config File: shared/config/assembly.lua

Defines weapon assembly recipes for the weapon bench. Each recipe specifies the weapon to produce and the parts required.

Field	Type	Description
weapon	string	GTA weapon hash name (e.g., 'weapon_pistol')
label	string	Display name
model	string	Weapon model for preview on bench
craftTime	number	Assembly duration in seconds
parts	table	Array of required parts with item, label, and amount

Config.Assembly = {
    pistol = {
        weapon = 'weapon_pistol', label = 'Pistol', model = 'w_pi_pistol', craftTime = 30,
        parts = {
            { item = '3d_printed_pistol_slide', label = 'Pistol Slide', amount = 1 },
            { item = '3d_printed_pistol_grip', label = 'Pistol Grip', amount = 1 },
            { item = '3d_printed_pistol_clip', label = 'Magazine', amount = 1 },
        },
    },
    -- ... 60+ assembly recipes
}

Craft times range from 20 seconds (basic pistols) to 90 seconds (heavy snipers, combat MGs, exotic weapons).

Config File: shared/config/progression.lua

Level Requirements

Setting	Type	Description
Config.Progression.metadataKey	string	Player metadata key ('weaponprinting')
Config.Progression.levels	table	Array of { level, xpRequired } entries

Config.Progression = {
    metadataKey = 'weaponprinting',
    levels = {
        { level = 1,  xpRequired = 0 },
        { level = 2,  xpRequired = 200 },
        { level = 3,  xpRequired = 600 },
        { level = 4,  xpRequired = 1400 },
        { level = 5,  xpRequired = 2800 },
        { level = 6,  xpRequired = 5000 },
        { level = 7,  xpRequired = 8500 },
        { level = 8,  xpRequired = 14000 },
        { level = 9,  xpRequired = 22000 },
        { level = 10, xpRequired = 35000 },
    },
}

XP Rewards

Setting	Type	Default	Description
Config.Progression.xpRewards.loadUsb	number	5	XP for loading a USB into a printer
Config.Progression.xpRewards.printComplete	number	15	XP for completing a print
Config.Progression.xpRewards.assembleWeapon	number	30	XP for assembling a weapon

Config.Progression.xpRewards = {
    loadUsb = 5,
    printComplete = 15,
    assembleWeapon = 30,
}

Blueprint Level Gates

The Config.Progression.blueprintLevels table maps each blueprint key to the minimum level required to load its USB into a printer. The Config.Progression.assemblyLevels table maps each assembly recipe key to the minimum level required to assemble that weapon.

Upgrade Level Gates

Setting	Description
Config.Progression.upgradeLevels.nozzle	{ [1] = 1, [2] = 3, [3] = 6 }
Config.Progression.upgradeLevels.storage	{ [1] = 1, [2] = 3, [3] = 6 }
Config.Progression.upgradeLevels.cooling	{ [1] = 1, [2] = 3, [3] = 6 }
Config.Progression.upgradeLevels.buildplate	{ [1] = 2, [2] = 4, [3] = 7 }
Config.Progression.upgradeLevels.psu	{ [1] = 2, [2] = 5 }

Bad Luck Protection

Setting	Type	Default	Description
Config.Progression.badLuckChance	number	10	Percentage chance of a bad luck event during assembly
Config.Progression.badLuckPenalty	number	15	Quality percentage points deducted from the assembled weapon (minimum 5%)

Config.Progression.badLuckChance = 10
Config.Progression.badLuckPenalty = 15

Experience Bonuses

Setting	Type	Default	Description
Config.Progression.experienceBonus.printsPerBonus	number	50	Prints needed per quality bonus milestone
Config.Progression.experienceBonus.printBonusPercent	number	2	Quality bonus per print milestone
Config.Progression.experienceBonus.assembliesPerBonus	number	25	Assemblies needed per quality bonus milestone
Config.Progression.experienceBonus.assemblyBonusPercent	number	3	Quality bonus per assembly milestone
Config.Progression.experienceBonus.maxBonus	number	20	Maximum combined quality bonus percentage

Config.Progression.experienceBonus = {
    printsPerBonus = 50,
    printBonusPercent = 2,
    assembliesPerBonus = 25,
    assemblyBonusPercent = 3,
    maxBonus = 20,
}

Quality Grades

Setting	Type	Description
Config.Progression.quality	table	Array defining quality tiers with gap, min, max, and grade

Config.Progression.quality = {
    { gap = 0, min = 20, max = 30, grade = 'Poor' },
    { gap = 1, min = 35, max = 45, grade = 'Decent' },
    { gap = 2, min = 50, max = 60, grade = 'Standard' },
    { gap = 3, min = 65, max = 75, grade = 'Quality' },
    { gap = 4, min = 80, max = 90, grade = 'Superior' },
}

The gap value is the minimum level difference between your level and the recipe's required level to reach that quality tier.

Config File: shared/config/upgrades.lua

Upgrade Categories

Each upgrade category defines its tiers, required items, and stat effects:

Config.Upgrades = {
    nozzle = {
        label = 'Nozzle',
        maxTier = 3,
        items = { 'printer_nozzle_mk1', 'printer_nozzle_mk2', 'printer_nozzle_mk3' },
        speedMultiplier = { [0] = 1.0, [1] = 0.85, [2] = 0.7, [3] = 0.55 },
        psuRequired = { [1] = 0, [2] = 1, [3] = 2 },
    },
    storage = {
        label = 'Storage Drive',
        maxTier = 3,
        items = { 'printer_storage_mk1', 'printer_storage_mk2', 'printer_storage_mk3' },
        slots = { [0] = 1, [1] = 3, [2] = 5, [3] = 8 },
        psuRequired = { [1] = 0, [2] = 1, [3] = 2 },
    },
    cooling = {
        label = 'Cooling Fan',
        maxTier = 3,
        items = { 'printer_cooling_mk1', 'printer_cooling_mk2', 'printer_cooling_mk3' },
        malfunctionReduction = { [0] = 0, [1] = 10, [2] = 20, [3] = 30 },
        psuRequired = { [1] = 0, [2] = 0, [3] = 1 },
    },
    buildplate = {
        label = 'Build Plate',
        maxTier = 3,
        items = { 'printer_buildplate_mk1', 'printer_buildplate_mk2', 'printer_buildplate_mk3' },
        qualityBonus = { [0] = 0, [1] = 3, [2] = 6, [3] = 10 },
        psuRequired = { [1] = 0, [2] = 1, [3] = 2 },
    },
    psu = {
        label = 'Power Supply',
        maxTier = 2,
        items = { 'printer_psu_mk1', 'printer_psu_mk2' },
    },
}

USB Malfunction

Setting	Type	Default	Description
Config.UsbMalfunction.baseChance	number	25	Base percentage chance of USB destruction on load
Config.UsbMalfunction.levelReduction	number	1.5	Percentage reduction per player level
Config.UsbMalfunction.minimumChance	number	5	Lowest possible malfunction chance

Config.UsbMalfunction = {
    baseChance = 25,
    levelReduction = 1.5,
    minimumChance = 5,
}

Formula: chance = max(minimumChance, baseChance - (playerLevel * levelReduction) - coolingReduction)

Config File: shared/config/durability.lua

Setting	Type	Default	Description
Config.Durability.degradePerShot	number	0.15	Durability percentage lost per shot
Config.Durability.unjamTime	number	3000	Unjam animation duration in milliseconds
Config.Durability.shotSyncInterval	number	10	Shots between client-server durability syncs
Config.Durability.breakAtZero	boolean	true	Destroy weapon when durability reaches 0%

Config.Durability = {
    degradePerShot = 0.15,
    jamChance = {
        { maxDurability = 100, minDurability = 80, chance = 0 },
        { maxDurability = 80,  minDurability = 60, chance = 2 },
        { maxDurability = 60,  minDurability = 40, chance = 5 },
        { maxDurability = 40,  minDurability = 20, chance = 10 },
        { maxDurability = 20,  minDurability = 0,  chance = 20 },
    },
    unjamTime = 3000,
    unjamAnim = { dict = 'anim@mp_player_intupperknuckle_crunch', name = 'idle_a' },
    shotSyncInterval = 10,
    breakAtZero = true,
}

Jam Chance Ranges

Durability Range	Jam Chance	Description
80-100%	0%	No jams at high durability
60-80%	2%	Rare jams begin
40-60%	5%	Noticeable jam frequency
20-40%	10%	Frequent jams
0-20%	20%	Very frequent jams, weapon near breaking

Config File: shared/config/ghostprops.lua

Controls the appearance of ghost props during printing. Each prop has a scale and vertical offset for positioning on the printer build plate.

Setting	Type	Default	Description
Config.GhostPropDefaults.alpha	number	170	Transparency (0-255) of the ghost prop
Config.GhostPropDefaults.rotationSpeed	number	0.7	Rotation speed of the ghost prop during printing

Individual prop entries in Config.GhostProps control scale and offset per model. These rarely need modification.

Next Steps

• Features - Understand the gameplay mechanics these settings control
• Admin - Admin commands for testing configuration changes
• Troubleshooting - Common issues related to misconfiguration