Wiki Release: 2026.09.5 · UltimateClans: 9.1.4 · Documentation branch: 9 · ClanGuardian

ClanGuardian#

ClanGuardian adds persistent clan guardian/pet system with configurable entity types, combat modes, equipment-derived stats, food/energy, boosts, skills, evolution, revive, HUD and optional shared clan guardians. The pages in this section explain what players see in-game, what administrators need to configure, the normal setup flow, and the most common problems you may need to diagnose.

Compatibility#

Component version: 1.0.0
Documentation release: 2026.09.5
Minimum UltimateClans version: 9.0.0
Additional requirement: ["EntityWizard"]

What you can do with it#

Open /clan guardian and choose an available guardian type
Spawn it with /clan guardian spawn; change behavior with /clan guardian mode <mode>
Use /clan guardian equip to manage equipment/stat contribution and /clan guardian skills to inspect/equip skills
Feed the guardian to maintain its configured resource/energy behavior, use boost food when available, and revive it after defeat with /clan guardian revive
Use /clan guardian info to check type, level, health, energy, mode, progression and equipped skills

How it works#

How Guardian progression works#

A Guardian is persistent clan/member companion data backed by Guardian profiles, type definitions, modes, equipment, energy/health, skills, upgrades, bond progression, rarity/evolution and revive state. Spawning creates the active entity representation; despawning removes that representation without deleting the saved Guardian profile.

The normal player flow is: open /clan guardian, select or unlock a Guardian type, spawn it, choose a combat mode, manage equipment/skills, then maintain it with feed/boost/revive actions. Types and skills are data-driven through guardians.yml and the individual files under skills/.

Combat modes#

The supplied implementation contains the modes PASSIVE, DEFENSIVE, AGGRESSIVE, GUARD, SUPPORT and STAY. Mode selection changes targeting/follow behavior; it does not replace the restrictions from worlds, regions, clan relations or type-specific movement. A ground-type Guardian should remain ground-bound even when its owner can fly.

Skills and equipment#

Skills are loaded from separate YAML definitions and can have triggers, conditions, cooldowns/effects and levels. The installed pack includes basic attack, ranged attack, power strike, heal, clan regeneration aura, item collector and last stand. Equipment contributes Guardian stats rather than merely changing appearance.

First setup#

Before enabling the feature for players, review these installed files:

commands.yml
config.yml
guardians.yml
gui.yml
languages/Lang_EN.yml
skills/basic_attack.yml
skills/clan_regeneration_aura.yml
skills/heal.yml
skills/item_collector.yml
skills/last_stand.yml
skills/power_strike.yml
skills/ranged_attack.yml

Recommended in-game workflow#

Open /clan guardian and choose an available guardian type.
Spawn it with /clan guardian spawn; change behavior with /clan guardian mode <mode>.
Use /clan guardian equip to manage equipment/stat contribution and /clan guardian skills to inspect/equip skills.
Feed the guardian to maintain its configured resource/energy behavior, use boost food when available, and revive it after defeat with /clan guardian revive.
Use /clan guardian info to check type, level, health, energy, mode, progression and equipped skills.

Useful command entry points#

/clan guardian
/clan guardian spawn
/clan guardian despawn
/clan guardian mode
/clan guardian skills
/clan guardian type
/clan guardian equip
/clan guardian feed
/clan guardian boost
/clan guardian revive
/clan guardian info
/clan guardian help
/clan guardian reload

See Commands in the sidebar for the full command reference and configured aliases/permissions.

GUI areas#

The installed GUI configuration contains screens/sections such as:

Guardian.home_main
Guardian.home_guardians
Guardian.home_upgrades
Guardian.home_skills
Guardian.home_skill_tree
Guardian.home_evolutions
Guardian.home_settings
Guardian.home_equipment
Guardian.home_storage

What administrators should configure#

Configure available types in guardians.yml and keep the default type in config.yml valid.
Tune follow side/distance/forward-offset/height and teleport distance before changing combat values.
Combat target radius, leash distance, defensive target duration and defense cap should be tested with hostile mobs and clan ally/rival rules.
Skills are definitions with triggers/conditions/cooldowns; change one dimension at a time and use debug skill failures while testing.
Shared guardians have separate enable/level/max/combat settings; do not assume player guardian settings automatically apply.

Configuration map#

config.yml — general (auto-spawn-on-join, tick-period, default-type, default-mode); follow (side, distance, forward-offset, height, speed-per-tick, teleport-distance); combat (target-radius, leash-distance, defensive-target-seconds, defense-enabled, max-defense-percent); debug (enabled, actionbar, console, interval-ms, skill-failures); hud (enabled, mode, only-in-combat, text); indicator (enabled, text); settings (name-max-length, name-allow-minimessage-colors); shared-guardian (enabled, default-type, follow-online-member, required-clan-level, max-per-clan, combat-enabled, damage-multiplier, attack-cooldown-ms, follow-distance)
guardians.yml — file-version; guardians (wolf, zombie, skeleton, iron_golem, spirit)

The Configuration page lists the available paths and defaults from the installed configuration, with notes on what each area controls.

Before going live#

Back up the component data/configuration.
Start the server and confirm the component is detected without startup errors.
Test with a non-OP player and the lowest clan role that should have access.
Exercise the complete flow once, including the failure/deny path, not only the happy path.
Restart the server and verify that persistent state survives.
If the network is multiserver, repeat the test from a second node and verify storage/synchronization.

Troubleshooting quick reference#

Symptom	Likely cause	What to check
Guardian does not spawn	Default/selected type unavailable, entity implementation failed to initialize, world/context is invalid or profile is defeated	Check `guardians.yml`, selected type, startup EntityWizard/entity integration logs and `/clan guardian info`.
Guardian follows but never attacks	PASSIVE/STAY/support behavior, target filtering, leash/radius or clan relationship rules prevent targeting	Switch to an attacking mode for the test, move a valid hostile target inside `combat.target-radius`, then inspect debug target/skill output.
Guardian teleports or moves awkwardly	Follow distance, forward offset, speed or teleport distance are too aggressive for the entity type	Return follow settings near defaults and tune one value at a time.
Skill never activates	Skill is not equipped, trigger/condition fails, cooldown/energy requirement is not met, or target is invalid	Enable `debug.skill-failures`, reproduce once and use the reported condition rather than lowering all limits blindly.
HUD shows wrong/stale values	HUD mode or update timing differs from the active guardian state	Check `hud.enabled`, mode/only-in-combat and reopen/respawn the guardian after config changes.
Shared clan guardian is absent	Feature disabled, clan level too low, max reached or no eligible online member can be followed	Check `shared-guardian.*`, clan level and online-member requirements.

For a longer diagnostic flow, open the Troubleshooting page for this component.