Configuration Reference

Complete reference for all Oxide 3D Weapon Printing configuration settings organized by config file.

Config File: shared/config.lua

General Settings

Setting	Type	Default	Description
`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.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	`'weaponbench'`	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 = 'weaponbench'
Config.BenchWeaponOffset = vector3(0.0, 0.0, 0.95)

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 = H). This is a FiveM control ID, not a letter — see the FiveM controls list for other keys
`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 52 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 },
        },
    },
    -- ... 52 weapon blueprints in total
}

Filament costs and print times scale with weapon tier:

Tier 1 pistols (sns_pistol, vintage_pistol, flare_gun): 1 filament, 600s (10 min) per part
Tier 2 pistols / Mini SMG: 2 filament, 1200s (20 min) per part
Advanced pistols / SMGs / standard rifles / standard shotguns / sniper rifle: 3 filament, 2100s (35 min) per part
Military rifles / military shotguns / marksman rifles / MG: 4 filament, 3000s (50 min) per part
Heavy snipers / Combat MGs: 5 filament, 4500s (75 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 },
        },
    },
    -- ... 52 assembly recipes in total
}

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

These are base values — the print and assembly rewards are multiplied by filament cost, so bigger weapons give more XP (see Features > XP Rewards).

Setting	Type	Default	Description
`Config.Progression.xpRewards.loadUsb`	number	`5`	XP for successfully loading a USB
`Config.Progression.xpRewards.printComplete`	number	`15`	XP per filament the part cost, awarded when a finished print is collected
`Config.Progression.xpRewards.assembleWeapon`	number	`30`	XP times the weapon's average part filament cost, awarded on assembly

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

The Config.Progression.blueprintLevels table maps each blueprint key to the minimum level required to print that weapon's parts. The Config.Progression.assemblyLevels table maps each assembly recipe key to the minimum level required to assemble that weapon. To make a weapon easier or harder to reach, change its number in both tables.

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

This file defines two independently-toggleable systems: Config.Durability (per-shot weapon decay and break-at-zero) and Config.Jam (jam roll and unjam animation). Either can run alone.

Config.Durability

Setting	Type	Default	Description
`Config.Durability.enabled`	boolean	`true`	Master switch for the printed-weapon degradation system. Disable when the host inventory has its own weapon decay (`ak47_qb_inventory`, `qs-inventory`, `codem-inventory`, etc.) to avoid double-decay or nil-quality crashes.
`Config.Durability.degradePerShot`	number	`0.15`	Durability percentage lost per shot
`Config.Durability.shotSyncInterval`	number	`10`	Shots between client-server durability syncs
`Config.Durability.breakAtZero`	boolean	`true`	Destroy weapon when durability reaches 0%

Config.Jam

Setting	Type	Default	Description
`Config.Jam.enabled`	boolean	`true`	Master switch for the jam mechanic. Independent of `Config.Durability.enabled`.
`Config.Jam.flatChance`	number	`5`	Per-shot jam chance (percent) used when `Config.Durability.enabled = false` and there is no durability number to derive a tier from.
`Config.Jam.durabilityTiers`	table	(see below)	Tier table used when `Config.Durability.enabled = true`. Maps durability ranges to jam chance percent.
`Config.Jam.unjamTime`	number	`3000`	Unjam animation duration in milliseconds
`Config.Jam.unjamAnim`	table	`{ dict, name }`	Animation played while unjamming

Config.Durability = {
    enabled = true,
    degradePerShot = 0.15,
    shotSyncInterval = 10,
    breakAtZero = true,
}

Config.Jam = {
    enabled = true,
    flatChance = 5,
    durabilityTiers = {
        { 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' },
}

When Config.Durability.enabled = false:

Freshly printed weapons are not given a durability field on their metadata.
The client never sends oxide:weaponprinting:syncShots, and the server ignores the event if it arrives.
Weapons never break from this resource — the host inventory's decay (if any) is the sole source.

Jam Chance Ranges (durability mode)

Used when Config.Durability.enabled = true. When durability tracking is disabled, the jam roll falls back to Config.Jam.flatChance.

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.