Guardian | UClans Addon 1.0.1

This addon requires UltimateClans 9.0.0+ and EntityWizard

Documentation/Wiki

About:

Addon of: ⚔ Ultimate Clans ⚔ | Take your server to a higher level

Guardian adds configurable companions directly into UltimateClans, allowing clan members to summon their own Guardian to follow, protect, fight and support them throughout normal gameplay.

Each Guardian can have its own entity, role, rarity, combat behavior, stats, skills, equipment, progression, vitality, bond levels and evolutions. Guardians can grow together with the player and Clan instead of acting as simple cosmetic pets.

Players can choose different combat modes depending on how they want their Guardian to behave, while server owners can control which entities it may attack, where it can be used, how powerful it becomes and which Guardian types are available at each Clan level.

Guardian entities are handled through EntityWizard, allowing them to operate as lightweight companion entities while remaining integrated with UltimateClans systems.

This addon must be installed in the folder "/plugins/UltimateClans/addons/"

Features:

• Fully Configurable Guardians - Create and customize Guardian types with their own entity, name, unlock requirements, role, rarity, stats, skills, equipment, combat settings, effects and progression.
• Ready-to-Use Guardian Types - Includes several preconfigured Guardians that can be edited or used as examples:
  • Wolf
  • Zombie
  • Skeleton
  • Iron Golem
  • Spirit
• Guardian Roles - Guardians can be configured around different combat styles:
  • TANK
  • DAMAGE
  • RANGED
  • SUPPORT
  • HEALER
  • HYBRID
• Guardian Rarities - Assign rarity levels to different Guardian types:
  • COMMON
  • UNCOMMON
  • RARE
  • EPIC
  • LEGENDARY
  • MYTHIC
• Multiple Combat Modes - Players can dynamically control how their Guardian behaves:
  • PASSIVE - Follow the owner without actively engaging enemies.
  • DEFENSIVE - React to threats involving the owner.
  • AGGRESSIVE - Automatically search for configured targets around the owner.
  • GUARD - Hold a position and protect the surrounding area.
  • SUPPORT - Focus on support behavior and skills without normal aggressive targeting.
  • STAY - Remain at the selected position without following the owner.
• Smart Target System - Configure which categories the Guardian may attack:
  • Monsters
  • Animals
  • Players
  • Specific whitelisted mob types
• Real Mob Validation - Guardian combat ignores technical and decorative entities such as Armor Stands instead of treating every LivingEntity as a valid enemy.
• Clan Relation Awareness - Player targeting can respect UltimateClans relationships including Clan members, allies, rivals and neutral players.
• Target Priority - Configure which target categories should have priority when multiple enemies are available.
• Combat Distance Control - Configure target radius, leash distance, preferred combat distance, minimum distance and maximum distance for different Guardian styles.
• Natural Follow Movement - Guardians move toward their actual destination and face the direction they are traveling instead of simply copying the player's rotation.
• Custom Follow Position - Fine-tune Guardian positioning with:
  • Left or right side
  • Lateral distance
  • Forward or backward offset
  • Height
  • Movement speed
  • Teleport distance
• Ground & Flying Guardians - Guardian types can independently be configured as ground or flying entities. Ground Guardians remain on valid terrain even when their owner is flying.
• Guardian Level System - Guardians have their own progression independently from the Clan level.
• Configurable Maximum Levels - Each Guardian type can define its own maximum level and progression curve.
• Progression Points - Guardians can gain progression through activities such as:
  • Killing enemies
  • Healing
  • Feeding
• Clan Level Scaling - Attack and defense values can scale together with the owner's Clan level.
• Guardian Level Scaling - Stats can also increase independently as the Guardian itself levels up.
• Guardian Upgrade Points - Level progression can award points that players spend improving their Guardian.
• Upgradeable Stats - Upgrade categories include:
  • Attack
  • Defense
  • Vitality
  • Speed
  • Heal Power
• Bond System - Guardians can develop a separate Bond level with their owner.
• Bond Progression - Bond points can be earned through kills, healing, feeding and time spent active with the Guardian.
• Guardian Evolutions - Guardian types can unlock evolutions after reaching configured Guardian and Bond levels.
• Evolution Choices - Evolutions can use choice groups, allowing a Guardian to follow different progression paths instead of automatically receiving every evolution.
• Evolution Bonuses - Evolutions can modify Guardian statistics, appearance, equipment, entity behavior and other properties.
• Guardian Skill System - Skills are stored as independent configurable files and can define requirements, cooldowns, energy costs, upgrade levels and behavior.
• Skill Loadouts - Players can choose which available skills their Guardian has equipped.
• Skill Slots - Guardian types can define how many skills may be equipped, including additional slots unlocked through progression.
• Upgradeable Skills - Individual skills can have multiple levels, upgrade costs and scaling effects.
• Included Skills - The addon includes configurable examples such as:
  • Basic Attack
  • Ranged Attack
  • Heal
  • Clan Regeneration Aura
  • Last Stand
  • Power Strike
  • Item Collector
• Active, Passive, Aura & Reactive Skills - The skill engine supports different activation styles instead of limiting Guardians to simple attacks.
• Skill Conditions - Skills can react to combat situations and configured conditions such as owner health, targets and nearby enemies.
• Item Collector Skill - Guardians can optionally collect nearby dropped items into their own storage.
• Upgradeable Guardian Storage - The Item Collector skill can provide additional storage rows as the skill is upgraded.
• Guardian Health - Guardians can have their own configurable health pool instead of being permanently invulnerable companions.
• Guardian Energy - Skills, protection and combat behavior can use a dedicated Guardian energy system.
• Feeding System - Configure different food items to restore Guardian health and energy.
• Guardian Boost Food - Special food can temporarily improve attack, defense and healing effectiveness.
• Regeneration System - Guardians can regenerate health and energy after remaining outside combat for a configurable period.
• Defeat & Revive System - Guardians can become defeated and require revival instead of simply respawning with full strength.
• Configurable Revival - Configure revival item, cooldown, restored health percentage and restored energy percentage.
• Owner Protection - Guardian defense can reduce damage received by its owner while the Guardian is active.
• Configurable Player Equipment - Individual Guardian types can allow players to equip items directly onto their Guardian.
• Equipment Restrictions - Configure allowed slots, materials and equipment categories for each Guardian type.
• Equipment Stat Contribution - Equipped items can contribute configurable attack and defense bonuses to the Guardian.
• Default Guardian Equipment - Server owners can define built-in main hand, off hand, armor and equipment for individual Guardian types.
• Visual Customization - Configure properties such as baby state, glowing, invisibility, tame state, arms, base plate and Custom Model Data where applicable.
• Custom Guardian Names - Players can personalize their Guardian name, with configurable MiniMessage color support and name length limits.
• Custom Effects - Configure animations, particles and sounds for events such as:
  • Spawn
  • Attack
  • Hurt
  • Feed
  • Boost
  • Energy depletion
  • Level up
• Guardian HUD - Optional combat HUD can display Guardian information using ActionBar or BossBar.
• Guardian Indicator - Display configurable information above the Guardian including name, level, health and energy.
• Auto Spawn - Guardians can automatically return when their owner joins the server.
• Guardian GUI - Players can manage their Guardian through integrated graphical menus.
• Skills GUI - View available skills, equipped skills, levels and skill progression.
• Skill Tree GUI - Upgrade Guardian skills and manage progression visually.
• Equipment GUI - Manage supported Guardian equipment from an integrated interface.
• Storage GUI - Access storage provided by compatible Guardian skills such as Item Collector.
• World Restrictions - Enable or disable individual Guardian types in configured worlds.
• Region Restrictions - When an UltimateClans REGION extension such as WorldGuard is available, Guardians can be enabled or disabled in specific regions.
• Creative & Spectator Control - Individual Guardian types can automatically be disabled while players are in Creative or Spectator mode.
• Clan Territory Context - Guardian attack strength can use different multipliers inside own Clan land or rival Clan land.
• Clan War Context - Guardian behavior and attack multipliers can be adjusted during Clan Wars.
• Nexus Defense Context - Guardian combat can use a dedicated Nexus defense multiplier when the corresponding UltimateClans context is available.
• Clan Level Unlocks - Guardian types can require a specific Clan level before becoming available.
• Permission/VIP Unlocks - Individual Guardian types can require permissions or allow permissions to bypass their normal Clan level requirement.
• Guardian API - Developers can access profiles, states, active Guardians, skills, spawning, feeding, upgrades, evolutions and other Guardian systems.
• Custom Skill Registration API - External integrations can register additional Guardian skills and even new skill types.
• Guardian Events - API events are available for actions including spawn, despawn, damage, targeting, feeding, skills, level ups, bond progression, upgrades, evolution, defeat and revival.
• Guardian Placeholder Parser - The API exposes Guardian values such as name, type, role, rarity, level, health, energy, attack, defense, bond, evolution, skills and status for integrations.
• Persistent Guardian Data - Guardian progression, equipment, skill loadouts, evolutions and storage are saved between sessions.
• YAML Storage - Guardian player data is currently persisted using YAML storage.

Player Commands:

/clan guardian - Open the Guardian menu
/clan guardian spawn - Spawn your Guardian
/clan guardian despawn - Despawn your Guardian
/clan guardian mode <mode> - Change Guardian behavior
/clan guardian skills - Open the skill loadout
/clan guardian type <type> - Select a Guardian type
/clan guardian equip - Open Guardian equipment
/clan guardian feed - Feed your Guardian
/clan guardian boost - Use Guardian boost food
/clan guardian revive - Revive a defeated Guardian
/clan guardian info - View Guardian information
/clan guardian help - Show Guardian commands

Admin Commands:

/clan guardian reload - Reload Guardian settings

Guardian Modes:

PASSIVE - Follow the owner without normal combat targeting.
DEFENSIVE - React when the owner becomes involved in combat.
AGGRESSIVE - Automatically search for configured enemies around the owner.
GUARD - Remain around a fixed position and defend the surrounding area.
SUPPORT - Remain available for support behavior without normal aggressive targeting.
STAY - Stay at the selected location without following or normally attacking.

Default Guardian Types:

Wolf - Damage-oriented common Guardian.
Zombie - Tank-oriented uncommon Guardian.
Skeleton - Ranged rare Guardian.
Iron Golem - Tank-oriented epic Guardian.
Spirit - Flying support-oriented legendary Guardian.

Dependencies:

⚔ Ultimate Clans ⚔ | Take your server to a higher level - Required!

EntityWizard - Required!
A REGION extension such as WorldGuard - Optional, only required when Guardian region restrictions are configured.

Storage:

YAML - Guardian profiles, progression, equipment, skill loadouts, evolutions and skill storage are persisted automatically.

Guardian is designed to turn companions into a real part of Clan progression instead of simple cosmetic pets: fight with them, level them, build their skills, improve their stats, strengthen their bond and evolve them as the Clan grows.

Preview: