# Mcast-Campfire

**Campfire** is a small Paper plugin for creating named campfire places.

It allows an admin or permitted player to create named campfires directly in the world. Each fire is stored as its own YAML file and can have individual timing, cooldown, chat message, potion effects, sounds and scene.

Campfires can become resting places, cursed fires, RPG locations or story elements without affecting other fires on the server.

## Main Features

* Named campfires stored as individual YAML files.
* Supports CAMPFIRE, SOUL_CAMPFIRE, FIRE and SOUL_FIRE.
* Individual cooldown and activation settings for every fire.
* Optional night-only activation with per-fire override.
* Original built-in **Good** and **Dark** scenes.
* Configurable chat messages, sounds, particles and potion effects.
* Original music motifs stored separately in YAML files.
* Permission-based player fire limits.
* Multi-language support including English and Czech.

## Typical Uses

Mcast-Campfire is suitable for:

* villages,
* RPG servers,
* resting places,
* adventure maps,
* story locations,
* themed events.

## Commands

/campfire help
/campfire reload
/campfire create <name>
/campfire cancel
/campfire list
/campfire show <name>
/campfire remove <name>
/campfire refuse <fire> add <players...>
/campfire refuse <fire> clear

Players with limit 2 or 4 can gradually add players refused by their own fires. Administrators can manage this list for every fire.

## Permissions

* mcast.campfire.limit.1 - 1 fire
* mcast.campfire.limit.2 - 2 fires
* mcast.campfire.limit.4 - 4 fires
* mcast.campfire.admin - unlimited management

If a player has more than one limit permission, the highest limit applies.

## Harbour Ownership Audit

The optional startup audit sends Harbour the actual owned fire inventory. Harbour returns current owner limits. Campfire keeps the oldest fires up to the returned limit and completely unregisters only newer excess definitions. Disabled owned fires count; the template and definitions without an owner do not.

Enable it with `audit.enabled` and configure `audit.endpoint` and `audit.token`. The hosted endpoint must use HTTPS; HTTP is accepted only for localhost. Backend identity and runtime context are read from the already running Octopus plugin. Campfire never connects to the Octopus database and never changes Octopus.

Existing fires receive stable creation metadata through a safe one-time local migration. Any migration, context, HTTP, response, or inventory validation failure leaves all fires unchanged. OP and active Campfire admin owners are reported as exempt.

## Configuration

By default, campfires activate only at night.

night:
  start-tick: 13000
  end-tick: 23000

Each fire can override this using `activation.night-only`.

The default cooldown is **240 seconds**. After the cooldown expires, the player must stay near the fire again before another scene can start.

## Scenes

Two built-in scene programs are available:

* good
* dark

The **Good** scene creates a warm campfire atmosphere with an original country/folk-rock ensemble of bass, rhythm, guitar, and banjo.

The **Dark** scene creates a cold atmosphere with an original shadowed country/blues motif.

Scenes are personal and are played only for the player who activated the fire. The plugin intentionally does not use Minecraft titles or subtitles.

## Music

Scene melodies are stored separately:

songs/good.yml
songs/dark.yml

These files contain original short musical motifs created specifically for this plugin.

## Potion Effects

Potion effects use standard Minecraft/Paper effect names and must also be listed in `allowed-effects` inside `config.yml`.

When a scene starts, the selected potion effect remains active for at least the entire duration of the scene.

Typical positive effects:

* REGENERATION
* SATURATION
* ABSORPTION
* SPEED
* RESISTANCE

Typical negative effects:

* SLOWNESS
* WEAKNESS
* DARKNESS
* GLOWING

## Notes

* Players can extinguish only their own fires.
* Administrators can manage all fires.
* A fire must remain burning to activate.
* Leaving and re-entering the activation area does not queue additional scenes.

## Technical Information

* Paper **1.21.11**
* Compatible with the entire **Minecraft 1.21.x** series
* Server-side plugin
* YAML-based configuration
* Lightweight and optimized for performance

**Author:** Mcast
