Changelog

1. Prepare

This guide updates an installed 1.1.0 resource to 1.2.0. Older installations must first complete the 1.1.0 installation/update steps in the previous entry. Back up your FiveM database, sky_treasurehunt resource, custom configuration/translations and resource KVP data. Preserve progression, collections, event claims and saved settings. Let searches finish and stop the server before replacing files.

Keep Sky Base 1.47.0 or newer, your existing framework, oxmysql/database, configured inventory/providers and OneSync setup. Treasure Hunt has no Jobs Base dependency. Keep the installed sky_dockside_salvage 2.4.12 map for the default merchant; this update does not change or require replacement of that separate map.

2. Replace files

Use the same 1.2.0 customer download for every replacement. Delete the complete old sky_treasurehunt/source/ folder and insert its new replacement, including the interface. Replace sky_treasurehunt/fxmanifest.lua. Refresh the complete sky_treasurehunt/config/locales/ and flat sky_treasurehunt/config/inventory/ folders, merging your custom wording and retaining your inventory provider's existing item definitions. These folders remain required package components; there are no new item IDs, images or translation keys. No stream asset changes or file removals/renames outside source/ are required.

3. Keep settings and data

There are no new, changed or removed public config options, SQL schemas or provider requirements in this update. Keep your current public Lua configuration, inventory registrations, prices, progression and event settings. No manual SQL/import, item re-registration or asset installation is needed when updating a complete 1.1.0 installation. Do not reset tables, KVPs or saved configuration. /treasureconfig remains the settings panel; /jobconfig is not used. With Config.UseIngameConfigurator = true, retain saved customized groups; no Lua Files Import is needed for this release. File-owned permissions remain unchanged.

4. Integrate optional minijobs

The new exports do not automatically integrate any minijob. If another activity must block Treasure Hunt bin searching, follow the Exports reference. Add dependency "sky_treasurehunt" to that integrating resource and use server SetTrashSearchBlocked(playerId, true, reason) after authorizing the job start. Use -1 instead of a player ID for a server-wide block. Release with false and the same reason on every job exit, cancellation or character switch. Each caller owns its reasons; releasing one does not remove other callers' or global restrictions.

Server locks enforce search/reward restrictions and synchronize the local interaction. Client locks affect only the local interaction. A cancelled search does not resume when unblocked, reroll a bin, reset its refill timer or undo completed rewards. Player locks clear on disconnect, caller-owned locks clear when that resource stops, and all locks clear when Treasure Hunt restarts. Reapply locks for ongoing jobs after a restart. Keep metal detecting, magnet fishing and diving on their existing workflows.

5. Restart and verify

Perform a full server restart and reconnect clients. Start the framework, database connector and selected providers first, then sky_base, the existing sky_dockside_salvage, sky_treasurehunt and any integrating minijob resources. Check startup logs and normal merchant, album and bin-search behavior. For each enabled integration, test blocking during an active search and an inventory-full retry, confirm E/target/search cleanup, then release the same reason and start a fresh search. Check overlapping reasons, player/global blocks, disconnect/character-switch cleanup and restart reapplication. Verify existing progress and settings remain present.

Optional diagnostics are disabled by default. To enable them, put setr sky_profiler 1 in server.cfg before the Sky ensure lines and restart the server. Start a recording manually using the FiveM profiler; recording and upload never start automatically. Disable diagnostics with setr sky_profiler 0 and another server restart. This is not a configurator setting. Gameplay, HUD/target cleanup and the minijob's own interaction need a connected FiveM client and your actual integration/provider setup.

1. Prepare

This is the first documented Sky Treasure Hunt release, version 1.1.0. For an existing 1.0.0 installation, back up the database, resource files, configuration, inventory definitions/images and the resource's KVP data. Keep the exact resource name sky_treasurehunt. Let current searches finish and stop the server for replacement. New installations need the same inventory, database and configuration setup below.

Use Base 1.47.0 from this shared update. Treasure Hunt uses Sky Base without a Jobs Base dependency; the other jobs in the shared batch still need Jobs Base 1.50.0. Keep your existing configured inventory/framework providers, use the existing oxmysql transaction setup and OneSync, and obtain both supplied packages: the core sky_treasurehunt ZIP and the separate sky_dockside_salvage-2.4.12.zip map. The map is not inside the core ZIP.

2. Replace files

Delete the complete old sky_treasurehunt/source/ folder and insert the new one, including its generated interface. Replace sky_treasurehunt/fxmanifest.lua and sky_treasurehunt/import.sql from the same 1.1.0 package. Refresh the complete sky_treasurehunt/stream/ tree, keeping only the supplied current native files; do not overlay obsolete Vantis-named equipment or development exports. The recursive stream tree includes detector/shovel tools, find props, magnet equipment/finds, diving tanks/finds and event models.

Refresh the whole sky_treasurehunt/config/locales/ tree, including configurator translations, and merge your custom wording. Refresh sky_treasurehunt/config/inventory/ as a flat installation folder containing the import examples and all 75 PNGs; there is no images/ subfolder. Merge the other public config files as described below instead of discarding custom settings.

Install the separate map as resources/sky_dockside_salvage with its manifest, README and all 49 stream files. Keep its supplied 2.4.12 version. The default merchant is at -758.66674, -1522.25369, 5.05 in the Higgins depot at Vespucci Marina. The map replaces the depot facade, two ground drawables and two collision tiles; a custom map replacing the same originals needs a compatible asset merge. Keep editable Blender sources, developer tools, previews and reports outside server resource folders.

3. Merge config

Review all supplied public settings: config/config.lua (bootstrap, merchant, detectors/shovels, search, terrain, presentation and General progression), config/skills.lua (skill trees), config/server.lua (merchant account, categories and admin hooks), config/prices.lua (central sale prices), config/loot.lua (detector pools/discoveries), config/hotzones.lua (areas), config/magnet.lua / magnet_server.lua, config/diving.lua / diving_server.lua, config/trash.lua / trash_server.lua, config/events.lua, and config/integration/admin.lua / water.lua. Preserve intended custom locations, item IDs, prices, pools, water rectangles and integrations. The complete new tables are supplied in those editable files; merge their full blocks rather than creating guessed entries.

New bootstrap/configurator and portable-album defaults in config/config.lua are:

Config.Enabled = true
Config.UseIngameConfigurator = true
Config.CommandPermissions = { treasureconfig = { "god", "superadmin", "admin" } }
Config.Locale = "en"
Config.Album = { item = "treasure_album", price = 50 }

Config.Locale accepts the supplied en or de; use Sky.Config.locale explicitly to follow Base's selected language. Keep your existing command-permission choices. The panel is /treasureconfig, not /jobconfig. File merges can be done while the server is stopped; panel changes and rights checks are performed after the SQL setup and first startup of the updated resource.

With Config.UseIngameConfigurator = true, the first startup imports Lua settings, while later startups retain saved customized groups and let untouched groups adopt supplied defaults. A normal update does not require an import or reset. Open /treasureconfig, review the effective groups, save deliberate changes, then restart Treasure Hunt and reopen to confirm the applied revision. To intentionally replace managed settings with merged Lua values, first back up stored settings, restart the resource, choose Lua files import in the panel and restart again. Config.UseIngameConfigurator = false uses Lua on the next startup and retains saved SQL settings/history.

For existing development installations, Config.Progression.xpPerFind in config/config.lua changes from 25 to 35. Retain deliberate XP overrides, and merge the supplied complete Config.Progression.thresholds list when adopting the current curve. In config/loot.lua, ServerConfig.Discovery[4].hardLimit and [5].hardLimit change from the former 165/300 to 90 eligible successful digs for an unseen item of that grade. These are first-discovery rules, not a recurring payment guarantee. Existing startup migrations preserve levels and relative progress while translating the curve; raw XP can change to match new thresholds. Saved finds and history remain. Existing General skills are retained; when General progression is first introduced, formerly shared trading, equipment-discount and learning benefits migrate once into that separate tree. Do not reset progress to apply these changes.

For older development data only, each magnet, diving or rubbish-search skill set whose stored skills.__version is missing or differs from 2 is reset once when that method is first loaded, and the version is stored as 2. This skill reset retains its method XP, finds, history and discovery counters. Available points are recalculated from the current method level minus one, minus the cost of learned nodes; after the reset the learned-node cost is zero. Players must allocate those available points again in the affected activity tree before using its skill-locked equipment. This version migration does not reset General or detector skills, and method skill sets already at version 2 remain unchanged. The separate XP-curve migration described above can still remap raw XP while preserving level and relative progress.

In config/magnet.lua, Config.Magnet.castsPerSpot changes from 1 to 5; remove the obsolete Config.Magnet.maxHeight = 5.0. Keep the normal aim/water/reach checks and deliberate depletion settings. In config/diving.lua, merge the supplied tank attachment and freemode presets together: Config.Diving.tank uses bone 24818, offset (-0.30, -0.23, 0.0) and rotation (0.0, 90.0, 0.0); the supplied male/female component 5 drawable is 0, replacing the earlier development drawable 43. Each equipped tier supplies its attached tank model. Preserve your deliberately supported character-model clothing choices.

Existing lootTier/tier skill fields in config/skills.lua and method skill lists now represent rarity weight bonuses: 1 is baseline, 2/3/4/5 add 25/50/75/100 percent. Normal and event minTier values are rarity metadata. All location-valid grades are available with Basic gear; the separate skill, level and ownership requirements for upgraded tools/scuba sets remain. There is no rarity access reset or item conversion.

ServerConfig.Shop.Currency in config/server.lua defaults to "money" and supports "money", "cash" and "bank". Merchant amounts are formatted by the corresponding Sky Base currency settings; changing resource language does not change the currency. Preserve your intended account and prices. Event prize label values are administrator-authored text and must be adjusted separately when you want another displayed currency.

The new optional config/events.lua block is supplied complete below. It is disabled. Merge it as a new ServerConfig.Events.runs entry list, retaining any deliberately saved events:

ServerConfig.Events = {
    runs = {
        {
            enabled = false,
            id = "halloween_2026",
            name = "Halloween",
            description = "Find Halloween bones and compete for prizes.",
            preset = "halloween",
            startsAt = "2026-10-24T00:00:00+02:00",
            endsAt = "2026-11-01T00:00:00+01:00",
            item = "treasure_halloween_bone",
            itemLabel = "Halloween Bone",
            banner = "album/treasure_halloween_bone.png",
            image = "album/treasure_halloween_bone.png",
            accent = "#dc9854",
            methods = {
                detector = { enabled = true, weight = 10, chance = 0.15, minTier = 1, min = 1, max = 1 },
                magnet = { enabled = true, weight = 10, chance = 0.15, minTier = 1, min = 1, max = 1 },
                diving = { enabled = true, weight = 10, chance = 0.15, minTier = 1, min = 1, max = 1 },
                trash = { enabled = true, weight = 10, chance = 0.15, minTier = 1, min = 1, max = 1 },
            },
            prizes = {
                { place = 1, rewards = { { sort = "cash", name = "money", amount = 5000, label = "$5,000" } } },
                { place = 2, rewards = { { sort = "cash", name = "money", amount = 2500, label = "$2,500" } } },
                { place = 3, rewards = { { sort = "cash", name = "money", amount = 1000, label = "$1,000" } } },
            },
        },
    },
}

Before enabling an event, install its item, give each edition a new unique ID, and use explicit numeric UTC offsets in YYYY-MM-DDTHH:MM:SS+hh:mm format (+00:00 for UTC). Enabled schedules must not overlap. The supplied October/November offsets account for the daylight-saving change; events do not recur annually. Started runs retain their recorded rules and prizes; editing/removing a Lua entry does not erase the archive or pending prizes.

Each supplied method uses chance = 0.15 per eligible item selection. It is a replacement find, not an extra drop. Guaranteed normal first finds take precedence; trash first needs its default 20 percent success roll, producing a base 3 percent event chance per search. Saved older rules without chance retain relative weight behavior. Keep the event disabled if you do not want it.

Event archive administration is separate from panel permissions: config/integration/admin.lua uses the existing sky_treasurehunt.admin ACE and your configured admin/duty integration. Its default duty requirement is false; integrate ServerConfig.IsAdminOnDuty in config/server.lua before deliberately requiring duty. Additional ServerConfig.WaterQuads belong in the existing water adapter only when your custom map needs them.

Optional diagnostics are disabled by default. Put setr sky_profiler 1 in server.cfg before the Sky ensure lines and perform a full server restart. Run profiler record 1000, wait for profiler status to show completion, then run profiler saveJSON sky-treasurehunt-1.1.0.json. Recording/uploading does not start automatically and this is not a configurator setting. Disable with setr sky_profiler 0 and another full restart.

4. SQL & items

Startup prepares the additive schemas for 10 gameplay tables, two configurator tables and seven event tables. sky_treasurehunt/import.sql contains all 19 matching CREATE TABLE IF NOT EXISTS statements, without prescribing charset/collation. Do not delete, truncate or reset existing player/config/event data. This resource has no customer Config.AutoExecuteQuery toggle to copy from a job script.

For manual schema preparation, keep the resource stopped, open your database administration tool, select the active FiveM database and execute the complete supplied sky_treasurehunt/import.sql. Its statements create missing tables and retain existing rows. If an existing sky_treasurehunt_trash_bins table lacks the expiry index, check and add it once:

SHOW INDEX FROM `sky_treasurehunt_trash_bins` WHERE Key_name = 'expires';
-- Only when that query returned no row:
ALTER TABLE `sky_treasurehunt_trash_bins` ADD INDEX `expires` (`expires`);

Automatic startup also checks that index. Preserve the existing KVP namespace so legacy depleted locations can be imported once into SQL; keep the same resource name. Progress/curve/skill migration is handled by startup, not by clearing database rows or replaying old rewards.

For OX, back up ox_inventory/data/items.lua and choose exactly one complete import: sky_treasurehunt/config/inventory/items_ox_en.lua for English or items_ox.lua for German. Merge the entries inside its return { ... } into your existing items table, preserving unrelated/custom items and avoiding duplicate IDs. Each complete import contains 60 regular finds, 12 reusable equipment items and treasure_album (73 IDs). The equipment IDs are metaldetector, metaldetector_standard, metaldetector_premium, shovel, shovel_standard, shovel_premium, fishing_magnet, fishing_magnet_standard, fishing_magnet_premium, scuba_gear, scuba_gear_standard and scuba_gear_premium. Keep tools/album at consume = 0, stack = false, close = true; Sky owns their use registration. Finds stay stackable and have no Use action. Do not add a second client export/event callback.

Copy the flat PNG files from sky_treasurehunt/config/inventory/ to ox_inventory/web/images/, with the supplied item IDs and client.image names matching. album_ox.lua and album_ox_de.lua are album-only alternatives for an otherwise complete inventory; the album is already in the complete imports and must be registered once. Its example weight is 250 grams and price defaults to 50. Preserve deliberate custom inventory weights; album loot-selection weights are a different setting.

Before enabling an event, merge its chosen item definitions. events_ox.lua provides treasure_halloween_bone and treasure_event_crate; install their matching flat PNGs. Importing them does not enable the Halloween example. For other inventory providers, register the same actual selected IDs in the provider's supported format, keep equipment reusable and configure that provider in Base. There is no supplied album_esx.sql or automatic item-registration SQL. Restart the full server after inventory edits so inventory definitions and Sky's item cache reload together.

The map and complete native stream assets are file installations, not inventory rows. Preserve old event image paths still referenced by recorded runs. Custom event artwork requires a supported local UI image path and a frontend rebuild; changing an image name alone does not install the file.

5. Restart & test

Perform a full server restart and reconnect clients. Start your framework, database/oxmysql and configured inventory/providers first, then Base 1.47.0, the supplied Dockside map and the core:

ensure sky_base
ensure sky_dockside_salvage
ensure sky_treasurehunt

Check startup for missing items/schema errors, then perform the intended /treasureconfig review/import only if needed and restart the resource before gameplay checks. Confirm the merchant/map, localized item names, account formatting, reusable tools and portable album. Try a detector dig, five valid magnet casts, a scuba find/refill with restored clothing, and a rubbish search. Confirm progress/collections after reconnecting, and that saved customized settings survive a restart.

For a deliberately enabled test event, check an issued event find, ranking, discovered event album and ended-run prizes. Only actually delivered finds score; purchases, transfers and administrator grants do not add points. Ties use the recorded completion time/order. A late delivered find can enter the event album without changing an already closed ranking. Existing visible diving finds keep their original selected item.

Rejected prize grants remain pending for a later visit. A provider exception or uncertain delivery goes to review and is not automatically repeated. In the authorized Event Archive, check the inventory/provider logs before confirming delivery or reopening a claim, and record a reason. A prize popup acknowledgement is separate from the payment claim. Keep the archive and unresolved claims.

These checks need your actual map, inventory/provider and connected FiveM client. Source, regression, build and package checks do not establish rendered models, client streaming stability, multiplayer or settlement on another server.