☢️ UltOrbitals

High-performance orbital strike system for Paper & Folia 1.21+

Massive configurable orbital weapons • Admin GUI • Public Developer API • Folia Compatible

---

📖 Overview

UltOrbitals gives players fishing rods that function as orbital strike weapons. Right-clicking aims at your crosshair target (up to the configured max range), and after the required number of pulls the payload drops from the sky. Every rod is single-use — it breaks immediately on firing.

Six weapon types are included out of the box:

Weapon	Description
Nuke	Concentric rings of TNT raining from above
Stab	A vertical pillar of explosions descending from max height
Bomb	One massive central crater with scatter blasts
Dog Cannon	Armored, buffed wolf pack deployed at the target
Chunk Eater	Clears away the whole chunk up to bedrock level
Wither Cannon	Charged wither skulls launched from the sky in a ring pattern

---

📸 Preview

---

✨ Features

• ☢️ Six unique orbital weapons
• 🎣 Fishing-rod-based targeting
• ⚙️ Fully configurable per-weapon parameters
• 📦 Configurable recipe system
• 🖥️ Full admin dashboard GUI
• 👥 Per-player inventory management
• 🌍 World allow-list restrictions
• 🧢 World-wide simultaneous-strike cap
• 🔄 Live configuration editing (/orbital reload)
• 🚀 Paper + Folia support
• 🧩 Public Developer API for other plugins

---

⚡ Installation

1. Drop UltOrbitals-1.0.0.jar into your plugins/ folder.
2. Start or restart the server.
3. Edit plugins/UltOrbitals/config.yml to taste.
4. Run /orbital reload to apply changes without restart.

Requirements: Paper or Folia 1.21.x, Java 21.

---

🎮 Commands

Player Commands — /orbital

Command	Permission	Description
/orbital nuke [amount]	ultorbitals.nuke	Give yourself nuke rod(s)
/orbital stab [amount]	ultorbitals.stab	Give yourself stab rod(s)
/orbital bomb [amount]	ultorbitals.bomb	Give yourself bomb rod(s)
/orbital dogs [amount]	ultorbitals.dogs	Give yourself dog cannon rod(s)
/orbital chunk [amount]	ultorbitals.chunk	Give yourself chunk eater rod(s)
/orbital wither [amount]	ultorbitals.wither	Give yourself wither cannon rod(s)
/orbital give <player> <type> [amount]	ultorbitals.give	Give a weapon to another player
/orbital remove <player> <type> [amount]	ultorbitals.remove	Remove weapons from a player
/orbital reload	ultorbitals.reload	Reload config.yml live
/orbital disable	ultorbitals.disable	Toggle global orbital disable
/orbital gui [player]	ultorbitals.admin.gui	Open admin player GUI
/orbital recipe	ultorbitals.recipe	Open recipe gui

Admin Commands — /orbitala

Command	Permission	Description
/orbitala	ultorbitals.admin	Open the admin dashboard GUI
/orbitala dashboard	ultorbitals.admin	Open the admin dashboard GUI
/orbitala cap [on|off]	ultorbitals.admin	View or toggle the world-wide strike cap
/orbitala capset <number>	ultorbitals.admin	Set the maximum simultaneous active strikes
/orbitala capreset	ultorbitals.admin	Reset the active strike counter to 0
/orbitala weapon <type> <key> <value>	ultorbitals.admin	Edit any weapon parameter live
/orbitala track [player]	ultorbitals.admin	Print a player's current orbital inventory

Weapon editor example:

/orbitala weapon nuke rings 8
/orbitala weapon nuke tnt-per-ring-base 60
/orbitala weapon wither count 10
/orbitala weapon stab explosion-power 6

---

🔑 Permissions

Node	Default	Description
ultorbitals.use	OP	Base usage permission (covers all weapons)
ultorbitals.nuke	OP	Nuke weapon
ultorbitals.stab	OP	Stab weapon
ultorbitals.bomb	OP	Bomb weapon
ultorbitals.dogs	OP	Dog Cannon
ultorbitals.chunk	OP	Chunk Eater
ultorbitals.wither	OP	Wither Cannon
ultorbitals.give	OP	Give weapons to others
ultorbitals.remove	OP	Remove weapons from others
ultorbitals.reload	OP	Reload config
ultorbitals.disable	OP	Toggle global disable
ultorbitals.admin	OP	Full admin access (GUI + cap + weapon editor)
ultorbitals.admin.gui	OP	Open admin GUI only
ultorbitals.recipe	Default	Open recipe GUI

---

🖥️ Admin GUI

Open with /orbitala or /orbitala dashboard.

Dashboard (54-slot inventory):

• Beacon (slot 5) — shows global status; click to toggle global disable
• Barrier (slot 9) — shows cap status; click to toggle cap on/off
• Redstone (slot 8) — click to reset active strike counter
• Player heads (rows 3–6) — one head per online player; shows their orbital counts; click to manage

Player GUI (per-player, 54-slot):

• One fishing rod icon per weapon type showing current count in inventory
• Left-click → give +1 to player
• Right-click → remove 1 from player
• Shift+Left → give +5
• Shift+Right → remove all of that type
• Arrow (slot 46) → back to dashboard
• Lava bucket (slot 54) → remove ALL orbitals from player

---

⚙️ World-Wide Cap

The cap prevents more than N orbital strikes from being active at the same time across the entire server. By default it is disabled.

Enable and configure in config.yml:

global:
  cap:
    enabled: true
    max: 1

Or use commands:

/orbitala cap on
/orbitala capset 1

When the cap is reached, players see the cap_reached message and their rod is not consumed. Admins can force-reset the counter with /orbitala capreset if strikes get stuck.

---

🧪 Crafting Recipes

All recipes are configurable in config.yml under recipes:. Each weapon has its own 3×3 shaped recipe. Set recipes.enabled: false to disable all custom recipes. Disable individual weapons with recipes.<type>.enabled: false.

Default recipes:

Weapon	Pattern	Key Materials
Nuke	TNT ring + Netherite center	TNT, Netherite Ingot, Soul Sand, Redstone Block, Fishing Rod
Stab	Diamond ring	Diamond, Stick, Fishing Rod
Bomb	Gunpowder ring	Gunpowder, Fishing Rod
Dog Cannon	Bone ring	Bone, Fishing Rod
Chunk Eater	Obsidian ring	Obsidian, Fishing Rod
Wither Cannon	Wither Skull ring	Wither Skeleton Skull, Fishing Rod

All recipes can be freely redesigned in config. Reload with /orbital reload.

---

🔧 Configuration Reference

The single config.yml file controls everything. Key sections:

global

• disabled — master on/off (also toggled by /orbital disable)

• allowed-worlds — whitelist of world names (empty = all worlds)

• cap.enabled — world-wide active strike cap toggle

• cap.max — max simultaneous active strikes

  cooldowns Per-weapon cooldown in seconds per player. 0 = no cooldown.

  messages Every player-facing string. Supports & color codes. Available placeholders:

• %weapon% — weapon display name

• %amount% — quantity

• %player% — target player name

• %sender% — command sender name

• %time% — cooldown seconds remaining

• %weapons% — comma-separated list of valid weapon types

  weapons.<type> Per-weapon tuning. All values are live-editable via /orbitala weapon or by editing config and running /orbital reload.

  recipes See crafting section above. Shapes use 3 rows × 3 chars. Ingredient map = character: MATERIAL_NAME.

---

🧩 Developer API

UltOrbitals exposes a full public API through UltOrbitalsAPI, so other plugins can build, give, track, and trigger orbital weapons programmatically.

Getting the API instance

UltOrbitalsAPI api = UltOrbitalsAPI.get();

Maven dependency

<dependency>
    <groupId>me.ultorbitals</groupId>
    <artifactId>UltOrbitals</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

Add UltOrbitals as a depend (or softdepend) in your plugin's plugin.yml:

depend: [UltOrbitals]

Building weapon items

ItemStack nuke = api.buildOrbital("nuke");

Supported types: nuke, stab, bomb, dogs, chunk, wither

Giving weapons

api.giveOrbital(player, "nuke", 3);

Removing weapons

int removed = api.removeOrbital(player, "bomb", 2);

Counting weapons

int amount = api.getOrbitalCount(player, "nuke");

Getting all orbitals a player holds

Map<String, Integer> orbitals = api.getAllOrbitals(player);
// e.g. { "nuke": 3, "bomb": 5, "dogs": 1 }

Detecting orbital items

if (api.isOrbital(item)) {
    String type = api.getOrbitalType(item);
}

Triggering a strike

Respects the world-wide cap and global disable toggle.

boolean scheduled = api.triggerStrike("nuke", player.getLocation(), player);

Returns false if the strike cap is reached, the weapon type is invalid, or orbitals are globally disabled.

Forcing a strike

Bypasses the strike cap (still fires even if the cap would normally block it).

api.forceStrike("wither", player.getLocation(), player);

Reading live weapon configuration

Lets other plugins read the same tunable values the admin GUI edits.

int rings          = api.getWeaponInt("nuke", "rings", 5);
double power       = api.getWeaponDouble("nuke", "explosion-power", 10.0);
boolean charged    = api.getWeaponBool("wither", "charged", true);
String particle    = api.getWeaponStr("nuke", "particles", "flame");

Strike cap controls

int active   = api.getActiveStrikes();
int cap      = api.getGlobalCap();
api.setGlobalCap(5);
api.resetActiveStrikes();

Global enable/disable

boolean disabled = api.isDisabled();
api.setDisabled(true);

Listing supported weapon types

List<String> types = api.getAllTypes();
// [nuke, stab, bomb, dogs, chunk, wither]

---

🏗️ Architecture

UltOrbitals
├── Weapons
│   ├── Nuke
│   ├── Bomb
│   ├── Stab
│   ├── Dogs
│   ├── Chunk
│   └── Wither
│
├── Commands
├── GUI
├── Recipes
├── Cooldowns
├── Config
├── API
└── Managers

Build requirements: Maven 3.8+ and JDK 21+.

---

❓ FAQ

Q: Rods don't break on one use?
A: Make sure pulls-required is set to 2 (default). The first pull primes the weapon, the second fires and breaks it.

Q: Cap counter stuck after server crash?
A: Run /orbitala capreset to reset the active counter to 0.

Q: How do I make a weapon free-craft for all players?
A: Grant ultorbitals.<type> to the default group in your permissions plugin. The crafting recipe will work for anyone with that permission.

Q: Recipe conflicts with another plugin?
A: Set recipes.<type>.enabled: false for the conflicting weapon and define it in that plugin instead.

Q: Can other plugins hook into UltOrbitals? A: Yes — see the Developer API section above. Add depend: [UltOrbitals] to your plugin.yml and call UltOrbitalsAPI.get().

---

📜 License

UltOrbitals is released under a GNU Affero General Public License.

Built on the OrbitalStrikeCannon mechanism. Expanded with wither cannon, admin GUI, world cap, recipe system, full config control, and a public developer API.