lunar_fishing — Manual

Sistema de pesca com zonas de dificuldade progressiva, varas e iscas de níveis diferentes, aluguel de barcos e progressão de nível vinda do cw-rep.

Sumário

1. Dependências
2. Instalação
3. Configuração
4. Controles
5. Como pescar
6. Integrações
7. Entrypoints para outros recursos
8. Localização
9. Estrutura de arquivos

Dependências

Instalação

1. Copie a pasta lunar_fishing para resources/.

2. Adicione ao server.cfg:

   ensure ox_lib
   ensure oxmysql
   ensure lunar_fishing

3. Copie as imagens de install/images/ para a pasta de imagens do seu inventário.

4. Cadastre os itens no seu inventário. Os guias prontos estão em install/OX.md, install/QBCore.md e install/ESX.md. Itens necessários:

   Grupo	Itens
   Varas	basic_rod, graphite_rod, titanium_rod
   Iscas	worms, artificial_bait
   Peixes	anchovy, trout, haddock, salmon, grouper, piranha, red_snapper, mahi_mahi, tuna, shark

   As varas precisam ser itens usáveis — é o uso do item que inicia a pescaria.

5. O install/import.sql não é mais necessário. A tabela lunar_fishing existe no arquivo, mas todo o código que a lia e gravava (em server/level.lua) está comentado: o nível agora vem do cw-rep.

Configuração

Arquivos: config/config.lua (compartilhado) e config/sv_config.lua (servidor).

Geral

Peixes (Config.fish)

Varas (Config.fishingRods)

Iscas (Config.baits)

O jogo usa automaticamente a isca mais cara que o jogador tiver no inventário.

Zonas de pesca (Config.fishingZones)

Zonas que vêm no config: Coral Reef (nível 1), Swamp (nível 2) e Deep Waters (nível 3).

Fora das zonas (Config.outside)

NPC pescador (Config.ped)

Aluguel de barcos (Config.renting)

Config.renting.model está declarado duas vezes na tabela (linhas 150 e 167 do config). Vale a segunda — ambas são s_m_m_dockwork_01, então não há diferença prática, mas edite as duas se for trocar o modelo.

Cliente (config/cl_edit.lua)

Arquivo de wrappers, não de opções: notificação, TextUI, progressbar, SetVehicleFuel, SetVehicleOwner e resolução do caminho das imagens do inventário. Edite aqui se o seu servidor usa outro sistema de notificação ou de combustível.

Controles

Ambas são registradas via lib.addKeybind e podem ser remapeadas pelo jogador em Configurações > Teclas > FiveM.

Como pescar

1. Compre uma vara e iscas com o NPC pescador (opção “Comprar varas” / “Comprar iscas” do menu). Varas e iscas de nível superior ficam bloqueadas até o nível de fishing correspondente.
2. Fique de frente para a água, em pé — não funciona nadando nem dentro de veículo. O recurso testa se há água à frente com TestProbeAgainstWater.
3. Use a vara pelo inventário. Não existe comando de pesca; o gatilho é o item usável.
4. A isca mais cara do inventário é consumida e começa a espera (faixa da zona, dividida pelo waitDivisor da isca).
5. Quando o peixe morder, complete o skill check. Segurar E a qualquer momento cancela a pescaria.
6. Sucesso: o peixe entra no inventário e o XP de fishing sobe. Falha: nada é ganho e a vara pode quebrar conforme o breakChance dela.
7. Venda os peixes no NPC pescador, na opção “Vender peixes”.

Integrações

cw-rep

O nível de pesca é inteiramente delegado ao cw-rep, na skill fishing:

• a cada peixe capturado, o servidor chama exports["cw-rep"]:updateSkill(source, 'fishing', Config.progressPerCatch);
• o nível usado para liberar zonas, varas e iscas vem de exports["cw-rep"]:fetchSkills(source).fishing;
• o menu do NPC mostra nível e progresso via getCurrentSkill e getCurrentLevel.

O sistema de XP original (tabela lunar_fishing no MySQL) foi desativado — o código está no arquivo, comentado.

rep-talkNPC

Os dois NPCs são criados com exports['rep-talkNPC']:CreateNPC, com o diálogo de apresentação definido nos campos name, tag, startMSG e message de Config.ped e Config.renting. As opções do target (abrir a loja do pescador, abrir o aluguel de barcos) são registradas via qtarget.

Entrypoints para outros recursos

O recurso não expõe exports nem comandos. O que existe são callbacks e eventos internos, usados na comunicação cliente-servidor.

Callbacks de servidor

-- Vende `amount` do peixe indicado, com 3s de delay antes de creditar
lib.callback.await('lunar_fishing:sellFish', false, fishName, amount)
 
-- Compra vara ou isca. data = { type = 'fishingRods' | 'baits', index = <índice no Config> }
lib.callback.await('lunar_fishing:buy', false, data, amount)
 
-- Aluga o barco de índice `index` em Config.renting.boats
lib.callback.await('lunar_fishing:rentVehicle', false, index)
 
-- Devolve o barco; o jogador precisa estar no banco do motorista
lib.callback.await('lunar_fishing:returnVehicle', false, netId)
 
-- Nível atual de fishing (proxy do cw-rep)
lib.callback.await('lunar_fishing:getLevel', false)
 
-- Mapa de itemName -> label, montado a partir dos itens do framework
lib.callback.await('lunar_fishing:getItemLabels', false)

Eventos

-- Servidor -> cliente: exibe uma notificação do ox_lib
TriggerClientEvent('lunar_fishing:showNotification', source, 'mensagem', 'success')
 
-- Cliente -> servidor: registra o barco recém-spawnado como alugado
TriggerServerEvent('lunar_fishing:registerBoat', netId)
 
-- Servidor -> cliente: atualiza o nível e recria blips e zonas
TriggerClientEvent('lunar_fishing:updateLevel', source, level)

Localização

As strings são traduzidas via ox_lib locale. Os arquivos ficam em locales/:

• en.json — inglês
• de.json — alemão
• pt-br.json — português do Brasil

O locale ativo é definido pela convar ox:locale no server.cfg:

setr ox:locale "pt-br"

As mensagens de entrada e saída das zonas (Config.fishingZones[].message) e os diálogos dos NPCs não passam pelo locale: estão escritos direto em config/config.lua.

Estrutura de arquivos

lunar_fishing/
├── client/
│   ├── main.lua          — zonas, blips, teste de água e o minigame de pesca em si
│   ├── ped.lua           — NPC pescador: menu de comprar varas/iscas e vender peixes
│   ├── rent.lua          — NPC locador: menu de aluguel, spawn e devolução do barco
│   ├── level.lua         — cache do nível de fishing no cliente
│   └── anchor.lua        — keybind da âncora do barco
├── server/
│   ├── main.lua          — registra as varas como itens usáveis; sorteia o peixe e resolve a captura
│   ├── ped.lua           — callbacks de venda de peixe e compra de vara/isca
│   ├── rent.lua          — callbacks de aluguel e devolução de barco
│   └── level.lua         — callback de nível (proxy do cw-rep; código MySQL original comentado)
├── config/
│   ├── config.lua        — peixes, varas, iscas, zonas, NPCs e aluguel
│   ├── sv_config.lua     — webhook do Discord
│   └── cl_edit.lua       — wrappers de notificação, TextUI, progressbar, fuel e imagens
├── framework/
│   ├── qb/{client,server}.lua
│   └── esx/{client,server}.lua
├── utils/
│   ├── cl_main.lua       — criação dos NPCs (rep-talkNPC + qtarget), blips e keybinds
│   └── sv_main.lua       — log no Discord e cache de labels dos itens
├── locales/
│   ├── en.json
│   ├── de.json
│   └── pt-br.json
├── install/
│   ├── OX.md             — itens para o ox_inventory
│   ├── QBCore.md         — itens para o qb-core
│   ├── ESX.md            — itens para o ESX
│   ├── import.sql        — tabela lunar_fishing (não utilizada nesta fork)
│   └── images/           — imagens dos itens (copiar para o inventário)
└── fxmanifest.lua