Configuration#

Every setting of Koja Fishing lives in shared/, split into one file per system. This page walks through each file and says what every option does. The skill tree is configured separately in data/skills.json.

config.main.lua#

Config.Locale = 'en'
Config.Debug = false
Config.ChanceToRodDamage = 15
Config.CreateAutoTable = true
Config.StartingValues = { level = 1, exp = 0 }

Levels#

Config.MaxLevel = 30
Config.ExpBase = 100
Config.ExpGrowth = 20

The XP needed to go from level n to n + 1 is ExpBase + (n - 1) * ExpGrowth. Each level gained grants skill points (sp_per_level in data/skills.json). XP stops at the last level.

Security#

Config.Security = {
    ValidatePedDistance = true,
    PedInteractDistance = 10.0,
    OnSuspicious = function(source, reason)
    end,
}

See Security for what is validated.

Shop and dynamic prices#

Config.Shop = { MaxQuantityPerItem = 100 }

Config.PriceChange = {
    enabled = true,
    changeInterval = 7200,
    maxItemsToChange = 8,
}

A discounted item costs between price - maxPriceChange and price (see items). Shop peds can change prices with their own multipliers (see peds).

Redeem codes#

Config.RedeemCode = {
    enabled = true,
    createCommand = 'createfishingcode',
}

Codes give a temporary luck bonus and are entered in the shop. Each player can use a code once. Create codes from the server console — see Commands.

Electric fishing#

Config.BatteryElectric tunes the illegal battery method.

Every grabbed fish counts as poaching evidence — see config.poaching.lua.

config.minigame.lua#

Keys, the strike window and the reeling fight.

Config.Minigame = {
    CastKey = 'E',
    CancelKey = 'X',
    DuiHeight = 1.35,
    DuiSize = 0.85,
    HookWindowMs = 1800,
    DirectionChange = { min = 1600, max = 3400 },
    DirectionWarningMs = 650,
    TensionGraceSeconds = 0.4,
    StartDistance = { min = 11.0, max = 16.0 },
    MaxDistance = 24.0,
}

Every value in Rarity.<rarity> is a rate per second:

config.tutorial.lua#

The fishing guide for new anglers.

Config.Tutorial = {
    Enabled = true,
    GuidePed = 'kuba',
    InviteNewPlayers = true,
    InviteDistance = 60.0,
    StarterKit = {
        { name = 'fishing_rod', count = 1 },
        { name = 'basic_reel', count = 1 },
        { name = 'basic_line', count = 2 },
        { name = 'worm_bait', count = 15 },
    },
    SkillPed = 'angelo',
    RewardXp = 50,
    BookItem = 'fishpedia',
    FishingPoint = vector3(-1847.0, -1250.8, 13.0),
}

Each Cutscene entry is one shot:

config.admin.lua#

The in-game admin panel edits config values live and stores them in the koja-fishing-config table.

Config.Admin = {
    Enabled = true,
    Command = 'fishingadmin',
    Ace = 'koja-fishing.admin',
    Groups = { 'admin', 'superadmin' },
}

The panel groups its sections into Gameplay, Content, World and System:

Items and fish use a list and detail editor: you can add an entry from a template or as a copy, delete it and restore a deleted file entry. Entries added in the panel live in the database; their key must be 2–40 characters of a-z, 0-9 and _. Spots, peds, quest boards, exam questions, boats, diving caches and cutscene shots use the same editor without adding or deleting.

Config.Admin, Config.Debug, Config.CreateAutoTable, Config.Poaching, Config.Party, the generated level table and functions such as OnSuspicious stay file-only.

config.fish.lua#

Each fish is an entry in Config.Fish, keyed by its item name:

['swamp_catfish'] = {
    name = 'Swamp Catfish',
    description = 'A huge catfish from the Zancudo marshes. Protected species.',
    rarity = 'uncommon',
    protected = true,
    weight = { min = 6.0, max = 18.0 },
    sellPrice = 260,
    xp = 30,
    length = { min = 70, max = 130 },
    image = 'swamp_catfish.webp',
    sellable = true,
    requirements = {
        minRodTier = 2,
        minLineTier = 2,
        minBaitTier = 1,
    },
},

Config.RarityMinLevel sets the level an angler needs for each rarity (common = 1, uncommon = 5, rare = 15, legendary = 24). Config.EquipmentTiers maps every rod, line, bait and reel to a tier from 1 to 5.

Names and descriptions are translated from the locales (game.content.fish.<key>.name / .description); the config text is the fallback.

config.items.lua#

Equipment, accessories and treasures, keyed by item name:

['advanced_rod'] = {
    name = 'Advanced Rod',
    requiredLevel = 3,
    price = 500,
    maxPriceChange = 100,
    sellPrice = 375,
    stats = { castDistance = 50.0, catchBonus = 10, durability = 150 },
    category = 'equipment',
    quality = 'uncommon',
},

Treasures (pearl, ancient_coin, sunken_compass, ship_bell, pirate_doubloon, rusty_key, fossil_shell, amber_chunk) have price = 0: they come from diving and digging and can only be sold.

Accessories work from the inventory: the best luckBonus necklace a player carries is applied automatically.

config.spots.lua#

A player can only fish inside a spot.

{
    id = 'cassidy_creek',
    name = 'Cassidy Creek',
    description = 'A clear forest river full of trout. Licence and an Advanced Rod required.',
    hidden = { enable = false },
    requiredLevel = 3,
    requireLicense = true,
    minRodTier = 2,
    locationType = 'radius',
    radius = { coords = vector3(-1651.7494, 4451.0513, 4.7721), range = 85.0 },
    fish = {
        { name = 'trout', chance = 40 },
        { name = 'rainbow_trout', chance = 25 },
    },
    waitTimeModifier = 0.95,
    blip = { enabled = true, sprite = 68, color = 25, label = 'Cassidy Creek', minLevel = 3 },
},

All requirements are checked by the server when the cast starts.

Config.BoostedZonesSettings controls the bubble event: one zone on the map is active for activeDurationSeconds, then the system waits cooldownSeconds and picks another. Inside it, rarityMultipliers change the odds per rarity.

config.peds.lua#

['hank'] = {
    name = 'Hank',
    model = 'a_m_m_hillbilly_01',
    pedtype = 'shop',
    icon = 'fa-solid fa-store',
    licenserequired = false,
    scenario = 'WORLD_HUMAN_LEANING',
    shop = {
        buyMultiplier = 0.85,
        sellMultiplier = 1.15,
    },
    zones = {
        { coords = vector4(1302.5378, 4226.6919, 33.9087, 75.7342) },
    },
    blip = { enabled = true, sprite = 52, color = 3 },
},

Most default peds have a second zone on Chumash Pier. Hank runs a village shop at the Alamo Sea; the hermits Tom and Gustaw have no blip.

The server measures distance to these zones, so a ped you remove here can no longer be used from anywhere.

config.hotbar.lua#

The hotbar is where the angler equips gear before casting.

config.quests.lua#

Quests are grouped in boards. With AutoUnlockNextBoard = true each board unlocks when the previous one is complete, and quests in a board are done in order.

{
    id = 4,
    name = 'Angler’s Path',
    description = 'Prove yourself on the river and earn a master’s rod.',
    image = './images/quests/quests_legal.webp',
    type = 'main',
    independent = true,
    quests = {
        { id = 31, title = 'Catch 5 trout at Cassidy Creek', objective = {
            label = 'Caught', target = 5,
            type = 'catch', item = 'trout', spot = 'cassidy_creek',
        }, reward = { xp = 150, money = 500 } },
        { id = 33, title = 'Sell 15 fish', objective = {
            label = 'Sold', target = 15, type = 'sell',
        }, reward = { xp = 250, items = { { name = 'master_rod', count = 1 } } } },
    },
},

Other resources can add progress too — see Exports and events.

config.tournaments.lua#

A fixed tournament scores points per species with fishPoints, between startsAt and endsAt (YYYY-MM-DD HH:MM:SS, server time).

Auto creates a new tournament every IntervalHours, lasting DurationHours, from Template. ScoringMode is weight_max (heaviest single fish, in grams) or weight_sum (total weight).

Prizes#

Prizes are paid automatically when a tournament ends:

prize = {
    name = 'Biggest Fish Trophy',
    image = 'items/big_catch.png',
    rewards = {
        { rank = 1, money = 2500, xp = 300, items = { { name = 'legendary_bait', count = 5 } } },
        { rankFrom = 2, rankTo = 3, money = 1000 },
    },
},

Only participants with more than 0 points are ranked. Online winners get the reward immediately; offline winners get it a few seconds after they next join. Each tournament is settled once — the result is stored in the database and survives restarts.

config.test.lua#

The fishing licence exam is taken at the test ped.

The intro, questions and answers are translated from game.test.content.*; the config texts are the fallback. A text edited in the admin panel is shown as written. Correct answers never leave the server.

config.boatrent.lua#

Config.Rent = {
    SpotClearRadius = 7.0,
    AnchorKey = 'G',
    Boats = {
        {
            model = 'dinghy',
            label = 'Dinghy',
            deposit = 500,
            minLevel = 1,
            parkingSpots = {
                vector4(-1793.6165, -1229.7045, -0.4824, 230.8976),
                vector4(-3438.0, 946.0, 0.0, 326.5),
            },
        },
    },
}

A boat spawns at the free parking spot nearest to the renting player, so one list can cover several marinas (Del Perro and Chumash Pier by default). SpotClearRadius is the free space a parking spot needs. The deposit is taken in cash and refunded when the boat is brought back within 20 m of the spot it was rented from. minLevel is checked on the server. AnchorKey is the default key of kf_anchor, which drops and raises the anchor of the boat you are on; the anchor is also in the ox_target menu.

config.diving.lua#

Caches#

Scuba gear#

Gear is bought and refilled at the diving ped (Marek), paid in cash.

Diving contracts#

Contracts = {
    OffersCount = 3,
    RefreshMinutes = 30,
    MaxActive = 1,
    Areas = {
        { id = 'del_perro_wreck', center = vector3(-2885.0, -270.0, -20.0), radius = 70.0, minTier = 1 },
    },
    Templates = {
        { id = 'salvage', count = { 3, 5 }, tier = 1, reward = { money = { 600, 1100 }, xp = { 60, 110 } } },
    },
},

A tier N contract needs tank and scanner level N or higher. Crate positions are generated per contract inside the area.

config.digging.lua#

Digging#

Tutorial and bike#

Digging gear and contracts#

Tier 1 contracts need no gear, tier 2 needs detector level 2, tier 3 needs detector and shovel level 3. Upgrades are paid in cash at the digging ped.

config.poaching.lua#

Config.Poaching = {
    Enabled = true,
    PoliceJobs = { 'police', 'sheriff' },
    MinPoliceGrade = 0,
    RequireOnDuty = false,
    EvidenceMinutes = 30,
    InspectDistance = 4.0,
    TargetCooldownSeconds = 60,
    Billing = 'money',
    Society = 'society_police',
    ConfiscateProtectedFish = true,
    Alert = { Enabled = true, Chance = 35, CooldownSeconds = 120, BlipSeconds = 90 },
    Offences = {
        { id = 'protected_zone', amount = 2500 },
        { id = 'protected_species', amount = 800, perUnit = true },
        { id = 'no_license', amount = 1000 },
        { id = 'electric_fishing', amount = 5000 },
        { id = 'littering', amount = 300 },
    },
    MaxFine = 25000,
}

Protected spots use protected = true in config.spots.lua, protected species protected = true in config.fish.lua. See Exports and events for the poaching events.

config.party.lua#

Config.Party = {
    Enabled = true,
    MaxMembers = 4,
    InviteDistance = 30.0,
    InviteTimeoutSeconds = 60,
    MembersCanInvite = false,
    OpenCommand = 'kf_party',
    OpenKey = 'F7',
    AcceptKey = 'Y',
    DeclineKey = 'N',
    ShareRadius = 150.0,
    ShareModeDefault = false,
    XpBonusPercent = 10,
}

Goal types: catch (fish landed), sell_value (total $ of fish sold), dive (caches and contract crates), dig_cache (contract caches dug up).

Translations#

The locale is loaded on the server too (shared/i18n.lua), so content in the configs is translated at start:

The config text is used when a key is missing. The admin panel labels and section descriptions come from the locales as well.

data/skills.json#

The skill tree has three branches — wedkarz (angler), klusownik (poacher), handlarz (trader) — listed in meta.trees with the level that unlocks them. Each node has requirements.skills, requirements.level, effect_per_level and an upgrades list whose price is the skill point cost of each level.

Keep the ids — the code reads them. The UI shows the catalog the server sends from data/skills.json; web/src/data/skills.json is only a fallback bundled into the UI.