> For the complete documentation index, see [llms.txt](https://atiysus-organization.gitbook.io/aty-scripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atiysus-organization.gitbook.io/aty-scripts/fishing/fishing.md).

# Fishing

## `aty_fishing`

`aty_fishing` is a comprehensive, feature-rich fishing and diving script for FiveM. It features a complete leveling system, rod upgrades, multiple bait types with distinct stat weights, diving activities, missions, multiplayer co-op fish tasks, active tournaments, leaderboards, and an in-game zone creator.

***

### Table of Contents

1. Key Features
2. Dependencies
3. Configuration Reference (`shared/config.lua`)
4. Command & Keybind Reference
5. Core Systems
   * Fishing Mechanics & Baits
   * Rod Upgrade Progression
   * Level & Reward Progression
   * Diving & Underwater Scavenging
   * Missions & Co-op Tasks
   * Tournaments & Leaderboard
   * Zone Creator (Admins)
6. Item Database Reference
7. Installation & Setup

***

### Key Features

* **Advanced Leveling System:** Track player experience (EXP) up to Level 50. Leveling up grants cash rewards and rare items.
* **Rod Upgrades:** Players can upgrade their fishing rods (up to level 5) at designated NPCs by supplying money and materials (`rod_body`, `fishing_hook`, `fishing_line`).
* **Dynamic Bait System:** Different baits (`worm`, `shrimp`, `lure`) change your luck, wait times, and modify the catch chance weights for common, rare, epic, and legendary fish.
* **Deep Sea Diving:** Put on a diving suit and oxygen tank to explore the ocean floor for salvage items like antique coins, gold bars, and pearls.
* **Co-op Tasks & Missions:** Take on missions with friends (e.g. Salmon Run, Deep Sea Expedition) or complete passive achievements (e.g., Tuna Titan, Pearl Seeker) for high yields of money and EXP.
* **Tournaments:** Periodic fishing competitions that trigger global announcements and feed into a persistent leaderboard.
* **In-game Zone Creator:** Admins can define custom fishing and diving zones dynamically on the map.

***

### Dependencies

* **`aty_lib`**: Core utilities, database abstractions, target compatibility layers (ox\_target, qb-target), and 3D text elements.
* **`PolyZone`**: Required for defining and tracking coordinates inside fishing/diving zones.

***

### Configuration Reference (`shared/config.lua`)

Below is a breakdown of the core configuration parameters:

| Variable                       | Type      | Description                                                     |
| ------------------------------ | --------- | --------------------------------------------------------------- |
| `UseTarget`                    | `boolean` | Toggles 3D Text interaction vs Target options (via `aty_lib`).  |
| `TournamentSystem`             | `boolean` | Enables or disables the active tournament system.               |
| `GlobalTournamentNotification` | `boolean` | Notifies the entire server when a tournament begins.            |
| `RodItem`                      | `string`  | The item code utilized as the base fishing rod.                 |
| `Diving.OxygenTime`            | `number`  | The duration (in seconds) the oxygen tank lasts (default: 300). |
| `Diving.SuitModel`             | `string`  | Ped clothing/model hash applied when wearing the diving suit.   |

***

### Command & Keybind Reference

Players can access the menus via the following default commands or their associated hotkeys:

| Command        | Default Key | Permission  | Description                                                       |
| -------------- | ----------- | ----------- | ----------------------------------------------------------------- |
| `/fishing`     | `L`         | Player      | Opens the primary fishing interface (fish status, stats, guides). |
| `/levelup`     | `K`         | Player      | Opens the rod leveling screen showing progress and upgrade costs. |
| `/multiplayer` | `J`         | Player      | Opens the co-op missions menu.                                    |
| `/tournament`  | `H`         | Player      | Displays active tournament details and timers.                    |
| `/leaderboard` | `J`         | Player      | Shows the top-performing anglers on the server.                   |
| `/zonecreator` | *None*      | Admin / God | Opens the dynamic in-game fishing zone setup manager.             |

***

### Core Systems

#### 1. Fishing Mechanics & Baits

To fish, players must equip a **Fishing Rod** and select a bait:

* **Worm (Lvl 1):** Standard bait. Highly attracts common and uncommon fish. No wait time bonus.
* **Shrimp Bait (Lvl 5):** Moderate bait. Wait time is reduced by 15%. Increased chance for rare and epic fish.
* **Professional Lure (Lvl 15):** Premium bait. Wait time is reduced by 30%. High chance for epic and legendary catches.

#### 2. Rod Upgrade Progression

Upgrade your rod at the **Rod Level Up NPC** using crafting parts and cash:

* **Level 1:** Default rod.
* **Level 2:** $2,500 + 1x `rod_body`.
* **Level 3:** $5,000 + 2x `rod_body`.
* **Level 4:** $10,000 + 3x `rod_body` + 1x `fishing_hook`.
* **Level 5:** $20,000 + 5x `rod_body` + 2x `fishing_hook` + 2x `fishing_line`.

#### 3. Level & Reward Progression

Players earn EXP by catching fish and completing tasks. Major level checkpoints yield distinct rewards:

* **Level 5:** $5,000 + 5x `shrimp` (bait)
* **Level 10:** $10,000 + 5x `lure` (bait)
* **Level 15:** $15,000 + 1x `rod_body` (crafting material)
* **Level 20:** $25,000 + 1x `fishing_line` (crafting material)
* **Level 30:** $75,000 + 1x `gold_bar`
* **Level 35:** $100,000 + 1x `treasure_chest`
* **Level 40:** $150,000 + 1x `fish_shark`
* **Level 50 (Max):** $500,000 cash prize.

#### 4. Diving & Underwater Scavenging

Using a **Diving Suit** and **Oxygen Tank**, players can dive in search of sunken wreck boxes. Searching these boxes yields:

* **Antique Coins** (40% chance) - $250 value.
* **Rusty Anchors** (30% chance) - $150 value.
* **Ocean Pearls** (20% chance) - $750 value.
* **Gold Bars** (10% chance) - $5,000 value.

#### 5. Missions & Co-op Tasks

Players can start structured missions at the **Multiplayer NPC**. These include:

* **Salmon Run (Medium):** Co-op catch target of 25 Salmons. (Reward: $6,000)
* **Deep Sea Expedition (Hard):** Co-op catch target of 10 Tunas. (Reward: $8,500)
* **Apex Predator Hunt (Extreme):** Co-op catch target of 3 Great White Sharks. (Reward: $15,000)
* **Operation Gold Bar (Diving - Hard):** Salvage 4 sunken gold bars. (Reward: $35,000)

#### 6. Tournaments & Leaderboard

Tournaments run periodically. Players score points based on the size, rarity, and quantity of fish caught in the designated tournament zones. Results populate the `/leaderboard` menu.

#### 7. Zone Creator (Admins)

Admins can use `/zonecreator` to define the coordinate boundaries of active fishing and diving areas. Zone metadata is written directly to `shared/zones.json`.

***

### Item Database Reference

| Item ID          | Label             | Base Value (Sell) | Base Value (Buy) | Description                            |
| ---------------- | ----------------- | ----------------- | ---------------- | -------------------------------------- |
| `fishing_rod`    | Rod               | $50               | $500             | Main tool for fishing.                 |
| `fishing_line`   | Line              | $5                | $25              | Rod upgrade material.                  |
| `fishing_hook`   | Hook              | $2                | $10              | Rod upgrade material.                  |
| `rod_body`       | Rod Body          | $30               | $200             | Rod upgrade material.                  |
| `worm`           | Worm              | $3                | $5               | Standard freshwater bait.              |
| `shrimp`         | Shrimp Bait       | $10               | $15              | Mid-tier saltwater bait.               |
| `lure`           | Professional Lure | $30               | $50              | High-end artificial bait.              |
| `fish_bass`      | Bass              | $15               | *Unbuyable*      | Common fish catch.                     |
| `fish_salmon`    | Salmon            | $25               | *Unbuyable*      | Uncommon fish catch.                   |
| `fish_tuna`      | Tuna              | $100              | *Unbuyable*      | Rare deep-sea fish catch.              |
| `fish_marlin`    | Blue Marlin       | $500              | *Unbuyable*      | Epic fish catch.                       |
| `fish_shark`     | Great White Shark | $2,000            | *Unbuyable*      | Legendary predator fish.               |
| `treasure_chest` | Treasure Chest    | $1,000            | *Unbuyable*      | Rare drop containing high-value items. |
| `diving_suit`    | Diving Suit       | $100              | $1,000           | Suit used to search underwater.        |
| `oxygen_tank`    | Oxygen Tank       | $50               | $500             | Provides underwater oxygen.            |
| `gold_bar`       | Gold Bar          | $5,000            | *Unbuyable*      | High-value diving loot.                |
| `pearl`          | Ocean Pearl       | $750              | *Unbuyable*      | High-value diving loot.                |

***

### Installation & Setup

1. Import `data.sql` to your database to register user progress tables.
2. Register the items in `shared/items.lua` within your framework's inventory item config (e.g. `ox_inventory/data/items.lua` or `qb-core/shared/items.lua`).
3. Ensure the script order in your server startup:

   ```cfg
   ensure PolyZone
   ensure aty_lib
   ensure aty_fishing
   ```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://atiysus-organization.gitbook.io/aty-scripts/fishing/fishing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.