String Rituals

A fully configurable, in-game ritual & altar system for Paper servers. Build craftable altars, spawn world ritual drops, and edit everything from a GUI - no config files required.

Note: This is an early test release. Requires Paper (or a Paper fork such as Purpur). It does not run on Spigot or CraftBukkit.

---

Features

• Recipe Rituals (crafting altars): place an altar for any recipe. Stand near it with the required ingredients and a spinning result item appears, then drops on completion. Supports normal and One-Shot altars (removed after one craft). Any player can craft at an altar - only admins (ritual.admin) can spawn or place them.
• World Rituals ("Rituals"): floating, spinning ritual items that spawn in the world on demand, with optional server-wide broadcasts (start + coordinates + completion).
• Random Spawns: turn it on and any ritual flagged "Random Spawn" will automatically appear somewhere inside the world border on a set interval, live for a configurable lifetime, then despawn. Great for surprise world events. Off by default.
• Full in-game editor: create/edit recipes, set results, durations, visual presets, rename, add/remove ingredients via drag-and-drop, place/remove altars, and toggle random spawning - all from the GUI.
• Global settings: toggle broadcasts, coordinates, sounds, particles, lightning, broadcast interval, default duration, per-craft broadcasts, and random spawns.
• 11 hand-tuned visual presets with massively boosted particle & audio effects (twin rotating rings, rising pillars, orbiting motes, ground shockwaves, and per-theme signature flourishes like lightning strikes, flame jets, and dragon's breath).
• Custom weapons: built-in Cataclysm, Eclipse, Widowmaker, and Oathbreaker items for use as ritual results.
• Everything is data-driven: recipes live under rituals:, world rituals under drop-rituals:. I don't need to edit config files by hand.

---

Installation

1. Download StringRituals.jar.
2. Drop it into your server's plugins/ folder.
3. Restart (or run /reload). A config.yml is created automatically with example rituals.
4. OP yourself (or grant ritual.admin) and run /ritual settings.

---

Getting Started

1. Open the control panel

• Run /ritual settings.
• The main menu shows 9 toggle panes and two list buttons: Recipe Rituals and Rituals.

2. Global settings (main menu)

• Click any green/red pane to toggle: Broadcast Coords, Initial Broadcast, Completion Broadcast, Broadcast Crafts, Sounds, Particles, Lightning, Random Spawns, Random Broadcast.
• Click the paper panes to change Broadcast Interval, Default Duration, and Random Interval.

3. Create a Crafting Ritual (altar)

1. Main menu → Recipe Rituals → New Recipe (emerald block).
2. Type an ID in chat (e.g. fire_blade) - letters, numbers and _ only.
3. In the editor: Set Result = hold the item you want crafted, then click it. Rename = type a display name. Set Duration and Preset.
4. Ingredients → Add Ingredient → drag one item into any slot, then click Save Ingredient (repeat for more). Click an ingredient in the list to remove it.
5. Place Altar Here spawns the altar at your location (or /ritual place <id>). Toggle One-Shot Altar ON to remove it after one craft.
6. Craft: stand near the altar with the required items in your inventory - the ritual auto-starts, a spinning result item appears, and the item drops when the timer ends. (Or /ritual craft <id> from anywhere.)

4. Create a World Ritual (drop)

1. Main menu → Rituals → New Ritual (emerald block). Hold the result item, then type an ID in chat.
2. Editor: set Duration / Preset / Rename. Click Spawn Now to drop it at your location.
3. Command alternative: /ritual create <id> <preset> <seconds> (while holding the result item), then /ritual spawn <id>. List with /ritual list, remove with /ritual remove <id>.

---

Random Spawns

1. Open /ritual settings → enable Random Spawns, set Random Interval (seconds between attempts) and Random Broadcast.
2. In any ritual's editor (Recipe or World), toggle Random Spawn ON and set its Random Lifetime (how long a randomly spawned instance stays before despawning).
3. On each interval the plugin picks a random enabled ritual with Random Spawn ON and drops it at a random spot inside the world border (on the surface). Recipe rituals spawn a temporary altar; world rituals spawn a temporary forge. Both auto-despawn after their lifetime.

Note: the master Random Spawns switch is OFF by default, so nothing spawns until you enable it.

---

Commands

Command	Description
/ritual settings	Open the GUI control panel
/ritual list	List all world rituals
/ritual create <id> <preset> <seconds>	Register a world ritual (hold the result item)
/ritual spawn <id> [x y z world]	Spawn a world ritual at a location
/ritual remove <id>	Remove a world ritual
/ritual place <recipe> [x y z world]	Place a crafting altar
/ritual craft <recipe>	Start a craft at your location (no altar)
/ritual give <cataclysm|eclipse|widowmaker|oathbreaker|all> [player]	Give a custom weapon
/ritual reload	Reload config
/string	Fill your empty inventory slots with string

---

Permissions

Permission	Default	Description
ritual.admin	op	Access to all /ritual commands and the editor
stringrituals.string	true	Use /string

---

Configuration

All settings live in config.yml under the ritual: section and are editable live from the GUI. Recipes are stored under rituals:; world rituals under drop-rituals:. Example (ships by default):

ritual:
  default-duration: 30
  broadcast-interval: 10
  initial-broadcast: true
  broadcast-coords: true
  completion-broadcast: true
  broadcast-craft: false
  sounds: true
  particles: true
  lightning: true
  display-scale: 1.0
  random-spawns: false
  random-interval: 300
  random-broadcast: true

rituals:
  example_relic:
    enabled: true
    oneShot: false
    duration: 30
    preset: arcane
    name: Example Relic
    result: NETHERITE_SWORD
    ingredients:
      DIAMOND: 4
      NETHERITE_INGOT: 1

drop-rituals:
  example_world_drop:
    enabled: true
    duration: 45
    preset: void
    item: TOTEM_OF_UNDYING

---

Visual Presets

The preset controls the particle/audio theme of a ritual. I trimmed the list to the 11 with the most potential and gave each a massive visual boost:

arcane · tempest · inferno · glacier · void · abyss · shriek · warp · bloodmoss · soul · dragon

---

Compatibility

• Supported: Paper, Purpur (and other Paper-based forks).
• Not supported: Spigot, CraftBukkit - the plugin uses Paper's Adventure Component API and org.joml math, which those loaders lack.

---

Feedback

This is a test release. Found a bug or have an idea? Leave a comment on the Modrinth project - it directly shapes what I fix and add next.