Skip to content

Astral Swords — Configuration

All plugin configuration is managed through a single unified config.yml file in plugins/AstralSwords/.

Unified Configuration

As of v1.8.18, all configuration has been consolidated into a single config.yml file. Previous separate config files (protection_config.yml, graceperiod_config.yml, worldborder_config.yml, ritual_config.yml, sword-display-config.yml, sword_enchants.yml, sword_recipes.yml, ability_attributes.yml) are automatically migrated and deleted on upgrade.

Configuration Sections

Container Protection

Controls whether swords can be placed in containers and interacted with in anvils.

protection:
  allow-container-storage: false    # Allow swords in chests, barrels, shulkers, etc.
  allow-item-frames: false          # Allow swords in item frames
  allow-hopper-pickup: false        # Allow hoppers to pick up swords
  allow-anvil-renaming: false       # Allow renaming swords in anvils
  allow-anvil-enchanting: false     # Allow adding enchantment books to swords in anvils

Grace Period System

Controls the PvP protection grace period when starting the SMP.

grace-period:
  duration: 900                 # Duration in seconds (default: 900 = 15 minutes)
  display-type: BOSSBAR         # Display type: BOSSBAR or ACTIONBAR
  bossbar-color: PURPLE         # BossBar color: BLUE, GREEN, PINK, PURPLE, RED, WHITE, YELLOW
  prevent-chest-access: false   # Block other players' chest access during grace
  per-player-enabled: true      # Enable per-player grace periods for late joiners

World Border Expansion

Settings for the world border expansion system.

world-border:
  initial-size: 50              # Starting border size in blocks
  final-size: -1                # Final size (-1 = Minecraft default 60,000,000)
  expansion-speed: 5.6          # Blocks per second per side
  expansion-countdown: 10       # Countdown before expansion starts (seconds)

Countdown Effects

Visual and audio effects during the SMP start countdown.

countdown-effects:
  countdown-title: "Astral Uni"
  countdown-subtitle: "Starting in {seconds}"
  countdown-title-color: "DARK_PURPLE"
  countdown-subtitle-color: "LIGHT_PURPLE"
  countdown-sound: "BLOCK_NOTE_BLOCK_PLING"
  sound-volume: 1.0
  sound-pitch: 1.0

Expansion Announcement

Announcement settings when the world border starts expanding.

expansion-announcement:
  expansion-title: "World Expanding!"
  expansion-subtitle: "The world border is growing..."
  expansion-title-color: "GREEN"
  expansion-subtitle-color: "AQUA"
  chat-announcement: true
  chat-message: "The world border is expanding! Prepare for adventure!"

Startup Messages

Messages displayed after the world border expansion starts.

startup-messages:
  enabled: true
  sound-sequence:
    thunder:
      enabled: true
      sound: "ENTITY_LIGHTNING_BOLT_THUNDER"
      volume: 2.0
      pitch: 0.9
      delay: 0
    dragon:
      enabled: true
      sound: "ENTITY_ENDER_DRAGON_GROWL"
      volume: 2.0
      pitch: 0.8
      delay: 1
  separator: "----------------------------------------"
  message1:
    enabled: true
    text: "Astral SMP has started!"
  message2:
    enabled: true
    text: "All players get {grace_period} min grace period (PvP disabled)"
  message3:
    enabled: true
    text: "Welcome to the ultimate survival experience!"
  message4:
    enabled: true
    text: "Good luck, everyone! ~ CiscoCodes"

Ritual Crafting System

Overview

Ritual crafting transforms sword creation into dramatic server-wide events where players must defend a charging ritual while the sword materializes in 3D space.

How Ritual Crafting Works

1. Initiation

  • Player crafts an Astral Sword in a crafting table
  • System detects craft completion
  • Instead of giving item: Destroys crafting table and starts ritual
  • 3D sword model spawns 3 blocks above the crafting location

2. Ritual Process

  • 3D Model: Full-scale sword floating and rotating in air
  • Animation: Gentle bobbing motion (configurable amplitude)
  • Rotation: Configurable rotation speed
  • Duration: Configurable per sword (2-4 minutes typically)

3. Visual Effects

  • Particle Effects: Flame particles in spiral pattern, enchantment glint orbiting
  • Intensity: Increases as charge progresses
  • Hologram Display: Sword name, charge percentage, time remaining

4. Server Announcements

  • Title Display (All Players): Configurable title, subtitle, colors, and duration
  • Boss Bar — Progress from 0% to 100%, configurable color, visible to all

5. Protection & Effects

  • Protection Zone: Configurable radius around ritual site (default 15 blocks)
  • Enhanced Spawning: Configurable mob spawn rate increase
  • Block Protection: Configurable building restrictions
  • PvP Settings: Configurable combat rules in ritual zones

6. Completion

  • Lightning strike visual + thunder sound
  • 3D sword model drops as actual item
  • Configurable completion announcement to all players

Ritual Management

  • Concurrent Limits: Maximum 1-3 rituals server-wide (configurable)
  • Queue System: Automatic queuing when limits reached (configurable queue size, wait time, process interval)
  • Interruption: Rituals can be cancelled by admins or area destruction
  • Persistence: Active rituals survive server restarts

Ritual Configuration

ritual-mode:
  enabled: false
  max-concurrent-rituals: 1

queue-settings:
  max-queue-size: 50
  max-wait-time: 10
  process-interval: 1

ritual-durations:
  SKYFALL_BLADE: 120        # Duration in seconds
  DRAGONS_WRATH: 180
  SOUL_REAVER: 240
  # ... (all 17 swords configurable)

announcement-settings:
  title-duration: 5
  subtitle-fade: 2
  boss-bar-color: "PURPLE"
  ritual-start-title: "Astral RITUAL"
  ritual-start-subtitle: "Defend the sword as it charges!"
  ritual-complete-title: "Astral Ritual Complete!"
  ritual-complete-subtitle: "{sword_name} has been forged!"

protection-settings:
  radius: 15
  block-breaking: false
  pvp-enabled: true
  mob-spawn-multiplier: 1.5

visual-settings:
  particle-intensity: 1.0
  hologram-update-interval: 20
  model-rotation-speed: 0.5
  bobbing-amplitude: 0.5

Sword Display (Rituals)

display-method: "ItemDisplay"     # Methods: ItemDisplay (1.19.4+), BlockDisplay, TextDisplay, ArmorStand

animation:
  rotation-speed: 0.314159
  bobbing:
    amplitude: 0.5
    frequency: 0.1

visual:
  scale: 1.0
  glow: true
  brightness: 15

Sword Settings

Base Material

sword-material: NETHERITE_SWORD   # Options: NETHERITE_SWORD, DIAMOND_SWORD

Enchantments

Default enchantments applied to each sword when crafted. Configurable per sword.

sword-enchants:
  skyfall_blade:
    sharpness: 8
    unbreaking: 4
  dragons_wrath:
    sharpness: 8
    unbreaking: 4
    fire_aspect: 5
  # ... (all 17 swords configurable)

Recipes

Crafting recipes for each sword using a 3x3 grid (slots 0-8). Each sword can be individually enabled/disabled.

sword-recipes:
  skyfall_blade:
    enabled: true
    recipe:
      0: ELYTRA
      1: NETHER_STAR
      2: ELYTRA
      # ...

Ability Attributes

All ability attributes are configurable per sword including cooldowns, damage values, durations, and radii. Cooldowns are in milliseconds, durations in ticks (20 ticks = 1 second).

ability-attributes:
  skyfall_blade:
    cooldown: 30000
    launch_power: 2.5
    base_explosion_radius: 8.0
    base_explosion_damage: 15.0
  # ... (all 17 swords configurable)

Server-Wide Toggles

Global toggles that affect all players on the server.

server-toggles:
  # When true: All players can hold multiple astral swords
  multi-sword-wielding: false

  # When true: Each sword type can only be crafted once on the entire server
  craft-limit: true

Runtime-Generated Files

The following files are created automatically at runtime:

File Purpose
player_languages.yml Stores per-player language preferences
gracedplayers.yml Tracks players who have received grace periods (prevents repeats)
smp_state.yml Persists SMP state (who started, when, active status)

Language Files

8 built-in language files are located in plugins/AstralSwords/messages/:

File Language
en_US.yml English (US)
es_ES.yml Spanish
fr_FR.yml French
de_DE.yml German
pl_PL.yml Polish
nl_NL.yml Dutch
hi_IN.yml Hindi
ur_PK.yml Urdu

Players' client language is auto-detected on join. Language preference can be changed with /as language <code>.