SLBossSpawner

OverviewTổng quan

InstallationCài đặt

• + Use Paper 1.21.11 / Java 21 and install MythicMobs 5.13.0
• + Place SLBossSpawner-3.1.0.jar into plugins/
• + Restart the server — config files are generated automatically
• + Edit configs in plugins/SLBossSpawner/
• + Run /slboss reload to apply changes

• + Dùng Paper 1.21.11 / Java 21 và cài MythicMobs 5.13.0
• + Bỏ file SLBossSpawner-3.1.0.jar vào thư mục plugins/
• + Restart server — các file config sẽ được tạo tự động
• + Chỉnh cấu hình trong plugins/SLBossSpawner/
• + Gõ /slboss reload để áp dụng

config.yml

# SLBossSpawner Configuration
prefix: "&#FF6B6B[&#FFD93DSLBossSpawner&#FF6B6B] "
debug: false
language: "vi"   # "en" = English, "vi" = Tieng Viet

schedules.yml

Each top-level key defines a boss with its MythicMob, schedule, location, and broadcast settings.

Mỗi khoá cấp cao nhất là một Boss, gồm thông tin MythicMob, lịch spawn, vị trí và cài đặt thông báo.

boss:                          # Boss ID (must match reward.yml)
  mythicmob: SkeletonKing     # MythicMobs internal name
  expire: 3600                # Despawn after 3600s (1 hour)
  clearOnExpire: true          # Remove entity when expired
  time-settings:
    zone: Asia/Ho_Chi_Minh    # IANA timezone
    time:
      - "12:00"               # Spawn at noon
      - "18:00"               # Spawn at 6 PM
      - "21:00"               # Spawn at 9 PM
  location:
    x: 100  y: 64  z: -200
    world: bossworld
    leashRadius: 10           # Max wander distance (0 = no limit)
  loadChunks: true             # Force-load spawn chunk
  broadcast:
    death:
      chat: true  title: true
    spawn-warning:
      chat: true  title: true  bossbar: true
      intervals: [30, 15, 5, 1]  # Warning at X minutes before spawn

reward.yml

Reward configuration per boss. Each boss has 3 categories: damage, tank, support — each with configurable tiers.

Cấu hình phần thưởng cho từng Boss. Mỗi Boss có 3 hạng mục: sát thương, chịu đòn, hỗ trợ — mỗi hạng mục chia thành nhiều bậc thưởng khác nhau.

boss:                               # Must match schedules.yml ID
  enabled: true
  item-protection:
    enabled: true
    duration: 60                   # Seconds before expiry
    expire-action: public          # "public" or "despawn"
  last-hit-bonus:
    multiplier: 1.5                # Bonus for the killing blow
  global-multiplier: 1.0           # Multiply all item amounts

  damage:                            # Damage category
    enabled: true
    tiers:
      1:                              # Rank #1
        multiplier: 3.0
        commands:
          - "eco give {player} 5000"
        drop-tables:
          - "BossLootTable"
        items:
          - type: vanilla
            material: DIAMOND
            amount: 5
            display-name: "&#FFD93D&lTop 1 Damage"

boss2:
  enabled: true
  damage:
    enabled: true
    tiers:
      1:
        multiplier: 1.0
        commands:
          - "cmi saveditems get ruinbladeboss -t:{player}"
          - "cmi money give {player} 10000"
      2:
        multiplier: 1.0
        commands:
          - "cmi saveditems get ruinbladeboss -t:{player}"
          - "cmi money give {player} 5000"
      3:
        multiplier: 1.0
        commands:
          - "cmi saveditems get ruinbladeboss -t:{player}"
          - "cmi money give {player} 2500"
      4:
        multiplier: 1.0
        commands:
          - "cmi saveditems get ruinbladeboss -t:{player}"
          - "cmi money give {player} 1000"
      5:
        multiplier: 1.0
        commands:
          - "cmi saveditems get ruinbladeboss -t:{player}"
          - "cmi money give {player} 500"

# Place under boss2.damage.tiers.1 (or another category/rank)
random-loot:
  enabled: true
  rolls: 1
  entries:
    - type: vanilla
      material: NETHERITE_INGOT
      amount: 1
      weight: 5
      chance: 25
    - type: command
      command: "cmi money give {player} 10000"
      weight: 1
      chance: 10

# Vanilla Minecraft item
- type: vanilla
  material: DIAMOND
  amount: 5
  display-name: "&#FFD93D&lCustom Name"

# MMOItems item (requires MMOItems plugin)
- type: mmoitems
  material: SWORD           # MMOItems type
  id: "CUSTOM_SWORD"        # MMOItems ID
  amount: 1

# MythicMobs item (built-in)
- type: mythicmobs
  material: "CustomItem"   # MythicMobs internal name
  amount: 1

Player TrackingTheo dõi người chơi

SLBossSpawner tracks player contributions in 3 independent categories during boss fights:

Trong mỗi trận đánh Boss, plugin sẽ theo dõi đóng góp của người chơi qua 3 hạng mục riêng biệt:

Reward SystemHệ thống phần thưởng

How It Works

Cách hoạt động

1. Boss dies — MythicMobDeathEvent triggers reward distribution
2. Rankings built — Players sorted by contribution per category
3. Tier matching — Rank #1 gets tier 1 rewards, rank #2 gets tier 2, etc.
4. Multipliers applied — tier x global x last-hit-bonus (if applicable)
5. Rewards delivered — Commands executed, items given (or dropped with protection)
6. Offline queue — If player is offline, rewards are saved and delivered on next join

1. Boss chết — MythicMobDeathEvent kích hoạt việc chia thưởng
2. Lập bảng xếp hạng — Người chơi được xếp theo đóng góp ở mỗi hạng mục
3. Ghép bậc thưởng — Hạng 1 nhận thưởng bậc 1, hạng 2 nhận bậc 2, v.v.
4. Áp hệ số nhân — bậc x toàn cục x thưởng đòn kết liễu (nếu có)
5. Phát thưởng — Chạy lệnh, trao đồ vào túi (hoặc rơi ra kèm bảo vệ nếu túi đầy)
6. Hàng đợi offline — Người chơi đang offline sẽ nhận thưởng khi đăng nhập lại

Pending rewards are created only for recipients who are offline when the boss dies. For online recipients, command output and warnings appear in the server console; CMI can still reject a player name after Bukkit accepts the dispatch. If fewer than five players were tracked, only those ranked players can receive tiers 1–5. The reported two-of-five case has no confirmed cause without these server logs.

Chỉ người đang offline lúc boss chết mới có phần thưởng chờ. Với người online, kết quả và cảnh báo lệnh nằm trong console; CMI vẫn có thể từ chối tên sau khi Bukkit nhận lệnh. Nếu chỉ ghi nhận dưới năm người, chỉ các hạng thực tế trong số 1–5 được nhận thưởng. Cần log server để xác định nguyên nhân thật của trường hợp chỉ nhận hai trên năm phần thưởng.

BroadcastsThông báo

Spawn Warnings

Cảnh báo trước khi spawn

Countdown warnings are sent at configured intervals (in minutes) before boss spawn. Channels: chat, title, bossbar — each independently toggleable.

Thông báo đếm ngược được gửi theo các mốc thời gian (tính bằng phút) trước khi Boss xuất hiện. Có 3 kênh: chat, title, bossbar — mỗi kênh bật/tắt riêng.

Death Announcements

Thông báo khi Boss bị hạ

When a boss dies, announcements show the killer's name. Ranking leaderboards display the top contributors per category.

Khi Boss bị tiêu diệt, hệ thống sẽ thông báo tên người hạ gục. Bảng xếp hạng hiển thị top người đóng góp theo từng hạng mục.

Item ProtectionBảo vệ vật phẩm

When a player's inventory is full, reward items drop on the ground with owner-only pickup protection.

Khi túi đồ người chơi đầy, vật phẩm thưởng sẽ rơi xuống đất và được khoá cho chủ nhân — chỉ người đó mới nhặt được.

1. Item dropped → tagged with owner UUID via PersistentDataContainer
2. Other players cannot pick up — shown actionbar denial message
3. After duration seconds, based on expire-action:
   • public — Protection removed, anyone can pick up
   • despawn — Item removed from the world

1. Vật phẩm rơi ra → được gắn UUID chủ nhân qua PersistentDataContainer
2. Người khác nhặt sẽ bị từ chối, kèm thông báo trên actionbar
3. Sau duration giây, tuỳ theo expire-action:
   • public — Bỏ khoá, ai nhặt cũng được
   • despawn — Vật phẩm biến mất

PersistenceLưu trữ dữ liệu

Boss State

Trạng thái Boss

Active bosses are saved to boss-state.yml and restored on server restart. An expired boss is removed and rescheduled after its saved entity is verified. If an old state row has no saved location and cannot be verified, scheduled spawns pause. After checking that the old mob is gone, an operator can run /slboss state forget <bossId> to release it.

Boss đang hoạt động được lưu vào boss-state.yml và phục hồi sau restart. Boss hết hạn được xóa và lên lịch mới sau khi xác minh entity cũ. Nếu trạng thái cũ không có vị trí và không thể xác minh, lượt spawn theo lịch sẽ tạm dừng. Sau khi kiểm tra boss cũ đã biến mất, quản trị viên dùng /slboss state forget <bossId> để mở lại.

Offline Rewards

Phần thưởng khi offline

Rewards for offline players are saved to pending-rewards.yml and automatically delivered when the player joins (2-second delay for safe loading).

Nếu người chơi offline lúc nhận thưởng, phần thưởng sẽ được lưu vào pending-rewards.yml. Khi họ vào lại server, hệ thống tự động trao sau 2 giây (chờ load xong cho chắc).

Legacy pending CMI saveditems/money and Mythic drop-table commands with stripped Bedrock names are repaired when the known player target matches the joining player's UUID. Review other custom pending commands before affected players join.

Lệnh CMI saveditems/money và Mythic drop-table cũ có tên Bedrock bị mất tiền tố sẽ được sửa khi xác định đúng mục tiêu theo UUID người đăng nhập. Hãy kiểm tra các lệnh tuỳ chỉnh cũ trong hàng đợi trước khi người chơi liên quan đăng nhập.

Statistics & LeaderboardThống kê & Bảng xếp hạng

Tracked Metrics

Chỉ số theo dõi

Period Types

Loại kỳ

Statistics are tracked across 7 period types: daily, weekly, monthly, quarterly, seasonal, yearly, alltime. Period rows stay in the YAML snapshot so history remains available without an archive job.

Thống kê được theo dõi qua 7 loại kỳ: daily, weekly, monthly, quarterly, seasonal, yearly, alltime. Các dòng kỳ được giữ trong snapshot YAML để không cần job lưu trữ.

In-memory leaderboard

Bảng xếp hạng trong bộ nhớ

Leaderboard reads sort the in-memory YAML aggregates and do not run a repeating database query. Configure the flush delay and result limit with statistics.flush-seconds and statistics.leaderboard-size.

Bảng xếp hạng sắp xếp aggregate YAML trong bộ nhớ và không chạy truy vấn database lặp lại. Cấu hình thời gian ghi và giới hạn kết quả bằng statistics.flush-seconds và statistics.leaderboard-size.

Statistics Configuration

Cấu hình thống kê

statistics:
  enabled: true
  flush-seconds: 2
  leaderboard-size: 100

Existing external SQL data files are left untouched and are not imported automatically. If an old statistics.database section is still present, it is ignored and a migration warning is logged.

File dữ liệu SQL bên ngoài cũ được giữ nguyên và không tự động nhập. Nếu còn mục statistics.database, plugin sẽ bỏ qua và ghi cảnh báo migration.

CommandsLệnh

Placeholders

Requires PlaceholderAPI. Prefix: %slbs_<bossId>.<key>%

Cần cài PlaceholderAPI. Cú pháp: %slbs_<bossId>.<key>%

Boss Placeholders

Placeholder Boss

Leaderboard Placeholders

Placeholder bảng xếp hạng

Reads from in-memory cache (non-blocking). Returns --- if rank not available.

Đọc từ bộ nhớ đệm (không gây lag). Trả về --- nếu hạng không có.

Periods: alltime, daily, weekly/week, monthly/month, quarterly/quarter, seasonal/season, yearly/year

Các kỳ: alltime, daily, weekly/week, monthly/month, quarterly/quarter, seasonal/season, yearly/year

Player Stats Placeholders

Placeholder thống kê người chơi

Shows requesting player's value from cache. Returns 0 if player not in top N.

Hiện giá trị của người chơi từ cache. Trả về 0 nếu không trong top N.

PermissionsQuyền

ChangelogNhật ký thay đổi

v3.1.0 (2026-10-09)

Statistics and diagnostics

Thống kê và kiểm tra cấu hình

• Replace SQL/JDBC statistics storage with asynchronously loaded, debounced atomic statistics.yml snapshots
• Thay lưu thống kê SQL/JDBC bằng snapshot statistics.yml tải bất đồng bộ, gộp ghi và thay file nguyên tử
• Keep /slboss stats, /slboss top, and statistics/top PlaceholderAPI expansions on the YAML store
• Giữ /slboss stats, /slboss top và PlaceholderAPI thống kê/top trên kho YAML
• Add /slboss validate [bossId] for world, coordinate, schedule, mob-pool, and reward diagnostics
• Thêm /slboss validate [bossId] để kiểm tra world, tọa độ, lịch, mob pool và phần thưởng
• Leave legacy external SQL data files untouched; no automatic import is performed
• Giữ nguyên file dữ liệu SQL bên ngoài cũ; không tự động nhập dữ liệu

v3.0.1 (2026-09-29)

Fixed

Sửa lỗi

• Keep remote spawn chunks loaded with a plugin ticket when loadChunks: true; reject an unloaded chunk when disabled
• Giữ chunk spawn bằng plugin ticket khi loadChunks: true; từ chối spawn vào chunk chưa tải khi tắt
• Verify the MythicMobs entity after one second and log its actual position or disappearance
• Kiểm tra entity MythicMobs sau một giây và ghi vị trí thực tế hoặc việc nó biến mất
• Record each boss's last known position and serialize state-file writes to prevent update races
• Ghi vị trí cuối cùng đã biết của boss và ghi file trạng thái theo thứ tự để tránh ghi đè lẫn nhau
• Keep live bosses and fight rankings through /slboss reload; preserve entities and state on plugin disable
• Giữ boss và bảng xếp hạng trận đấu khi chạy /slboss reload; giữ entity và trạng thái khi tắt plugin
• Reserve unresolved saved boss slots, with /slboss state forget <bossId> for checked legacy state
• Giữ chỗ cho boss chưa khôi phục và thêm /slboss state forget <bossId> cho trạng thái cũ đã kiểm tra
• Warn and skip invalid rank keys; valid tiers 1–5 still match ranked players, with new participant and tier debug counts
• Cảnh báo và bỏ qua khoá hạng sai; bậc hợp lệ 1–5 vẫn ghép người xếp hạng, kèm log số người và số bậc
• Track skill damage and tanking through the final damage event's causing entity where available
• Ghi nhận sát thương skill và chịu đòn qua nguồn gây sát thương ở sự kiện cuối khi server cung cấp
• Preserve exact player names, including Floodgate's default dot prefix and digits, in CMI command rewards and offline delivery
• Giữ nguyên tên người chơi, gồm dấu chấm mặc định của Floodgate và chữ số, khi chạy lệnh CMI và trả thưởng offline
• Repair known CMI and Mythic drop-table commands queued by older releases when their stripped target matches the joining player
• Sửa lệnh CMI và Mythic drop-table cũ trong hàng đợi khi tên đã bỏ tiền tố khớp người đăng nhập
• Repair shaded SQLite JDBC driver discovery and native loading
• Sửa việc tìm driver và tải thư viện native của SQLite JDBC trong file plugin đã đóng gói
• Bundle MySQL Connector/J 8.2.0 and merge both JDBC driver registrations for MySQL and SQLite
• Đóng gói MySQL Connector/J 8.2.0 và gộp đăng ký driver JDBC cho MySQL và SQLite
• Recheck MySQL index metadata when concurrent initializers create the same index
• Kiểm tra lại metadata chỉ mục MySQL khi nhiều tiến trình cùng tạo một chỉ mục
• Widen MySQL statistics player-name columns for Floodgate-prefixed gamertags
• Mở rộng cột tên người chơi trong thống kê MySQL cho gamertag có tiền tố Floodgate
• Write pending rewards in order after a one-tick debounce, preventing stale file snapshots
• Ghi thưởng chờ theo thứ tự sau một tick gộp thay đổi, tránh dữ liệu file cũ ghi đè

Updated APIs

Cập nhật API

• Add optional weighted or independent-chance random-loot entries within reward tiers
• Thêm random-loot tuỳ chọn theo trọng số hoặc tỉ lệ độc lập trong mỗi bậc thưởng
• Make base /slboss help available to all players while keeping admin actions permission-guarded
• Cho mọi người xem trợ giúp /slboss nhưng vẫn giữ quyền riêng cho lệnh quản trị
• Target Paper 1.21.11 / Java 21; compile against MythicMobs 5.13.0, PlaceholderAPI 2.12.3, and MMOItems 6.10.1-SNAPSHOT
• Chuyển sang Paper 1.21.11 / Java 21; biên dịch với MythicMobs 5.13.0, PlaceholderAPI 2.12.3 và MMOItems 6.10.1-SNAPSHOT

v3.0.0 (2026-02-27)

Added

Thêm mới

• SQLite/MySQL database for persistent player statistics
• Cơ sở dữ liệu SQLite/MySQL để lưu thống kê người chơi
• 11 tracked metrics across 7 period types (daily → all-time)
• 11 chỉ số theo dõi qua 7 loại kỳ (hàng ngày → toàn thời gian)
• /slboss stats [player] — view player statistics
• /slboss stats [player] — xem thống kê người chơi
• /slboss top <metric> [period] [boss] — leaderboard with tab completion
• /slboss top <metric> [period] [boss] — bảng xếp hạng có tab-complete
• Leaderboard & stats PlaceholderAPI expansions (with period support: daily, weekly, monthly, etc.)
• Placeholder PlaceholderAPI cho bảng xếp hạng & thống kê (hỗ trợ theo kỳ: ngày, tuần, tháng, v.v.)
• In-memory leaderboard cache with async refresh
• Bộ nhớ đệm bảng xếp hạng với làm mới bất đồng bộ
• Automatic period archival (daily, weekly, monthly, etc.)
• Tự động lưu trữ kỳ cũ (ngày, tuần, tháng, v.v.)
• Code architecture improvements: AbstractBossTracker, CommandValidator, ItemFactory
• Cải thiện kiến trúc code: AbstractBossTracker, CommandValidator, ItemFactory

Fixed

Sửa lỗi

• Reload-safe flag to suppress death-event processing during reload
• Cờ an toàn khi reload để bỏ qua sự kiện chết trong lúc reload
• Delayed state restore by 2 ticks to ensure worlds are loaded
• Trì hoãn khôi phục trạng thái 2 tick để đảm bảo thế giới đã tải
• Only send spawn success if boss actually spawned
• Chỉ gửi thông báo thành công nếu boss thực sự xuất hiện

v2.0.1 (2026-02-11)

Security

Bảo mật

• Drop table name sanitization to prevent command injection
• Khử độc tên bảng drop để ngăn chặn command injection
• Command validation to block shell metacharacters
• Xác thực lệnh để chặn metacharacter shell

Fixed

Sửa lỗi

• Duplicate stopTracking() calls, volatile bossScheduler, YAML parsing, forceSpawn reschedule
• Gọi stopTracking() trùng, volatile bossScheduler, phân tích YAML, lên lịch lại forceSpawn

v2.0.0 (2026-02-11)

Initial release with scheduled spawning, damage/tank/support tracking, tiered rewards, persistence, PlaceholderAPI, and multi-language support.

Bản phát hành đầu tiên với spawn theo lịch, theo dõi sát thương/chịu đòn/hỗ trợ, phần thưởng theo bậc, lưu trữ, PlaceholderAPI, và hỗ trợ đa ngôn ngữ.