Configuration Reference

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

All settings live in shared/config.lua and the files inside shared/config/. Open them with any text editor (Notepad++, VS Code). After changing a setting, restart the resource (restart oxide-weaponprinting in the server console) for it to take effect.

Config File: shared/config.lua

General Settings

Setting	Type	Default	Description
`Config.SpawnDistance`	number	`100.0`	How close (in meters) a player must be before placed equipment appears for them
`Config.RequireOwnership`	boolean	`true`	When `true`, only the player who placed equipment can operate it or pick it up

Config.SpawnDistance = 100.0
Config.RequireOwnership = true

Per-Player Equipment Limits

How many of each piece of equipment one character can have placed in the world at the same time.

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

Areas where placing equipment is blocked. Empty by default (placement allowed everywhere).

Setting	Type	Default	Description
`Config.SafeZones`	table	`{}`	List of areas (outlined by corner points) where placement is blocked

Config.SafeZones = {}
-- Example: block placement in a rectangular area.
-- Each vec2(x, y) is one corner of the area on the map.
-- 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`	The 3D model used for the printer (included with the resource)
`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'

If you change an item name here, register the new name in your framework's items list instead (see Item Registration).

Camera Settings

Controls where the camera moves when a player uses a 3D printer. You usually won't need to touch these.

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 interaction prompt on printers (shown via ox_target).

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 the floating status labels above printers (toggled with a key while near a printer).

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 the parts each one can print. 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
}

Costs scale with how powerful the weapon is — from 1 filament and 600s (10 min) per part for starter pistols, up to 5 filament and 4500s (75 min) per part for heavy snipers and combat MGs. You can freely adjust any part's cost or time.

Config File: shared/config/items.lua

Defines regular items the printer can produce directly, with no bench assembly. Added in v1.0.1 as a preview feature. One example (a lockpick) ships enabled.

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	Where progression is saved on the character (`'weaponprinting'`). Don't change this after players have progress — they would appear to start over
`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,
}

Blueprint Level Gates

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. Both use the blueprint key (e.g. pistol = 1). To make a weapon easier or harder to reach, change its number in both tables.

Upgrade Level Gates

The minimum player level for each upgrade tier ([tier] = level):

Setting	Default
`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 Events

Each weapon assembly has a chance to come out worse than expected.

Setting	Type	Default	Description
`Config.Progression.badLuckChance`	number	`10`	Percent chance of a bad luck event per assembly
`Config.Progression.badLuckPenalty`	number	`15`	Quality points removed when it happens (quality can't drop below 5%)

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

Set badLuckChance = 0 to turn bad luck off entirely.

Experience Bonuses

Long-term play improves weapon quality.

Setting	Type	Default	Description
`Config.Progression.experienceBonus.printsPerBonus`	number	`50`	Lifetime prints needed per quality bonus milestone
`Config.Progression.experienceBonus.printBonusPercent`	number	`2`	Quality bonus per print milestone
`Config.Progression.experienceBonus.assembliesPerBonus`	number	`25`	Lifetime 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' },
}

gap is how many levels above the weapon's requirement the builder must be to reach that tier; min/max is the base quality range rolled at that tier.

Config File: shared/config/upgrades.lua

Upgrade Categories

Each upgrade category lists its items (one per tier) and what each tier does. psuRequired is which PSU tier must already be installed (0 = none).

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

For example, speedMultiplier [2] = 0.7 means a Mk II nozzle makes prints take 70% of their normal time (30% faster).

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 round fired
`Config.Durability.shotSyncInterval`	number	`10`	Shots between client-server durability saves (lower = more accurate, more server work)
`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 assembled 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 see-through preview props shown spinning on the printer while it prints. Each prop has a size (scale) and position (offset) so it sits nicely on the printer's 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.