Documentation
Using Miner Job: the job panel, crew missions, mine tiers, minerals and drop rates, pickaxes and durability, the jewellery furnace, selling, levels, leaderboards, achievements, rich veins, tournaments and the admin panel.
Everything starts at the job manager in the quarry. Walk up and press E — or use your target — and the camera cuts to a close-up of the manager while the panel opens beside him. The panel is open to everyone; only taking a mission and mining need the job.
Tab | What it does |
|---|---|
Missions | The contract list, your crew slots, invitations, and the button to start or abandon a mission. |
Shop | Buy pickaxes, and sell ore and jewellery one item at a time or all at once. |
Statistics |
The daily, season and all-time leaderboards, the time left until each reset, the prizes, the last winners and the tournament wins board.
Achievements | Milestones and per-mineral goals, your totals, and the Claim button for every finished one. |
Guide | The whole loop in six steps and four tips, read from the translation file — reword or delete any line there. |
Who the panel says you are talking to, and how players are named, are set at the top of config.lua:
Config.PedName = 'Duke Halloran'
Config.PedGreeting = "Pick a contract. The seam is not going anywhere, but the daylight is."
-- 'character' = first and last name, 'cfx' = FiveM name, 'both' = "Name (FiveM name)"
Config.PlayerNameSource = 'character'A mission asks for a number of each mineral. Every ore the crew cashes in counts toward it, the tracker updates for everyone, and the moment the last one lands the mission pays out and the outfit comes off. Five ship in Config.Tasks:
Mission | Level | Asks for | Pays |
|---|---|---|---|
Beginner's Excavation | 1 | 3 coal | $400 · 300 XP |
Novice's Excavation | 2 | 10 coal, 5 gold | $600 · 500 XP |
Apprentice's Excavation | 3 | 15 coal, 10 gold, 5 emerald | $1,000 · 800 XP |
Journeyman's Excavation | 4 | 20 gold, 15 emerald, 10 ruby | $1,500 · 1,200 XP |
Master's Excavation | 5 | 30 ruby, 20 amethyst, 10 diamond | $2,500 · 2,000 XP |
To add one, copy an entry and give it the next taskOrder. mineralAmount and mineralRequireds are read in pairs — the first amount belongs to the first mineral — and img picks one of the three covers, miner_img1.png to miner_img3.png.
{
taskOrder = 6,
name = "Deep Seam Contract",
img = "miner_img3.png",
description = "A long shift in the deepest tier.",
recommendedPlayers = { 2, 4 },
levelRequired = 8,
mineralAmount = { 20, 15 },
mineralRequireds = { "amethyst", "diamond" },
experience = 3000,
money = 4000,
},The leader invites by server id from the Missions tab. The other player has to be within Config.InviteDistance metres (20 by default, 0 turns the check off) and accepts a pop-up. A crew holds up to Config.MaxPartyMembers players including the leader, and every member has to meet the mission's level. With qs-party running, the leader's real party joins the crew automatically.
How a crew is paid is Config.MissionPayout:
Value | Behaviour |
|---|---|
| Every member gets the full money and experience. A crew of four on a $2,000 mission costs the server $8,000 — for the same haul one player would bring, since the amount asked for does not scale with the crew. |
| Money and experience are divided between the members still in the crew when it completes, rounded down and never below 1. |
Only players who still hold a mining job are paid. Abandoning from the panel, disconnecting or losing the job takes that player out of the mission and back into normal clothes; a promotion within the job does not.
Use the pickaxe item, or press Z to move it between your hand and your belt. Weapons have to be put away first, and attacking is blocked while it is in your hand.
Stand at a rock and press E. Each mineral needs its own number of swings, and every swing wears the pickaxe down. A rock in use by someone else is busy until they finish.
The broken rock goes into your arms. Walk it to the conveyor and press E at the prompt: the drops land in your inventory, the experience is paid and the mission advances. E anywhere else drops the rock.
After Config.RespawnTime milliseconds (5,000 by default) a fresh rock appears in the same spot, rolled again from that tier's odds.
Config.MinesLevels splits the mine into tiers, each with a minimum level, its own spawn odds and its own list of rock positions. Below the level, the rock refuses you.
Tier | Level | Spawn odds |
|---|---|---|
1 | 1 | Coal 80 · Gold 15 · Emerald 5 |
2 | 3 | Gold 60 · Emerald 30 · Ruby 10 |
3 | 6 | Ruby 70 · Amethyst 27 · Diamond 3 |
The odds of a tier should add up to 100. Every tier ships with a commented-out set of positions for the K4MB1 Cave map right under the default ones — swap them in, together with the alternatives under Config.Locations, if you run that map.
Config.Minerals says what each rock is worth and what it costs to break:
Mineral | Swings | Experience | Wear per swing | Drops |
|---|---|---|---|---|
Coal | 3 | 75 | 0.1 | Coal Ore, Flint 20%, Sulfur Chunk 10% |
Gold | 4 | 150 | 1 | Gold Nugget, Gold Dust 30%, Quartz Crystal 10% |
Emerald | 5 | 220 | 1 | Emerald Crystal, Beryl Chunk 25%, Green Garnet 10% |
Ruby | 6 | 280 | 1 | Ruby Crystal, Corundum Chunk 25%, Pink Sapphire 10% |
Amethyst | 7 | 310 | 1 | Amethyst Geode, Purple Quartz 30%, Clear Crystal 10% |
Diamond | 8 | 450 | 1 | Diamond Crystal, Graphite Chunk 20%, Blue Diamond 10% |
Each line of a mineral's items takes five values:
-- item name label chance max sell price
{ "coal_ore", "Coal Ore", 100, 4, 1 },chance — the percent chance this line drops at all, rolled once per rock. The pickaxe's bonus, level × LevelBonusMultiplier and an active rich vein are added on top, capped at 100. The first line of every mineral is 100: the ore itself always drops.
max — a ceiling, not the amount. The first unit is certain and each further one is less likely, so a 4 usually pays 1 or 2.
sell price — what one unit sells for in the shop. This is the only place it is set.
Pickaxes are bought in the panel's Shop tab. The server checks the level, the price and that the player does not already own one, delivers it, and only then takes the money from the player's cash.
Pickaxe | Level | Price | Durability | Drop bonus |
|---|---|---|---|---|
Rusty | 1 | $50 | 100 | 0% |
Stone-Crafted | 2 | $150 | 200 | 5% |
Iron-Edged | 3 | $300 | 300 | 10% |
Steel | 4 | $600 | 500 | 15% |
Diamond-Encrusted | 5 | $1,200 | 800 | 20% |
Mythical | 6 | $2,000 | 1,200 | 25% |
The drop bonus multiplies each line's chance, so a 20% line becomes 25% with the Mythical pickaxe. Every swing removes that mineral's durabilitypenalty; at zero the pickaxe breaks, plays its sound and leaves the inventory.
Config.InventoryPickaxe = true (default). The pickaxe is a real, usable item. On ox_inventory its durability is stored in the item's metadata and shows on the slot; on qs-inventory and the framework inventories the job keeps the durability itself.
Config.InventoryPickaxe = false. Nothing goes into the inventory: the shop hands out a prop the script tracks, with the same durability and bonus. No items need registering for it.
Where the prop sits in the hand and on the belt is Config.PickaxeAttachments — bone, position and rotation for each.
The furnace beside the job manager turns ore into jewellery. Walk up, press E, pick a recipe you have the level and materials for, and play the smelting minigame: bring the temperature up and hold it inside the band until it is stable. Higher-difficulty recipes are harder to hold.
Success — the materials are used, the piece and the recipe's experience are yours, and the clean-run counter goes up.
Failure or abandoning — the materials are lost and the clean run ends.
Full inventory — nothing is lost: the materials are handed back.
Twenty recipes ship, from the Gold Ring at level 1 to the Diamond Necklace at level 25. A recipe reads:
["Gold Ring"] = {
order = 1, -- position in the list
item = "gold_ring", -- what comes out
amount = 1, -- how many come out (optional, default 1)
levelRequired = 1,
itemsRequired = { "gold_nugget", "coal_ore", "graphite_chunk", "flint", "quartz_crystal" },
itemsLabels = { "Gold Nugget", "Coal Ore", "Graphite Chunk", "Flint", "Quartz Crystal" },
amountRequired = { "5", "3", "2", "2", "1" },
experience = 150,
sellPrice = 250, -- what the shop pays for one
difficulty = 1, -- 1 to 10, how hard the minigame is
},Ingredients do not have to be mining items — anything in your inventory can be asked for. To add a second furnace, add another entry to Config.Furnaces with its own coords, rotation and recipes; a commented example sits in config.lua.
The Shop tab lists everything you carry that the mine buys — raw ore at its Config.Minerals price and jewellery at its recipe's sellPrice — with the total. Sell one line or everything at once; the money is paid in cash. Prices are fixed and always re-read on the server.
The shop can also be opened on its own, without the job panel, from an NPC manager or any script: see openSellMenu. Change the currency symbol in the translation key CURRENCY_TYPE and its side with Config.CurrencyPosition ("prefix" → $500, "suffix" → 500 zł).
Experience comes from cashing in rocks, smelting, missions, achievements and tournaments. There is no level cap: each level costs BaseExperience × GrowthFactor^(level − 1) — 3,500 for the first, about 3,850 for the second, and so on. Each level also adds LevelBonusMultiplier percentage points to every drop chance.
Config.LevelExperience = {
LevelBonusMultiplier = 0.5, -- +0.5 drop chance per level
BaseExperience = 3500, -- experience for level 1
GrowthFactor = 1.1, -- how much each level grows
}The Statistics tab ranks miners by experience in three boards — daily (resets every day at 00:00 server time), season (resets at 00:00 on the first of each month) and all-time. At each reset the top three are paid; a winner who is offline has the prize banked and paid on their next login.
Config.EnableLeaderboard = true
Config.UpdateLeaderboard = 1 -- minutes between refreshes
Config.MaxLeaderboardPlayers = 100 -- miners shown per board
Config.LeaderBoardRewards = {
Daily = { [1] = 5215, [2] = 350, [3] = 200 },
Season = { [1] = 5000, [2] = 3500, [3] = 2000 },
}Achievements are counted on the server and do not pay themselves: a finished one waits in the Achievements tab until the player comes back to the manager and presses Claim. Nineteen milestones ship in Config.Achievements.List, plus one per mineral whose goal and reward are set per mineral in MineralGoal and MineralReward.
Type | Measures |
|---|---|
| Every ore ever extracted. |
| How many different minerals you have brought up. |
| How many of one mineral, named in |
| At least |
| The job level reached. |
| A tally named in |
| Every other achievement on the list. |
{ id = 'ruby_100', icon = 'gem', type = 'mineral', mineral = 'ruby', value = 100, reward = 4000, experience = 5000 },The id is also the translation key: ruby_100 reads ACHIEVEMENT_RUBY_100 and ACHIEVEMENT_RUBY_100_DESC from config/translations.lua.
Every so often one mineral — not a place — runs rich across the whole mine for Duration minutes. Miners are told, a clock appears on screen, and that mineral spawns more often, drops more and pays more experience while everything else stays as it was.
Config.RichVeins = {
Enabled = true,
Duration = 20, -- minutes
MinersOnly = true, -- only players with the job see and benefit
Boost = {
Spawn = 3.0, -- x spawn weight (taken from the other minerals)
DropChance = 25, -- + percentage points on each drop
Quantity = 1.6, -- x max amount, rounded up
Experience = 1.5, -- x experience
},
-- Relative weights of which mineral runs rich. 0 = never.
Minerals = { coal = 30, gold = 26, emerald = 18, ruby = 13, amethyst = 9, diamond = 4, default = 10 },
Random = { Enabled = true, MinInterval = 30, MaxInterval = 75 }, -- minutes between veins
}Set Random.Enabled = false to run them only by hand, from the Events tab of the admin panel.
A tournament runs across the whole mine — there is no zone to stand in. It is announced AnnounceBefore minutes ahead, runs for Duration minutes with a live board, and has two winners:
Biggest haul (most) — the most ore, every mineral counting the same.
Richest haul (richest) — the most points, where one diamond is worth twenty coal.
One miner can win both and is paid for each. Firsts are recorded on the tournament wins board and count toward the tournament achievements.
Config.Tournaments = {
Enabled = true,
Duration = 20,
AnnounceBefore = 5,
MinersOnly = true,
ShowResults = true,
Schedule = { { at = '13:00' }, { at = '18:00' }, { at = '22:00' } }, -- server time
Random = { Enabled = true, CheckEvery = 60, Chance = 25 },
Points = { coal = 1, gold = 3, emerald = 5, ruby = 8, amethyst = 12, diamond = 20, default = 5 },
Prizes = {
richest = { { money = 6000, experience = 4000 }, { money = 3000, experience = 2000 }, { money = 1200, experience = 900 } },
most = { { money = 4000, experience = 2500 }, { money = 2000, experience = 1200 }, { money = 800, experience = 600 } },
},
MinimumEntries = 1, -- entrants needed before anything is paid
}/mineradmin opens an in-game editor for every setting in config.lua, grouped into sections — Job & NPC, The mine, Minerals, Pickaxes, Furnaces, Missions & crew, Levels & records, Events, Setup and Other — with a search box and each setting's own help text.
Saves go to the database, not to the file. config.lua is never rewritten; the saved value is laid over it at start-up.
A save takes effect on the next restart of the resource. The panel shows a banner while saved settings are waiting.
Back to the file's value resets one setting; Reset everything deletes every saved setting so the file takes over again.
Any coordinate can be filled with Use my position, visited with Go there, or marked with Waypoint.
The Events tab starts or stops a rich vein (pick the mineral, or leave it to chance) and a tournament, for the minutes you type. These act immediately.
Who can open it is Config.AdminPanel.Ace — command.miner by default, and group.admin always works too. The usual add_ace group.admin command allow already covers it, so most servers have nothing to add. To give it to someone else, in server.cfg or the server console:
add_ace group.miner command.miner allow
add_principal identifier.fivem:1234567 group.minerConfig.AdminPanel = {
Enabled = true,
Ace = 'command.miner', -- false = anyone may open it
ConfigCommand = 'mineradmin', -- '' registers no command
}Config.Locations holds the Mining Zone blip (public = true shows it to everyone), the job manager's model and position, and where the conveyor's deposit prompt is drawn. Leave Config.NewCoords as it is.
The floating marker over the manager is Config.PedMarker: switch it off, or change its type (any FiveM marker id), height, distance, bob, size and RGBA color.
Keys are FiveM control ids in
Config.Keys:TogglePickaxe = 20(Z),InteractKey = 38andMineStone = 38(E). The full list is in the FiveM controls reference.