UltimateBlissSMP -----
A recreation of minecraft Bliss SMP feature into plugin.....## Overview
**UltimateBliss** is a comprehensive class-based power system plugin for Minecraft servers running Paper 1.21.1 - 1.21.8. 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 |
|---------|-------------|
| **8 Unique Gems** | Each with 4 abilities and distinct playstyles |
| **Dynamic Energy System** | Power fluctuates based on PvP performance |
| **3-Tier Progression** | Evolve your gem to unlock more abilities |
| **Custom Items** | Upgraders, traders, repair items |
| **Visual Effects** | Particles, sounds, and glow effects |
| **Full GUI System** | Interactive menus for gem selection |
| **Persistent Data** | 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
**Color:** Yellow (#FFFF55)
**Icon:** Lightning Rod
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Flow State** | Speed and attack speed buffs that increase while running/fighting. Stacks up to 5 levels. Resets when you stop moving. | Always active |
| **Conduction** | Sneak + Left Click on a copper block within 20 blocks to teleport to it with lightning effects. | Sneaking near copper |
| **Tireless** | 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 |
|---------|------|------|-------------|----------|
| **Flashbang** | I | Instant | Spawns flash particles, applies Blindness and Nausea to enemies in radius. "Tastes like blue raspberry flavor." | 15s |
| **Flux Beam** | I | Charged | Raytrace a damaging beam. Damage scales with charge %. When overcharged (100-200%), beam pierces through multiple entities. | 8s |
| **Ground** | 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
- **Hold Right Click** to charge (visualized on XP bar)
- **0-100%** = Normal charge (3 seconds)
- **100-200%** = Overcharge (additional 2 seconds, XP bar flashes)
- **Release** 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 (#FF5555)
**Icon:** Blaze Powder
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Fire Resistance** | Permanent immunity to fire and lava damage. | Always active |
| **Ember Trail** | Leave fire particles behind when sprinting. | Sprinting |
| **Heat Aura** | 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 |
|---------|------|------|-------------|----------|
| **Fireball** | I | Charged | Launch an explosive fireball. Size and damage scale with charge time. Sets area on fire. | 10s |
| **Crisp** | I | Instant | Evaporate all water in a radius (5-11 blocks based on tier). Extra damage to water mobs (fish, squid, drowned). | 8s |
| **Blaze Aura** | 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 (#AA00AA)
**Icon:** Amethyst Shard
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Night Vision** | Permanent night vision effect. | Always active |
| **Shadow Cloak** | 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 |
|---------|------|------|-------------|----------|
| **Dagger Throw** | I | Instant | Throw a fast, no-gravity dagger projectile. Applies poison on hit (3 seconds). | 5s |
| **Invisibility** | I | Toggle | Become invisible. Breaks when you attack or take damage. Duration: 5-9s based on tier. | 25s |
| **Phase** | 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 (#55FF55)
**Icon:** Glistering Melon Slice
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Natural Regeneration** | Enhanced health regeneration (0.5 hearts every 2 seconds). | Always active |
| **Life Sense** | 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 |
|---------|------|------|-------------|----------|
| **Health Share** | I | Instant | Share 25% of your health with nearby allies. Visual beam connection. | 20s |
| **Heart Lock** | I | Toggle | Lock your health at current value for 5-7 seconds. Cannot go below locked amount. | 60s |
| **Regeneration Burst** | 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 (#FFFFFF)
**Icon:** Feather
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Feather Fall** | Complete immunity to fall damage. Soft landing particles. | Always active |
| **Air Cushion** | 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 |
|---------|------|------|-------------|----------|
| **Double Jump** | I | Instant | Perform a second jump while in mid-air. Resets on landing. | 3s |
| **Cloud Dash** | I | Instant | Dash forward leaving a cloud trail. Damages enemies in path. | 10s |
| **Updraft** | 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 (#55FFFF)
**Icon:** Sugar
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Swift** | Permanent Speed I-III based on tier. | Always active |
| **Quick Reflexes** | 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 |
|---------|------|------|-------------|----------|
| **Lightning Strike** | I | Targeted | Call down lightning at target location. Stuns and damages enemies. | 12s |
| **Speed Boost** | I | Instant | Temporary massive speed increase (Speed IV-VI) with Jump Boost. Lasts 5-9 seconds. | 20s |
| **Dash** | 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 (#FFAA00)
**Icon:** Blaze Rod
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Titan** | Permanent Strength I-III based on tier. | Always active |
| **Armor Piercing** | Attacks ignore 10-30% of enemy armor (based on tier). | Melee attacks |
| **Heavy Hitter** | 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 |
|---------|------|------|-------------|----------|
| **Bounty Tracker** | I | Targeted | Track the nearest player with a compass. Shows distance and particle trail for 30 seconds. | 30s |
| **Nullify** | I | Area | Remove all beneficial potion effects from enemies within 8-11 blocks. Applies brief Weakness. | 25s |
| **Power Strike** | 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 (#FFFF55)
**Icon:** Gold Ingot
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Fortune** | 15-45% chance for double drops from ores and mobs (based on tier). Triple drops possible at Tier 3. | Breaking ores, killing mobs |
| **Miser** | 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 |
|---------|------|------|-------------|----------|
| **Virtual Pocket** | I | Menu | Access a personal virtual inventory (9/18/27 slots based on tier). | None |
| **Item Lock** | I | Toggle | Lock items in your inventory slots (3/6/9 max based on tier). Locked items are kept on death. | 10s |
| **Fortune Boost** | 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) |
|--------|---------------------|-----------------|-------------------|
| **Abilities** | 2 unlocked | 3 unlocked | 4 unlocked (all) |
| **Damage Multiplier** | 1.0x | 1.25x | 1.5x |
| **Color** | Gray | Aqua | Purple |
| **Symbol** | | [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
- **Flux:** Charge behind cover, release when enemies approach
- **Fire:** Stay aggressive, your heat aura chips away at enemies
- **Astra:** Use invisibility to escape or set up backstabs
- **Life:** Stay near teammates to share health
- **Puff:** Use mobility to kite melee attackers
- **Speed:** Build momentum before engaging
- **Strength:** 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
- **Gem Wars:** Team battles based on gem types
- **Bounty Hunts:** Strength gems track targets
- **Treasure Hunt:** 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.
---
## Credits & Support
**UltimateBliss** - A comprehensive gem system for Minecraft servers.
**Version:** 1.0.0
**API Version:** 1.21
---
*Thank you for using UltimateBliss! May your gems always shine bright.* ✨
**UltimateBliss** is a comprehensive class-based power system plugin for Minecraft servers running Paper 1.21.1 - 1.21.8. 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 |
|---------|-------------|
| **8 Unique Gems** | Each with 4 abilities and distinct playstyles |
| **Dynamic Energy System** | Power fluctuates based on PvP performance |
| **3-Tier Progression** | Evolve your gem to unlock more abilities |
| **Custom Items** | Upgraders, traders, repair items |
| **Visual Effects** | Particles, sounds, and glow effects |
| **Full GUI System** | Interactive menus for gem selection |
| **Persistent Data** | 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
**Color:** Yellow (#FFFF55)
**Icon:** Lightning Rod
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Flow State** | Speed and attack speed buffs that increase while running/fighting. Stacks up to 5 levels. Resets when you stop moving. | Always active |
| **Conduction** | Sneak + Left Click on a copper block within 20 blocks to teleport to it with lightning effects. | Sneaking near copper |
| **Tireless** | 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 |
|---------|------|------|-------------|----------|
| **Flashbang** | I | Instant | Spawns flash particles, applies Blindness and Nausea to enemies in radius. "Tastes like blue raspberry flavor." | 15s |
| **Flux Beam** | I | Charged | Raytrace a damaging beam. Damage scales with charge %. When overcharged (100-200%), beam pierces through multiple entities. | 8s |
| **Ground** | 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
- **Hold Right Click** to charge (visualized on XP bar)
- **0-100%** = Normal charge (3 seconds)
- **100-200%** = Overcharge (additional 2 seconds, XP bar flashes)
- **Release** 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 (#FF5555)
**Icon:** Blaze Powder
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Fire Resistance** | Permanent immunity to fire and lava damage. | Always active |
| **Ember Trail** | Leave fire particles behind when sprinting. | Sprinting |
| **Heat Aura** | 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 |
|---------|------|------|-------------|----------|
| **Fireball** | I | Charged | Launch an explosive fireball. Size and damage scale with charge time. Sets area on fire. | 10s |
| **Crisp** | I | Instant | Evaporate all water in a radius (5-11 blocks based on tier). Extra damage to water mobs (fish, squid, drowned). | 8s |
| **Blaze Aura** | 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 (#AA00AA)
**Icon:** Amethyst Shard
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Night Vision** | Permanent night vision effect. | Always active |
| **Shadow Cloak** | 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 |
|---------|------|------|-------------|----------|
| **Dagger Throw** | I | Instant | Throw a fast, no-gravity dagger projectile. Applies poison on hit (3 seconds). | 5s |
| **Invisibility** | I | Toggle | Become invisible. Breaks when you attack or take damage. Duration: 5-9s based on tier. | 25s |
| **Phase** | 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 (#55FF55)
**Icon:** Glistering Melon Slice
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Natural Regeneration** | Enhanced health regeneration (0.5 hearts every 2 seconds). | Always active |
| **Life Sense** | 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 |
|---------|------|------|-------------|----------|
| **Health Share** | I | Instant | Share 25% of your health with nearby allies. Visual beam connection. | 20s |
| **Heart Lock** | I | Toggle | Lock your health at current value for 5-7 seconds. Cannot go below locked amount. | 60s |
| **Regeneration Burst** | 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 (#FFFFFF)
**Icon:** Feather
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Feather Fall** | Complete immunity to fall damage. Soft landing particles. | Always active |
| **Air Cushion** | 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 |
|---------|------|------|-------------|----------|
| **Double Jump** | I | Instant | Perform a second jump while in mid-air. Resets on landing. | 3s |
| **Cloud Dash** | I | Instant | Dash forward leaving a cloud trail. Damages enemies in path. | 10s |
| **Updraft** | 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 (#55FFFF)
**Icon:** Sugar
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Swift** | Permanent Speed I-III based on tier. | Always active |
| **Quick Reflexes** | 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 |
|---------|------|------|-------------|----------|
| **Lightning Strike** | I | Targeted | Call down lightning at target location. Stuns and damages enemies. | 12s |
| **Speed Boost** | I | Instant | Temporary massive speed increase (Speed IV-VI) with Jump Boost. Lasts 5-9 seconds. | 20s |
| **Dash** | 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 (#FFAA00)
**Icon:** Blaze Rod
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Titan** | Permanent Strength I-III based on tier. | Always active |
| **Armor Piercing** | Attacks ignore 10-30% of enemy armor (based on tier). | Melee attacks |
| **Heavy Hitter** | 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 |
|---------|------|------|-------------|----------|
| **Bounty Tracker** | I | Targeted | Track the nearest player with a compass. Shows distance and particle trail for 30 seconds. | 30s |
| **Nullify** | I | Area | Remove all beneficial potion effects from enemies within 8-11 blocks. Applies brief Weakness. | 25s |
| **Power Strike** | 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 (#FFFF55)
**Icon:** Gold Ingot
#### Passives
| Passive | Description | Requirements |
|---------|-------------|--------------|
| **Fortune** | 15-45% chance for double drops from ores and mobs (based on tier). Triple drops possible at Tier 3. | Breaking ores, killing mobs |
| **Miser** | 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 |
|---------|------|------|-------------|----------|
| **Virtual Pocket** | I | Menu | Access a personal virtual inventory (9/18/27 slots based on tier). | None |
| **Item Lock** | I | Toggle | Lock items in your inventory slots (3/6/9 max based on tier). Locked items are kept on death. | 10s |
| **Fortune Boost** | 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) |
|--------|---------------------|-----------------|-------------------|
| **Abilities** | 2 unlocked | 3 unlocked | 4 unlocked (all) |
| **Damage Multiplier** | 1.0x | 1.25x | 1.5x |
| **Color** | Gray | Aqua | Purple |
| **Symbol** | | [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
- **Flux:** Charge behind cover, release when enemies approach
- **Fire:** Stay aggressive, your heat aura chips away at enemies
- **Astra:** Use invisibility to escape or set up backstabs
- **Life:** Stay near teammates to share health
- **Puff:** Use mobility to kite melee attackers
- **Speed:** Build momentum before engaging
- **Strength:** 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
- **Gem Wars:** Team battles based on gem types
- **Bounty Hunts:** Strength gems track targets
- **Treasure Hunt:** 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.
---
## Credits & Support
**UltimateBliss** - A comprehensive gem system for Minecraft servers.
**Version:** 1.0.0
**API Version:** 1.21
---
*Thank you for using UltimateBliss! May your gems always shine bright.* ✨
Resource Information
Author:
----------
Total Downloads:
208
First Release:
Dec 21, 2025
Last Update:
Jan 18, 2026
Category:
---------------
All-Time Rating:
0 ratings
Version
-----
Released:
--------------------
Downloads:
------
Version Rating:
----------------------
-- ratings