FishingSystem

Provides a basic fishing system, adding a fishing hook entity and fishing events without handling results.

---

Requirements

• PocketMine-MP API 5.0.0 or higher
• Virion: presentkim-pm/play-sound-utils 2.0.0

---

Features

Provides the base mechanism for fishing, including events for stage progression and results. Supports basic fishing configurations for plugin users. Also provides API for other plugins to hook into the fishing system.

---

Configuration

Configuration file: config.yml (generated in plugin_data/FishingSystem/ on first run)

Path	Type	Description
stages.wait.tick.min	int	Minimum ticks for wait stage
stages.wait.tick.max	int	Maximum ticks for wait stage
stages.teases.tick.min	int	Minimum ticks for teases stage
stages.teases.tick.max	int	Maximum ticks for teases stage
stages.teases.distance.min	float	Minimum fish distance (blocks) in teases stage
stages.teases.distance.max	float	Maximum fish distance (blocks) in teases stage
stages.bites.tick.min	int	Minimum ticks for bites stage
stages.bites.tick.max	int	Maximum ticks for bites stage
stages.bites.enable-auto-retry	bool	If true, return to wait stage on miss; if false, cancel fishing
enable-rod-damage	bool	Whether to damage the fishing rod on reel

Default values are defined in resources/config.yml.

---

Developer API

Classes and Interfaces

FishingSystem

Main API for the fishing system. Use FishingSystem::getInstance() to access.

Method	Description
getSession(Player $player): ?FishingSession	Get session by player
getSessionByXuid(int $xuid): ?FishingSession	Get session by player XUID
hasSession(Player $player): bool	Check if player has active session
hasSessionByXuid(int $xuid): bool	Check if XUID has active session
createSession(Player $player, FishingHook $fishingHook, FishingRod $fishingRod): FishingSession	Create new session (replaces existing)
closeSession(Player $player): bool	Close session and return success
getSessions(): FishingSession[]	All active sessions indexed by XUID
getFishingConfig(): FishingConfig	Current fishing config
setFishingConfig(FishingConfig $config): void	Override fishing config

@see FishingSession, FishingHook, FishingConfig

FishingSession

Represents a fishing session. Contains the player, fishing hook, and fishing rod item.

Method	Description
getPlayer(): Player	The player who is fishing
getFishingHook(): FishingHook	The fishing hook entity
getFishingRod(): FishingRod	Clone of rod at cast time (use for enchantment checks)
isClosed(): bool	Whether the session is closed
setData(string $key, mixed $value): void	Store custom plugin data
getData(string $key, mixed $default = null): mixed	Get stored data
hasData(string $key): bool	Check if key exists
unsetData(string $key): void	Remove stored data

@see FishingHook, FishingSystem

FishingHook

Interface for fishing hooks. Constants for stages are defined here.

Constant	Value	Description
STAGE_STUCK	0	Hook stuck on non-water block
STAGE_SETTLE	1	Settling on water surface
STAGE_WAIT	2	Waiting for fish
STAGE_TEASES	3	Fish teasing the bait
STAGE_BITES	4	Fish biting (player must reel)

Can be used to create custom fishing hooks. Default implementation: DefaultFishingHook.

DefaultFishingHook

Entity implementation of FishingHook. Constant MAX_PLAYER_DISTANCE (32.0) defines max player–hook distance.

DefaultFishingConfig

Basic implementation of FishingConfig. Uses only configuration values (no enchantments) for all stage timings and distances.

LureFishingConfig

Alternative implementation of FishingConfig that applies the Lure enchantment to the wait stage. Reduces wait-stage duration based on the Lure level on the fishing rod (100 ticks ≈ 5 seconds per level). Can be used as a drop-in replacement for DefaultFishingConfig.

Stage flow diagram

stateDiagram-v2
    state FishingStage {
        direction TB

        [*] --> STAGE_SETTLE
        STAGE_SETTLE --> STAGE_WAIT : Staying on water surface
        STAGE_SETTLE --> STAGE_STUCK : Staying on other blocks
        STAGE_WAIT --> STAGE_TEASES : Time over
        STAGE_TEASES --> STAGE_BITES : Time over

        state IF_AUTO_RETRY <<choice>>
        state IF_PLAYER_RESPONSE <<choice>>
        STAGE_BITES --> IF_PLAYER_RESPONSE : Time over
        IF_PLAYER_RESPONSE --> SUCCESS : Player uses fishing rod
        IF_PLAYER_RESPONSE --> IF_AUTO_RETRY : Time over

        IF_AUTO_RETRY --> STAGE_WAIT : if auto_retry
        IF_AUTO_RETRY --> FAILURE : if not auto_retry
    }

Loading

• If the player uses the fishing rod at a time not declared in the diagram above, it will be CANCEL.
• If the player was disconnected or died, it will be CANCEL.

Events

FishingCastEvent

Fired when a player tries to cast a fishing rod, before the session is created.

• Cancellable: Yes
• Properties:
  • getPlayer(): Player
  • getFishingRod(): FishingRod
  • setFishingRod(FishingRod $fishingRod): void

FishingReelEvent

Fired when a player reels the fishing rod while fishing.

• Cancellable: Yes
• Extends: FishingEvent (provides getFishingSession(), getPlayer(), getFishingHook(), getFishingRod())

FishingSuccessEvent

Fired when fishing is successful.

• Cancellable: Yes
• Properties:
  • getRewardItems(): Item[]
  • setRewardItems(Item[] $items): void
  • getDropXp(): int
  • setDropXp(int $xp): void
• Reward items and XP are automatically given to the player unless they die or leave.

FishingFailureEvent

Fired when fishing fails (fish escapes; player missed the bite window).

• Cancellable: No
• Properties:
  • isAutoRetryEnabled(): bool — Whether auto-retry is configured
  • setAutoRetry(bool $enabled): void — Override auto-retry for this failure (e.g. force retry or cancel)

FishingCancelEvent

Fired when fishing is cancelled (player action, hook error, or session close).

• Cancellable: No
• Properties:
  • getReason(): int — One of the cause constants below
• Cause constants:
  • CAUSE_BY_PLAYER (0) — Player cancelled (e.g. moved, switched item)
  • CAUSE_BY_HOOK_ERROR (1) — Hook error (e.g. out of range)
  • CAUSE_BY_SESSION_CLOSE (2) — Session closed programmatically

Stage events (FishingStartStageEvent and subclasses)

Fired when each stage begins. All extend FishingEvent and are Cancellable.

Event	When
FishingStartWaitEvent	Wait stage starts
FishingStartTeasesEvent	Teases stage starts
FishingStartBitesEvent	Bites stage starts

Properties (from FishingStartStageEvent):

• getMaxStageTicks(): int
• setMaxStageTicks(int $ticks): void

Use setMaxStageTicks() to customize stage duration per session (e.g. for mini-games).

Example: Listen to fishing success

use kim\present\system\fishing\event\result\FishingSuccessEvent;
use pocketmine\event\Listener;

final class FishingListener implements Listener{

    /** @handleCancelled false */
    public function onFishingSuccess(FishingSuccessEvent $event) : void{
        $player = $event->getPlayer();

        // Override default rewards
        $event->setRewardItems([]);
        $event->setDropXp(10);

        $player->sendMessage("You caught something special!");
    }
}

Register the listener in your plugin's onEnable().

Example: Use LureFishingConfig

use kim\present\system\fishing\FishingSystem;
use kim\present\system\fishing\config\LureFishingConfig;

// This example assumes the default values from resources/config.yml
FishingSystem::getInstance()->setFishingConfig(
    new LureFishingConfig(
        waitStageTickMin: 100,
        waitStageTickMax: 600,
        teasesStageTickMin: 40,
        teasesStageTickMax: 100,
        teasesStageDistanceMin: 2.0,
        teasesStageDistanceMax: 5.0,
        bitesStageTickMin: 40,
        bitesStageTickMax: 80,
        autoRetryEnabled: true,
        rodDamageEnabled: true
    )
);

Example: Customize bites stage duration (e.g. mini-game)

use kim\present\system\fishing\event\stage\FishingStartBitesEvent;
use pocketmine\event\Listener;

final class FishingMiniGameListener implements Listener{

    public function onStartBites(FishingStartBitesEvent $event) : void{
        // Set bites stage to 3 seconds
        $event->setMaxStageTicks(60); // 60 ticks = 3 seconds
    }
}