#📦 INSTALLATION

resources/
└── [FIXITFY]/
    └── fx-fishing/

• Place the resource folder inside your server's resources directory
• Add ensure fx-fishing to your server.cfg below your framework, ox_lib and inventory
• No SQL to run — every table and column is created automatically on first start

---

#⚙️ DEPENDENCIES

textox_lib            ← required (skill check, callbacks, context menu, text UI)
oxmysql           ← required (database)
qb-core           ← only if using QBCore
qbx_core          ← only if using Qbox
es_extended       ← only if using ESX

Optional — the script runs fully without them

textox_target / qb-target        ← falls back to an [E] key prompt
ps-dispatch / cd_dispatch    ← police alerts for poaching and illegal diving
LegacyFuel / cdn-fuel        ← full fuel tank on rented boats
qb-vehiclekeys               ← automatic keys for rented boats
illenium-appearance          ← exact outfit restore after diving
scuba clothing pack          ← diving gear visuals

• Framework, inventory and target system are all auto-detected — no configuration needed
• Every optional resource is detected at runtime and skipped when missing

---

#🗄️ SERVER.CFG

QBCore

ensure ox_lib
ensure oxmysql
ensure qb-core
ensure qb-inventory
ensure fx-fishing

Qbox

ensure ox_lib
ensure oxmysql
ensure qbx_core
ensure ox_inventory
ensure fx-fishing

ESX

ensure ox_lib
ensure oxmysql
ensure es_extended
ensure fx-fishing

• After a successful start you will see [fx-fishing] Framework: QB | Inventory: OX in the console
• If it prints none, the resource started too early — fix the order or set Config.Framework manually

---

#🗃️ ITEM REGISTRATION

The resource uses 36 items (21 fishing + 15 diving). Apply only one file for your inventory.

ox_inventory — paste into ox_inventory/data/items.lua

lua['fishingrod_basic'] = { label = 'Starter Rod', weight = 1200, stack = false, close = true },
['worm']             = { label = 'Worm', weight = 50, stack = true, close = true },

tgiann / qs-inventory — paste into your items file

luafishingrod_basic = { name = 'fishingrod_basic', label = 'Starter Rod', weight = 1200,
                     type = 'item', image = 'fishingrod_basic.png', unique = true, useable = true },

qb-inventory — paste into qb-core/shared/items.lua

lua['fishingrod_basic'] = {['name'] = 'fishingrod_basic', ['label'] = 'Starter Rod', ['weight'] = 1200,
                        ['type'] = 'item', ['image'] = 'fishingrod_basic.png', ['unique'] = true, ['useable'] = true},

ESX default inventory — run setup/items/esx-items.sql once

sqlINSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
    ('fishingrod_basic', 'Starter Rod', 1200, 0, 1),
    ('worm', 'Worm', 50, 0, 1)
ON DUPLICATE KEY UPDATE `label` = VALUES(`label`);

• Ready-to-paste files for all four are in setup/items/ — the snippets above are just samples
• Safe to re-run — the SQL uses ON DUPLICATE KEY UPDATE
• Item names are case-sensitive and must not be renamed
• Useable items: all rods (start fishing) and diving_suit (equip gear) — auto-detected on ox and tgiann

---

#🖼️ ITEM ICONS

setup/images/{itemName}.png     →     your inventory's image folder

• All 36 icons are included in setup/images/
• The career panel ships with its own copies — you never need to touch inventoryimages/

---

#🌐 LANGUAGE

lua-- config/config.lua
Config.Locale = "en"  -- "en" | "tr"

• English and Turkish are included
• To add a language, copy locale/locales/en.lua to xx.lua, change Locales["en"] to Locales["xx"], and add it to shared_scripts in fxmanifest.lua
• Every player-facing string lives in the locale files — nothing is hardcoded

---

#🎮 COMMANDS

• Player command names are configurable: Config.OpenLogCommand, Config.Diving.toggleCommand, Config.Diving.Menu.command, Config.Anchor.command
• Admin access is ACE based — see SvConfig.AdminAces in config/sv_config.lua

---

#🐟 FISHING ZONES

Zones are defined in config/config_zones.lua.

lua{
    id       = "coral_reef",              -- must match the key in SvConfig.ZonePools
    label    = L("zone_coral_reef_label"),
    coords   = vector3(-1774.06, -1796.27, 0.0),
    radius   = 250.0,                     -- players must be inside this area
    levelReq = 1,                         -- fishing level required
    waitMin  = 5000,  waitMax = 11000,    -- wait time before a bite (ms)
    blip     = { enabled = true, sprite = 356, color = 3, scale = 0.75 },
    illegal  = true,                      -- optional: poaching is also possible here
},

Catch pools live server-side in config/sv_config.lua:

luaSvConfig.ZonePools = {
    coral_reef = {
        { fish = "bass", weight = 38 },   -- higher weight = spawns more often
        { fish = "carp", weight = 32 },
    },
}

• 12 species across 6 example zones out of the box
• Rain and thunder increase the weight of rare species (SvConfig.WeatherRareBoost)
• All shipped coordinates are vanilla-map examples — update them for your own map

---

#🚤 TRADERS & BOAT RENTAL

Defined in config/config_shop.lua. Boat rental is part of a trader, not a separate NPC.

lua{
    id       = "delperro_trader",
    coords   = vector4(-1823.33, -1245.38, 13.16, 54.42),
    model    = `a_m_m_fatlatin_01`,
    scenario = "WORLD_HUMAN_CLIPBOARD",
    blip     = { enabled = true },

    boatRental = {
        enabled     = true,
        spawnPoint  = vector4(-1793.66, -1245.48, 0.29, 0.0),   -- must be ON WATER
        returnPoint = vector3(-1797.84, -1227.95, 0.16),
    },
},

• 5 traders and 5 vessels configured by default
• Config.BoatRental.returnAtAnyLocation → return a boat at any rental point
• Anchor system freezes the boat at calm water level so waves never drag it away
• Casting from a boat drops the anchor automatically (Config.Anchor.autoAnchorOnCast)

---

#🚨 POACHING

Defined in config/config_illegal.lua. No separate zone list — just set illegal = true on a fishing zone.

luaConfig.Illegal = {
    restrictHours   = true,
    activeHourStart = 22,   -- 22:00
    activeHourEnd   = 5,    -- 05:00

    heat = {
        perCastIncrease       = 8,    -- heat gained per cast (0-100)
        decreasePerMinuteAway = 15,
        catchChanceAt100Heat  = 55,   -- % chance of a dispatch at full heat
    },

    dispatch = { export = "ps-dispatch" },  -- "ps-dispatch" | "cd_dispatch" | "none"
    seizePercentOnCaught = 60,              -- % of illegal catch seized when caught
}

• Requires the Black Market Rod + Illegal Bait — normal gear will not work
• A hidden black market buyer pays far more than legal traders
• Alerts are sent only to the offending player's client — the dispatch resource distributes them

---

#🤿 DIVE SITES

Defined in config/config_diving.lua. Diving has its own level track, completely separate from fishing.

lua{
    id           = "deep_reef",
    coords       = vector3(-2100.0, -1400.0, -35.0),   -- SEABED centre, z must be negative
    radius       = 60.0,
    diveLevelReq = 5,
    crateCount   = 6,                                   -- multiplied by crew size in crew dives
    crateModels  = { `tr_prop_tr_chest_01a` },
    lootPool     = "reef",                              -- key from SvConfigDiving.LootPools
    illegal      = false,                               -- true: requires a dive knife + dispatch risk
    searchTimeMs = 7000,
    cooldownSec  = 1800,                                -- optional per-site override
},

• 9 sites across 5 difficulty tiers, including 2 illegal wrecks
• Crates belong to a mission, not the world — players never steal each other's loot
• Config.Diving.CrateSeabedRaycast = true → an approximate z is enough, crates settle on the real seabed
• Site cooldown is written when the mission starts and is tied to the character identifier, so abandoning or reconnecting cannot reset it

---

#🫁 OXYGEN

lua-- config/config_diving.lua
Config.Diving.Oxygen = {
    fullTankSeconds = 320,   -- how long one tank lasts underwater
    warnAt          = 25,    -- % warning threshold
    criticalAt      = 10,    -- % critical threshold
    autoSwapTank    = true,  -- consumes a spare tank automatically
    graceSeconds    = 10,    -- grace period before damage starts
    damagePerTick   = 3,
    damageTickMs    = 1200,
    autoEndAfterEmptySeconds = 20,   -- safety net: dive ends, damage stops
}

• damagePerTick, damageTickMs and graceSeconds together define time-to-death — it must be long enough to swim up from your deepest site
• Drowning protection stays active until the player reaches the surface, so removing gear underwater never kills instantly
• A tank is consumed the moment a dive starts, so re-equipping cannot refill oxygen for free

---

#👥 DIVING CREWS

lua-- config/config_diving.lua
Config.Diving.Team = {
    maxSize            = 8,
    inviteRadius       = 10.0,
    maxCrates          = 24,     -- cap on crates per crew mission
    minMembersForBonus = 2,      -- solo "crews" get no bonus
    xpMultiplier       = 1.5,

    MemberMarkers = {
        blips    = true,
        marker3d = true,
        partyHud = true,         -- health / oxygen / distance panel
        zoneOnly = true,         -- markers only inside the mission area
    },
}

• Roles: leader → admin → member, with invite, kick, promote, demote and transfer
• Crate count scales with crew size, so crates-per-player stay the same as solo
• The party is locked during a mission — no members can be added or removed mid-run
• zoneOnly = true prevents the crew markers from being abused as a player tracker

---

#🏆 CAREER PANEL

Configured in config/config_career.lua, opened with /fishinglog.

luaConfig.Career.Season = {
    monthly      = true,   -- new season on the 1st of every month, points reset automatically
    pointsTarget = 5000,
    catchPoints  = 10,     -- season points per catch
    sellPointsPer = 0.02,  -- season points per $1 sold
}

Config.Career.Market = {
    enabled       = true,
    updateMinutes = 5,     -- server-wide price multiplier drift
    minMult       = 0.72,
    maxMult       = 1.35,
}

• 31 story missions (22 fishing + 9 diving) and 18 achievements
• Daily & weekly quests picked deterministically from a pool — identical for every player
• 7-day login streak rewards, Fisher Pass with 9 claimable tiers
• Dynamic market with live price charts and demand indicators
• Weekly and all-time leaderboards, full collection and statistics pages
• 6 built-in themes, switchable by the player and remembered locally

---

#🔐 SECURITY

Every reward path is server-authoritative.

textCast          ← position verified against the real ped, zone, vehicle type, level,
                rod & bait ownership, plus a rate limit
Sale          ← trader proximity, item ownership, amount bounds, all-or-nothing
Purchase      ← proximity, level requirement, funds, refund on inventory failure
Boat rental   ← trader proximity on rent AND on return
Crate search  ← mission ownership, 2D distance, below-sea-level check, rate limit
Rewards       ← claims written to the database immediately, so a restart cannot replay them

• Prices, catch chances and loot tables live in sv_config.lua / sv_config_diving.lua and are never sent to the client
• The treasure radar sends only an angle and a 0-1 heat value — crate coordinates never leave the server
• Fish and treasure are added without metadata, so items always stack correctly

---

#⚠️ TROUBLESHOOTING

• Console prints Framework: none → the resource started before your framework, or set Config.Framework manually
• No item is given when catching a fish → item definitions were not added, or the item name does not match exactly
• Item icons are blank → the PNGs from setup/images/ were not copied to your inventory's image folder
• "You must be in a permitted fishing zone" → the player is outside every zone radius in config_zones.lua
• Poaching does not start → wrong hour, zone is not flagged illegal = true, or the player is not using the Black Market Rod + Illegal Bait
• Diving outfit looks wrong → Config.Diving.Components does not match your clothing pack — set Config.Debug = true and use /scuba
• Crates are not visible → crates only exist during an active mission, start one from /divemenu
• Rod stuck in hand → /rodfix, or /divefix for stuck diving state

---

#📁 FILES OVERVIEW

---

#🏁 SUMMARY

FX-FISHING provides:

• Full fishing loop with skill check, 12 species, 6 zones, 4 rods and 3 baits
• Night-only poaching with a heat system, police dispatch and confiscation penalties
• Boat rental from 5 traders with a complete anchor system
• Independent scuba diving career with 9 dive sites, 9 treasures and 6 loot pools
• Mission-based crates — no loot stealing, per-character site cooldowns
• Oxygen system with tanks, auto-swap, warnings and a safe auto-surface fallback
• Diving crews up to 8 players with roles, live HUD and shared missions
• Career panel with seasons, daily rewards, quests, achievements, pass and dynamic market
• 31 story missions, 18 achievements, 9 pass tiers, 6 panel themes
• Fully server-authoritative economy with prices never exposed to the client
• Self-installing database that scales through summary tables
• Framework support: QBCore / Qbox / ESX — auto-detected
• English & Turkish included, all text in locale files

---

© Fixitfy Development