UltimateBlissSMP

** ---

Overview

Gem System is a comprehensive class-based power system plugin for Minecraft servers running Paper 1.21.1 - 1.21.11. It introduces a unique Gem System where each player possesses one of 8 distinct Gems, each granting unique passive abilities and active skills.

Key Features

| Feature | Description | |---------|-------------| | Highly Configurable | Each with 4 abilities and distinct playstyles | | Highly Configurable | Power fluctuates based on PvP performance | | Highly Configurable | Evolve your gem to unlock more abilities | | Highly Configurable | Upgraders, traders, repair items | | Highly Configurable | Particles, sounds, and glow effects | | Highly Configurable | Interactive menus for gem selection | | Highly Configurable | Uses PDC for reliable data storage | | Highly Configurable | Every value can be customized |

---

Core Concepts

How It Works

``` ┌─────────────────────────────────────────────────────────────┐ │ ULTIMATEBLISS FLOW │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Player Joins → Selects Gem → Uses Abilities → Gains Energy │ │ ↓ ↓ ↓ ↓ │ │ Load Data Open Menu Click Actions Kill Players │ │ ↓ ↓ ↓ │ │ Get Tier 1 Gem Cooldowns +1 Energy │ │ ↓ ↓ ↓ │ │ Upgrade Tier Deal Damage Power Up │ │ ↓ ↓ ↓ │ │ Unlock More Win Fights Max at 10 │ │ Abilities │ │ │ │ Death = -1 Energy → Broken at 0 → Repair at Pedestal │ └─────────────────────────────────────────────────────────────┘ ```

The Power Triangle

``` ┌──────────────┐ │ GEM TYPE │ │ (Abilities) │ └──────┬───────┘ │ ┌────────┴────────┐ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ TIER │ │ ENERGY │ │ (Unlocks & │ │ (Power Level │ │ Multiplier) │ │ & Effects) │ └──────────────┘ └──────────────┘ ```

---

The 8 Gems - Complete Guide

---

⚡ FLUX GEM *"Control electrical energy"*

Theme: Electricity, lightning, and kinetic energy

Icon: Yellow Icon: Lightning Rod

Passives

| Passive | Description | Requirements | |---------|-------------|--------------| | Shocking Chance | Speed and attack speed buffs that increase while running/fighting. Stacks up to 5 levels. Resets when you stop moving. | Always active | | Shocking Chance | Sneak + Left Click on a copper block within 20 blocks to teleport to it with lightning effects. | Sneaking near copper | | Shocking Chance | Complete immunity to Weakness, Slowness, and Hunger effects. | Always active | | Shocking Chance | 15% chance on arrow hit to stun enemy (no movement for 1 second). | Arrow hits |

Active Abilities

| Ability | Tier | Type | Description | Cooldown | |---------|------|------|-------------|----------| | Kinetic Burst | I | Instant | Spawns flash particles, applies Blindness and Nausea to enemies in radius. "Tastes like blue raspberry flavor." | 15s | | Kinetic Burst | I | Charged | Raytrace a damaging beam. Damage scales with charge %. When overcharged (100-200%), beam pierces through multiple entities. | 8s | | Kinetic Burst | II | Charged | Freezes target enemy (max slowness). When overcharged, also disables their jumping. | 20s | | Kinetic Burst | I | Instant | Radial knockback blast pushing all nearby enemies away with sonic boom effect. | 12s |

Charge Mechanic - Interrupted to charge (visualized on XP bar) - Interrupted = Normal charge (3 seconds) - Interrupted = Overcharge (additional 2 seconds, XP bar flashes) - Interrupted with F key (swap hands) or stop sneaking - Interrupted if you take damage or switch items

Controls | Action | Effect | |--------|--------| | Right Click (Hold) | Start charging | | F Key / Stop Sneaking | Release charge | | Shift + Right Click | Cycle ability selection | | Shift + Left Click | Conduction teleport | | Left Click | Cancel charge |

---

🔥 FIRE GEM *"Harness the power of flames"*

Theme: Fire, heat, and destruction

Color: Red

Icon: Blaze Powder

Passives

| Passive | Description | Requirements | |---------|-------------|--------------| | Burning Strikes | Permanent immunity to fire and lava damage. | Always active | | Burning Strikes | Leave fire particles behind when sprinting. | Sprinting | | Burning Strikes | Nearby enemies take small fire damage every 2 seconds and catch fire. 4 block radius. | Always active | | Burning Strikes | Melee attacks set targets on fire for 3 seconds. | Melee hits |

Active Abilities

| Ability | Tier | Type | Description | Cooldown | |---------|------|------|-------------|----------| | Inferno | I | Charged | Launch an explosive fireball. Size and damage scale with charge time. Sets area on fire. | 10s | | Inferno | I | Instant | Evaporate all water in a radius (5-11 blocks based on tier). Extra damage to water mobs (fish, squid, drowned). | 8s | | Inferno | II | Toggle | Surround yourself in flames. Damages all enemies within 3 blocks. Lasts 5-9 seconds. | 30s | | Inferno | III | Instant | Massive fire explosion. Sets ground on fire, huge damage and knockback to all nearby. | 45s |

Controls | Action | Effect | |--------|--------| | Right Click (Hold) | Charge Fireball | | F Key | Release Fireball | | Shift + Left Click | Crisp | | Shift + Right Click | Toggle Blaze Aura |

---

🗡️ ASTRA GEM *"Master of shadows and daggers"*

Theme: Stealth, assassination, and shadows

Color: Dark Purple

Icon: Amethyst Shard

Passives

| Passive | Description | Requirements | |---------|-------------|--------------| | Backstab | Permanent night vision effect. | Always active | | Backstab | While sneaking, mobs have 50% reduced chance to target you. Gain brief invisibility. | Sneaking | | Backstab | Deal 50% extra damage when attacking enemies from behind. | Attacking from behind |

Active Abilities

| Ability | Tier | Type | Description | Cooldown | |---------|------|------|-------------|----------| | Shadow Step | I | Instant | Throw a fast, no-gravity dagger projectile. Applies poison on hit (3 seconds). | 5s | | Shadow Step | I | Toggle | Become invisible. Breaks when you attack or take damage. Duration: 5-9s based on tier. | 25s | | Shadow Step | II | Toggle | Walk through solid blocks for 2-3 seconds. Teleports you through obstacles. | 15s | | Shadow Step | III | Targeted | Instantly teleport behind a target player within 15 blocks. Grants brief invisibility after. | 8s |

Controls | Action | Effect | |--------|--------| | Left Click | Throw Dagger | | Right Click | Toggle Invisibility | | Shift + Right Click | Activate Phase | | Shift + Left Click | Shadow Step to target |

---

💚 LIFE GEM *"Manipulate health and vitality"*

Theme: Healing, support, and vampirism

Color: Green

Icon: Glistering Melon Slice

Passives

| Passive | Description | Requirements | |---------|-------------|--------------| | Vitality | Enhanced health regeneration (0.5 hearts every 2 seconds). | Always active | | Vitality | See nearby players' health on action bar. Warns when allies are low. | Always active | | Vitality | Increased maximum health: +4/+8/+12 HP based on tier. | Always active |

Active Abilities

| Ability | Tier | Type | Description | Cooldown | |---------|------|------|-------------|----------| | Lifesteal Aura | I | Instant | Share 25% of your health with nearby allies. Visual beam connection. | 20s | | Lifesteal Aura | I | Toggle | Lock your health at current value for 5-7 seconds. Cannot go below locked amount. | 60s | | Lifesteal Aura | II | Instant | Apply powerful Regeneration (I-III based on tier) and Absorption for 5-7 seconds. | 30s | | Lifesteal Aura | III | Toggle | Steal 20% of damage dealt as healing. Lasts 10 seconds. | Varies |

Controls | Action | Effect | |--------|--------| | Right Click | Health Share | | Shift + Right Click | Toggle Heart Lock | | Shift + Left Click | Regeneration Burst | | Left Click | Toggle Lifesteal Aura (Tier 3) |

---

🌬️ PUFF GEM *"Master of air and mobility"*

Theme: Air, movement, and flight

Color: White

Icon: Feather

Passives

| Passive | Description | Requirements | |---------|-------------|--------------| | Glide | Complete immunity to fall damage. Soft landing particles. | Always active | | Glide | 40% reduced knockback received. | Always active | | Glide | While sneaking in air, slow falling with forward momentum. | Sneaking while airborne |

Active Abilities

| Ability | Tier | Type | Description | Cooldown | |---------|------|------|-------------|----------| | Tornado | I | Instant | Perform a second jump while in mid-air. Resets on landing. | 3s | | Tornado | I | Instant | Dash forward leaving a cloud trail. Damages enemies in path. | 10s | | Tornado | II | Instant | Launch yourself and nearby entities upward. Enemies take damage. | 15s | | Tornado | III | Sustained | Create a moving tornado that pulls, spins, and damages enemies for 5 seconds. | 45s |

Controls | Action | Effect | |--------|--------| | Right Click (in air) | Double Jump | | Right Click (on ground) | Cloud Dash | | Left Click | Updraft | | Shift + Left Click | Tornado (Tier 3) |

---

⚡ SPEED GEM *"Lightning fast reflexes"*

Theme: Speed, lightning, and time manipulation

Color: Aqua

Icon: Sugar

Passives

| Passive | Description | Requirements | |---------|-------------|--------------| | Momentum | Permanent Speed I-III based on tier. | Always active | | Momentum | Increased attack speed (Haste effect). | Always active | | Momentum | Speed increases while sprinting continuously. Stacks up to 5 levels. Bonus damage at max. | Continuous sprinting |

Active Abilities

| Ability | Tier | Type | Description | Cooldown | |---------|------|------|-------------|----------| | Time Slow | I | Targeted | Call down lightning at target location. Stuns and damages enemies. | 12s | | Time Slow | I | Instant | Temporary massive speed increase (Speed IV-VI) with Jump Boost. Lasts 5-9 seconds. | 20s | | Time Slow | II | Instant | Instant teleport in look direction (8-11 blocks). 2 charges, regenerate every 3 seconds. | Charge-based | | Time Slow | III | Area | Slow down time for all enemies within 10 blocks for 5 seconds. You gain speed during this. | 45s |

Controls | Action | Effect | |--------|--------| | Left Click | Lightning Strike | | Right Click | Dash | | Shift + Right Click | Speed Boost | | Shift + Left Click | Time Slow (Tier 3) |

---

💪 STRENGTH GEM *"Raw power and tracking"*

Theme: Brute force, hunting, and nullification

Color: Gold

Icon: Blaze Rod

Passives

| Passive | Description | Requirements | |---------|-------------|--------------| | Combo Damage | Permanent Strength I-III based on tier. | Always active | | Combo Damage | Attacks ignore 10-30% of enemy armor (based on tier). | Melee attacks | | Combo Damage | 30% increased knockback dealt to enemies. | Melee attacks | | Combo Damage | Consecutive hits increase damage. Resets when hit or after 3 seconds. | Continuous combat |

Active Abilities

| Ability | Tier | Type | Description | Cooldown | |---------|------|------|-------------|----------| | Iron Skin | I | Targeted | Track the nearest player with a compass. Shows distance and particle trail for 30 seconds. | 30s | | Iron Skin | I | Area | Remove all beneficial potion effects from enemies within 8-11 blocks. Applies brief Weakness. | 25s | | Iron Skin | II | Charged | Charge for 3 seconds, then your next hit deals massive bonus damage (15+) with huge knockback. Expires after 5 seconds if unused. | 15s | | Iron Skin | III | Toggle | 60% damage resistance + fire immunity for 5-7 seconds. Slight slowness applied. | 40s |

Controls | Action | Effect | |--------|--------| | Right Click | Start Power Strike charge | | Left Click | Release Power Strike (when charged) | | Shift + Left Click | Nullify | | Shift + Right Click | Bounty Tracker / Iron Skin |

---

💰 WEALTH GEM *"Virtual storage and protection"*

Theme: Fortune, storage, and item protection

Color: Yellow

Icon: Gold Ingot

Passives

| Passive | Description | Requirements | |---------|-------------|--------------| | Greed | 15-45% chance for double drops from ores and mobs (based on tier). Triple drops possible at Tier 3. | Breaking ores, killing mobs | | Greed | 20-60% chance to prevent durability loss on tools (based on tier). | Using tools | | Greed | 10-30% bonus XP from all sources (based on tier). | Collecting XP |

Active Abilities

| Ability | Tier | Type | Description | Cooldown | |---------|------|------|-------------|----------| | Midas Touch | I | Menu | Access a personal virtual inventory (9/18/27 slots based on tier). | None | | Midas Touch | I | Toggle | Lock items in your inventory slots (3/6/9 max based on tier). Locked items are kept on death. | 10s | | Midas Touch | II | Instant | Triple your fortune chance for 10-14 seconds. | 60s | | Midas Touch | III | Area | Convert nearby dropped items into gold for 5 seconds. Value based on item rarity. | Varies |

Controls | Action | Effect | |--------|--------| | Right Click | Open Virtual Pocket | | Left Click | Toggle Item Lock on held item | | Shift + Right Click | Fortune Boost (Tier 2) | | Shift + Left Click | Midas Touch (Tier 3) |

---

Energy System

Energy Scale

``` Energy State Effect Visual ────────────────────────────────────────────────── 10 Pristine +5 150% power GLOWING ✨ 9 Pristine +4 140% power GLOWING ✨ 8 Pristine +3 130% power 7 Pristine +2 120% power 6 Pristine +1 110% power 5 Pristine 100% power ← Starting 4 Scratched 90% power 3 Cracked 80% power 2 Shattered 70% power 1 Ruined 50% power ⚠️ Passives OFF 0 Broken 0% power ❌ ALL OFF ```

Energy Bar Visualization ``` [██████████] = 10 Energy (Pristine +5) [████████░░] = 8 Energy (Pristine +3) [█████░░░░░] = 5 Energy (Pristine) [███░░░░░░░] = 3 Energy (Cracked) [█░░░░░░░░░] = 1 Energy (Ruined) [░░░░░░░░░░] = 0 Energy (Broken) ```

Gaining & Losing Energy

| Action | Energy Change | |--------|---------------| | Kill a player | +1 | | Die to a player | -1 | | Use Reparation Shard | +1 | | Use Reparation Pedestal | +5 (costs diamonds) |

Broken State When energy reaches 0: - ❌ All abilities disabled - ❌ All passives disabled - ✅ No death ban - ✅ Can still play normally otherwise - 🔧 Must repair at Pedestal or use Reparation Shards

---

Tier System

Tier Comparison

| Aspect | Tier I (Apprentice) | Tier II (Adept) | Tier III (Master) | |--------|---------------------|-----------------|-------------------| | Symbol | 2 unlocked | 3 unlocked | 4 unlocked (all) | | Symbol | 1.0x | 1.25x | 1.5x | | Symbol | Gray | Aqua | Purple | | Symbol | [I] | [II] | [III] |

Upgrading Tiers

``` Tier I ──[Gem Upgrader]──> Tier II ──[Gem Polisher]──> Tier III ```

Combined Power Calculation ``` Final Power = Energy Multiplier × Tier Multiplier

Example (Max Power): Energy 10 (1.5x) × Tier III (1.5x) = 2.25x damage/effect power

Example (Low Power): Energy 3 (0.8x) × Tier I (1.0x) = 0.8x damage/effect power ```

---

Custom Items

Gem Upgrader ``` ┌─────────────────────────────────┐ │ ◆ Gem Upgrader │ │ Material: Amethyst Shard │ │ Function: Tier I → Tier II │ ├─────────────────────────────────┤ │ Recipe: │ │ D A D │ │ A E A D = Diamond │ │ D A D A = Amethyst Shard │ │ E = Emerald │ └─────────────────────────────────┘ ```

Gem Polisher ``` ┌─────────────────────────────────┐ │ ◆ Gem Polisher │ │ Material: Amethyst Cluster │ │ Function: Tier II → Tier III │ ├─────────────────────────────────┤ │ Recipe: │ │ N G N │ │ G E G N = Netherite Ingot │ │ N G N G = Gold Block │ │ E = End Crystal │ └─────────────────────────────────┘ ```

Gem Trader ``` ┌─────────────────────────────────┐ │ ◆ Gem Trader │ │ Material: Ender Eye │ │ Function: Reroll gem type │ │ Note: Keeps tier and energy! │ ├─────────────────────────────────┤ │ Recipe: │ │ E P E │ │ P N P E = Ender Eye │ │ E P E P = Ender Pearl │ │ N = Nether Star │ └─────────────────────────────────┘ ```

Reparation Shard ``` ┌─────────────────────────────────┐ │ ◆ Reparation Shard │ │ Material: Prismarine Shard │ │ Function: +1 Energy │ ├─────────────────────────────────┤ │ Recipe: │ │ . D . │ │ D P D D = Diamond │ │ . D . P = Prismarine Shard│ └─────────────────────────────────┘ ```

Reparation Pedestal ``` ┌─────────────────────────────────┐ │ ◆ Reparation Pedestal │ │ Material: Lodestone (placeable)│ │ Function: Full repair station │ │ Cost: 5 Diamonds per use │ │ Effect: +5 Energy │ │ Cooldown: 5 minutes │ ├─────────────────────────────────┤ │ Recipe: │ │ D E D │ │ E L E D = Diamond Block │ │ O O O E = Emerald Block │ │ L = Lodestone │ │ O = Obsidian │ └─────────────────────────────────┘ ```

---

Commands Reference

Player Commands

| Command | Aliases | Description | |---------|---------|-------------| | `/bliss` | `/ub`, `/gem`, `/gems` | Main command | | `/bliss help` | | Show help menu | | `/bliss info` | `/bliss status` | View your gem information | | `/bliss select` | `/bliss choose` | Select your initial gem (GUI) | | `/bliss trade` | | Trade your gem for another (GUI) | | `/bliss abilities` | `/bliss skills` | View your abilities list | | `/bliss energy` | | View detailed energy info |

Admin Commands

| Command | Description | Example | |---------|-------------|---------| | `/blissadmin give <player> <gem> [tier]` | Give a gem | `/ba give Steve FLUX 2` | | `/blissadmin remove <player>` | Remove gem | `/ba remove Steve` | | `/blissadmin settier <player> <1-3>` | Set tier | `/ba settier Steve 3` | | `/blissadmin setenergy <player> <0-10>` | Set energy | `/ba setenergy Steve 10` | | `/blissadmin repair <player>` | Repair to pristine | `/ba repair Steve` | | `/blissadmin giveitem <player> <item> [amount]` | Give custom item | `/ba giveitem Steve upgrader 5` | | `/blissadmin info <player>` | View player info | `/ba info Steve` | | `/blissadmin reload` | Reload configs | `/ba reload` |

Item Types for giveitem - `upgrader` - Gem Upgrader - `polisher` - Gem Polisher - `trader` - Gem Trader - `shard` / `repshard` - Reparation Shard - `pedestal` - Reparation Pedestal - `gemshard <gemtype>` - Gem Shard (gives that gem)

---

GUI Menus

Gem Selection Menu ``` ╔════════════════════════════════════════╗ ║ ✦ Select Your Gem ✦ ║ ╠════════════════════════════════════════╣ ║ [ASTRA] [FIRE] [FLUX] [LIFE] ║ ║ [PUFF] [SPEED][STRENGTH][WEALTH] ║ ║ ║ ║ [Random Gem] ║ ║ [Close] ║ ╚════════════════════════════════════════╝ ```

Gem Trader Menu ``` ╔════════════════════════════════════════╗ ║ ✦ Gem Trader ✦ ║ ╠════════════════════════════════════════╣ ║ Current: [Your Current Gem] ║ ║ ↓ ║ ║ TRADE ║ ║ ↓ ║ ║ [GEM] [GEM] [GEM] [GEM] [GEM] ║ ║ ║ ║ [Random Trade] [Close] ║ ╚════════════════════════════════════════╝ ```

Virtual Pocket (Wealth Gem) ``` ╔════════════════════════════════════════╗ ║ ✦ Virtual Pocket ✦ ║ ╠════════════════════════════════════════╣ ║ [Edit Mode] [INFO] [X] ║ ╠════════════════════════════════════════╣ ║ [Storage Slots - 9/18/27 based on tier]║ ║ [ ][ ][ ][ ][ ][ ][ ][ ][ ] ║ ║ [ ][ ][ ][ ][ ][ ][ ][ ][ ] ║ ║ [ ][ ][ ][ ][ ][ ][ ][ ][ ] ║ ╠════════════════════════════════════════╣ ║ [🔒 Locked Items Display] ║ ╚════════════════════════════════════════╝ ```

Shard Spin Animation When selecting a gem, an animated slot-machine style reveal plays: ``` ╔════════════════════════════════════════╗ ║ ✦ Gem Selection ✦ ║ ╠════════════════════════════════════════╣ ║ ▼ Selected ▼ ║ ║ [gem] [gem] [★ YOUR GEM ★] [gem] ║ ║ ║ ╚════════════════════════════════════════╝ ```

---

Configuration Guide

config.yml - Main Settings ```yaml settings: debug: false Enable debug messages save-interval: 300 Auto-save interval (seconds)

energy: default: 5 Starting energy min: 0 max: 10

effects: glow_at_max_energy: true Glowing at energy 9-10 particles_enabled: true Enable particle effects sounds_enabled: true Enable sound effects

gems: flux: enabled: true Enable/disable gems display_name: "&eFlux Gem" ... per-gem settings ```

cooldowns.yml - Ability Timers ```yaml global: ability_global_cooldown: 0.5 Minimum time between abilities

flux: flashbang: 15 flux_beam: 8 ground: 20 kinetic_burst: 12 charge_time: 3.0 overcharge_time: 2.0

fire: fireball: 10 crisp: 8 blaze_aura: 30 inferno: 45

... all gems ```

messages.yml - All Text ```yaml prefix: "&8[&bUltimateBliss&8] "

gem: received: "&aYou have received the {gem} &a!" changed: "&eYour gem has been changed to {gem}&e!" upgraded: "&aYour gem has been upgraded to Tier {tier}!"

energy: gained: "&a+1 Energy! ({current}/{max})" lost: "&c-1 Energy! ({current}/{max})" broken: "&c&lYour gem is BROKEN! Visit a Pedestal to repair it."

... all messages customizable ```

---

Permissions

Player Permissions

| Permission | Description | Default | |------------|-------------|---------| | `ultimatebliss.use` | Use gem abilities | true | | `ultimatebliss.command.info` | Use /bliss info | true | | `ultimatebliss.command.select` | Use /bliss select | true | | `ultimatebliss.command.trade` | Use /bliss trade | true |

Admin Permissions

| Permission | Description | Default | |------------|-------------|---------| | `ultimatebliss.admin` | All admin commands | op | | `ultimatebliss.admin.give` | Give gems to players | op | | `ultimatebliss.admin.remove` | Remove player gems | op | | `ultimatebliss.admin.reload` | Reload plugin | op |

Bypass Permissions

| Permission | Description | Default | |------------|-------------|---------| | `ultimatebliss.bypass.cooldown` | No ability cooldowns | op | | `ultimatebliss.bypass.energy` | Abilities work at 0 energy | op |

---

API Documentation

Getting Started ```java // Check if UltimateBliss is available if (BlissAPI.isAvailable()) { // Use the API }

// Get the plugin instance UltimateBliss plugin = BlissAPI.getPlugin(); ```

Player Data Operations ```java // Check if player has a gem boolean hasGem = BlissAPI.hasGem(player);

// Get player's gem type GemType type = BlissAPI.getGemType(player); // Returns null if no gem

// Get player's tier GemTier tier = BlissAPI.getGemTier(player);

// Get player's energy (0-10) int energy = BlissAPI.getEnergy(player);

// Get energy state enum EnergyState state = BlissAPI.getEnergyState(player); ```

Gem Management ```java // Give a gem BlissAPI.giveGem(player, GemType.FLUX); BlissAPI.giveGem(player, GemType.FIRE, GemTier.ADEPT);

// Remove a gem BlissAPI.removeGem(player);

// Change gem type (keeps tier) BlissAPI.changeGemType(player, GemType.ASTRA);

// Upgrade gem tier BlissAPI.upgradeGem(player); ```

Energy Management ```java // Set exact energy BlissAPI.setEnergy(player, 7);

// Add energy BlissAPI.addEnergy(player, 2);

// Repair to pristine (5) BlissAPI.repairGem(player); ```

Active Gem Instance ```java // Get the active gem instance for advanced operations Gem gem = BlissAPI.getActiveGem(player); if (gem != null) { // Access gem-specific methods if (gem instanceof FluxGem fluxGem) { boolean charging = fluxGem.isCharging(); } } ```

Events (Custom) You can listen to standard Bukkit events and check for gem involvement: ```java @EventHandler public void onDamage(EntityDamageByEntityEvent event) { if (event.getDamager() instanceof Player player) { Gem gem = BlissAPI.getActiveGem(player); if (gem != null && gem.getGemType() == GemType.STRENGTH) { // Player with Strength gem dealt damage } } } ```

---

Installation & Setup

Requirements - Paper 1.21.1 or higher - Java 21

Installation Steps

1. Download the latest `UltimateBliss.jar`

2. Place in your `plugins/` folder

3. Start your server (generates default configs)

4. Stop the server

5. Configure the files in `plugins/UltimateBliss/`: - `config.yml` - Main settings - `messages.yml` - Customize text - `cooldowns.yml` - Adjust timings - `recipes.yml` - Recipe settings

6. Start the server again

First-Time Setup Checklist - [ ] Review `config.yml` settings - [ ] Customize messages if desired - [ ] Test with `/bliss select` - [ ] Give yourself admin items: `/ba giveitem YourName upgrader 1` - [ ] Place a Reparation Pedestal for testing

Recommended Server Settings ```yaml In your server's spigot.yml or paper.yml Ensure good tick rates for smooth ability effects

paper-global.yml chunk-loading: player-max-chunk-load-rate: 100 ```

---

Gameplay Tips

For Players

Choosing Your Gem | Playstyle | Recommended Gem | |-----------|-----------------| | Aggressive PvP | Fire, Strength | | Assassin/Stealth | Astra | | Support/Team | Life | | Hit & Run | Speed, Puff | | Resource Gathering | Wealth | | Versatile | Flux |

Energy Management Tips - 🎯 Target weaker players to safely gain energy - 🛡️ Avoid fights when below 5 energy - 💎 Carry Reparation Shards for emergencies - 📍 Know where Reparation Pedestals are located - ⚠️ At energy 1-2, play very defensively

Combat Tips - Wealth: Charge behind cover, release when enemies approach - Wealth: Stay aggressive, your heat aura chips away at enemies - Wealth: Use invisibility to escape or set up backstabs - Wealth: Stay near teammates to share health - Wealth: Use mobility to kite melee attackers - Wealth: Build momentum before engaging - Wealth: Track targets, set up power strikes - Wealth: Focus on resources, avoid unnecessary fights

For Server Owners

Balancing Tips ```yaml If a gem seems too strong, adjust in cooldowns.yml: flux: flux_beam: 12 Increase from 8 to 12

If energy drain is too punishing: energy: default: 6 Start with extra energy

For hardcore servers: pedestal: repair_cost: 10 More diamonds needed ```

Event Ideas - Survival Games: Team battles based on gem types - Survival Games: Strength gems track targets - Survival Games: Wealth gems get bonus loot - Survival Games: Start at Tier 1, find upgraders

---

Troubleshooting

Common Issues

| Issue | Solution | |-------|----------| | Abilities not working | Check energy level (broken at 0) | | Can't select gem | Already have one? Use trade instead | | No particles | Check `effects.particles_enabled` in config | | Commands not found | Ensure plugin loaded: `/plugins` | | Recipes not working | `/ba giveitem` for manual giving |

Performance Tips - Particles run on paper async threads - Passive abilities only tick when needed - Reduce `save-interval` if seeing lag (less frequent saves)

Debug Mode Enable in `config.yml`: ```yaml settings: debug: true ``` This logs detailed ability usage and gem events.

---

Texture Pack

download here

---

Credits & Support

UltimateBliss - A comprehensive gem system for Minecraft servers.

API Version: 1.0.0 API Version: 1.21

---

*Thank you for using UltimateBliss! May your gems always shine bright.* ✨**