RoseFirefighter/README.md

# RoseFirefighter

RoseFirefighter is a Paper 26.2 companion plugin for **JobsReborn**. It does not implement its own economy or leveling system. Instead, it detects legitimate firefighting actions and submits matching JobsReborn actions so JobsReborn continues to handle job membership, levels, job XP, income progression, bonuses, taxes, payment limits, payment visualization, and level-ups.

## Supported firefighting

- Extinguishing `FIRE`.
- Extinguishing `SOUL_FIRE`.
- Extinguishing lit `CAMPFIRE` blocks.
- Extinguishing lit `SOUL_CAMPFIRE` blocks.
- Water-bucket extinguishing when the affected fire can be attributed to the player who emptied the bucket.
- Controlled RoseFirefighter emergency fires.

Only players currently working the configured JobsReborn `Firefighter` job can receive the submitted JobsReborn rewards.

## Anti-farming behavior

With `rewards.anti-farm: true`, RoseFirefighter rejects payment for player-created fire, including:

- Flint-and-steel ignition.
- Fire-charge/direct player ignition.
- Fire started by a projectile shot by a player.
- Fire spread from a player-created fire.
- Fire caused by player-placed lava or tracked lava flow.
- Campfires a player relights and then extinguishes.

Active player-created fire and active player-placed lava remain tainted for as long as those sources still exist; they do not become payable merely because a timer expires. Configurable retention timers remain after the active source disappears. A separate location cooldown prevents duplicate/delayed-event payouts and repeated same-location farming.

Creative and spectator players do not receive rewards by default. Creative earning can be enabled explicitly in `config.yml`.

## Requirements

- Paper 26.2
- Java 25 for compilation/server runtime
- JobsReborn 5.2.6.x
- CMILib, as required by JobsReborn
- A JobsReborn-compatible economy if monetary payouts are desired

## Build

The repository includes the Gradle 9.6.1 Wrapper. A global Gradle installation is **not** required.

Windows:

```text
gradlew.bat clean build
```

Linux/macOS:

```text
./gradlew clean build
```

The resulting plugin JAR is written to `build/libs/`.

## Install

1. Copy `jobs/Firefighter.yml` to:

   `plugins/Jobs/jobs/Firefighter.yml`

2. Reload JobsReborn or restart the server.

3. Copy the RoseFirefighter JAR from `build/libs/` into the server's `plugins/` directory.

4. Restart Paper.

5. Players can join the profession with the normal JobsReborn command, for example:

   `/jobs join Firefighter`

## JobsReborn payouts

`jobs/Firefighter.yml` contains the base income and job-XP values. RoseFirefighter does not calculate those amounts itself.

| Verified extinguish | JobsReborn action | Base income | Base job XP |
|---|---|---:|---:|
| `FIRE` | `BREAK/FIRE` | 1.00 | 1.00 |
| `SOUL_FIRE` | `BREAK/SOUL_FIRE` | 1.25 | 1.25 |
| `CAMPFIRE` | `COLLECT/CAMPFIRE` | 0.50 | 0.50 |
| `SOUL_CAMPFIRE` | `COLLECT/SOUL_CAMPFIRE` | 0.75 | 0.75 |

Campfires intentionally use a synthetic JobsReborn `COLLECT` action. Putting campfires under the JobsReborn `Break` section would also reward players for simply mining the campfire block.

The per-type `action-count` options in RoseFirefighter's `config.yml` control how many JobsReborn actions are submitted for a verified extinguish. Keep them at `1` for the normal base payout. Emergency fires additionally apply `emergencies.reward-multiplier`, which defaults to `5`.

## Emergency sites

Stand at the center of an area where controlled emergencies may appear:

```text
/firefighter site add RoseGarden 18
```

Other management commands:

```text
/firefighter status
/firefighter site remove <name>
/firefighter site list
/firefighter emergency start <site>
/firefighter emergency stop
/firefighter reload
```

`rosefirefighter.admin` is required for site, emergency, and reload management and defaults to server operators.

## Emergency behavior

Automatic emergencies default to a random 30-60 minute interval and require at least one online Firefighter. Manual starts use the same online-Firefighter requirement unless `emergencies.require-firefighters-online` is disabled.

Emergency fire generation:

- Uses admin-defined named sites and radii.
- Can be limited to configured world names with `emergencies.allowed-worlds`.
- Places only temporary fire blocks on safe solid support blocks.
- Does not replace the supporting block.
- Cancels emergency-fire spread and spread ignition.
- Cancels nearby block burning.
- Tracks and removes remaining emergency fire on completion, manual stop, expiry, plugin disable, or server shutdown.
- Periodically removes stale tracked entries if an emergency fire disappears through another legitimate game event.
- Broadcasts configurable alerts, by default to all online players.

Example alert:

```text
🔥 FIRE ALERT! A fire has been reported at RoseGarden near X:123 Y:64 Z:-245. Firefighters are needed immediately!
```

## Configuration

`src/main/resources/config.yml` includes controls for:

- JobsReborn job name.
- Normal fire, soul fire, campfire, and soul-campfire action submission.
- Duplicate reward cooldown.
- Player-created-fire and player-lava tracking retention.
- Creative-mode earning.
- Water attribution scan radius.
- Emergency enable/disable and automatic scheduling.
- Minimum online Firefighters.
- Emergency duration and fire counts.
- Emergency reward multiplier.
- Announcement behavior.
- Permitted emergency worlds.
- Saved emergency sites.

## Development notes

Paper 26.2 uses the current Paper dependency format and Java 25 toolchain:

```kotlin
compileOnly("io.papermc.paper:paper-api:26.2.build.+")
```

JobsReborn is referenced through its documented JitPack coordinate:

```kotlin
compileOnly("com.github.Zrips:Jobs:v5.2.6.2")
```

The JobsReborn dependency is non-transitive because RoseFirefighter only needs the JobsReborn API classes and should not pull JobsReborn's optional integration dependencies into its compile classpath.