EnderDragonCompanion

EnderDragonCompanion

A Paper 1.21.10 plugin: Hatch your own Ender Dragon companion that follows you like a tamed wolf, fights alongside you, breathes dragon's breath, and can be ridden in flight once mature.

I. Gameplay Overview

Stage	Description
Hatching	Right-click a placed Dragon Egg block to spawn a baby Ender Dragon
Baby Stage	Follows/wanders/sits like a tamed wolf, automatically attacks the target the owner is attacking, and retaliates when attacked; defaults to maturing in 20 minutes
Adult	Scale resets to 1.0, can be ridden for flight and breathe dragon's breath
Daily Growth	Each in-game day: health +1 (no cap by default), attack damage +0.2 (capped at 100)

II. Core Mechanics

1. Invisible Wolf AI Brain

Each dragon is bound to an invisible, silent tamed wolf that serves as its "AI brain":

• The dragon makes no AI decisions of its own. Instead, every tick it teleports to hover above the wolf (3 blocks above for babies, 6 for adults), creating the visual effect of the wolf following/wandering/sitting.
• The wolf inherits all vanilla tamed wolf behaviors: following the owner, wandering nearby, staying put when sitting, and targeting whatever the owner targets (wolf.getTarget()).
• The wolf's attack damage is synced in real-time to the dragon's growth-based attack damage. When the wolf bites a target, it deals damage (kill credit goes to the wolf's owner; drops go to the owner).
• The wolf self-checks every 5 seconds: only one wolf is allowed per dragon; extras (from anomalies or duplicates) are automatically cleaned up, and the wolf will not touch wolves bound to other players' dragons.
• If the wolf is unexpectedly lost, it automatically respawns beside the dragon and re-binds (PDC records are updated accordingly).

2. Dragon Combat (Assisted Fighting)

• Targets are chosen entirely by vanilla wolf AI: when the owner attacks something, the wolf attacks it; when the dragon is hit, the wolf retaliates against the attacker.
• The dragon lunges at targets within horizontal distance, ramming them to deal growth-based damage + knockback, accompanied by a roar sound.
• Attack range and cooldown differ between baby and adult dragons (see configuration).
• Dragon's breath (see below) is only triggered by the player's left-click while riding.

3. Growth System

• Health: Starts at 1 upon hatching, +1 per in-game day, no cap (internal上限 raised to 1,000,000).
• Attack Damage: Starts at 1 upon hatching, +0.2 per in-game day, capped at 100.
• The owner receives a notification each day-crossing showing current health and attack damage.
• Baby growth timer is based on hatching time (survives server restarts via PDC records). On maturity, the dragon's scale resets and a "can now be ridden" message is shown.

4. Mounted Flight

• Mounting: After maturity, right-click with a Dragon Whistle (air or dragon) to mount (must be within 32 blocks).
• Controls:
  • W/S/Left/Right: Move forward/backward/strafe
  • Spacebar: Ascend
  • Left-click: Breathe dragon's breath
  • Sneak: Dismount
• Dragon's Breath: Spawns 20 moving dragon's breath clouds in front of the dragon's head, covering approximately 50 blocks. Clouds persist for about 4 seconds along their path. All entities within range take damage every 0.2 seconds (damage configured via ride.breath-damage). The dragon itself, the owner, the rider, and allied wolves/dragons are immune. Whether other players take damage is configurable.
• Ride Protection: While mounted, the rider is immune to environmental damage (suffocation, fall, fire, lava, drowning, wall collision, contact damage) — the dragon flies with no physical collision so the rider is unharmed.

5. Sit / Stand (Stop Following)

Either of the following toggles sit/stand:

• Right-click the dragon while holding a Dragon Whip, or right-click air (applies to your own dragon).

When sitting, the dragon (and its invisible wolf) stays in place and stops following the owner.

6. Death & Drops

• When the dragon dies, its bound invisible wolf is removed, and a Dragon Egg is dropped (can be re-hatched; death.drop-egg can disable this).
• Baby dragons are immune to all damage by default, preventing a 1-HP baby from dying accidentally (baby.invulnerable can disable this).
• A player can only own one dragon at a time (hatch.one-dragon-per-player).

III. Items

Item	How to Obtain	Purpose
Dragon Egg	/enderdragon egg	Right-click to place and hatch a dragon
§dDragon Whistle	/enderdragon whistle	Hold and right-click to mount your adult dragon (right-click air or dragon)
§6Dragon Whip	/enderdragon whip	Hold and right-click to make your dragon sit/stand (right-click dragon or air)

IV. Commands

Command	Permission	Description
/enderdragon egg [player]	enderdragon.admin	Give a player a Dragon Egg
/enderdragon grow [player]	enderdragon.admin	Instantly mature the player's dragon (for testing)
/enderdragon remove [player]	enderdragon.admin	Remove the player's dragon and its invisible wolf
/enderdragon whistle [player]	enderdragon.admin	Give a Dragon Whistle
/enderdragon whip [player]	enderdragon.admin	Give a Dragon Whip
/enderdragon reload	enderdragon.admin	Reload the configuration file
/enderdragon info	None (all players)	View your dragon's status (name/baby or adult/health/growth progress)

enderdragon.admin is granted to ops by default.

V. Configuration Parameters (config.yml)

Hatching Settings
hatch:
  one-dragon-per-player: true   # Each player can own at most 1 dragon

Baby Dragon Settings
baby:
  scale: 0.5                    Baby dragon scale (adult is 1.0; due to vanilla dragon model limitations, this config does not take effect — the dragon spawns at full size)
  follow-distance: 4.0          Follow distance from owner when not mounted (controlled by wolf AI)
  follow-height-offset: 3.0     Hover height: blocks above the wolf the dragon hovers at
  follow-speed: 1.1             Follow flight speed (movement step in blocks/tick)
  attack-distance: 3.5          Horizontal distance threshold for the dragon to lunge at a target
  attack-cooldown-ticks: 25     Ram attack cooldown (ticks; 20 ticks = 1 second)
  attack-damage: 2.0            (Reserved; actual damage is based on growth attack damage)
  growth-seconds: 1200          Seconds to mature into an adult dragon (default 20 minutes)
  invulnerable: true            Whether baby dragons are immune to damage
  teleport-range: 200           Range within which the wolf auto-teleports to the owner if too far away

Adult Dragon Settings adult: follow-distance: 7.0 Follow distance when not mounted follow-height-offset: 6.0 Hover height when not mounted follow-speed: 0.9 Follow flight speed attack-distance: 4.5 Ram attack horizontal distance threshold attack-cooldown-ticks: 20 Ram attack cooldown (ticks) attack-damage: 5.0 (Reserved; actual damage is based on growth attack damage)

Mounted Flight Settings ride: speed: 1.6 Flight speed (blocks/tick) vertical-speed: 1.0 Ascend speed while holding spacebar breath-cooldown-seconds: 3.0 Dragon's breath cooldown (seconds) breath-damage: 6.0 Damage dealt per dragon's breath tick breath-radius: 3.0 Dragon's breath cloud radius breath-damage-players: true # Whether dragon's breath damages other players (dragon/owner/rider are immune)

Health Growth health: initial: 1.0 Initial health at hatching per-day: 1.0 Health gained per in-game day max-cap: -1 Health cap; -1 = no cap (default)

Attack Damage Growth attack-damage: start: 1.0 Initial attack damage at hatching per-day: 0.2 Attack damage gained per in-game day max-cap: 100.0 Attack damage cap

Combat Assist combat: assist-range: 16.0 Maximum range for dragon to assist in attacking (against wolf-selected target) assist-against-players: false # Whether to help the owner attack other players retaliate: true Whether the dragon retaliates when attacked ram-distance: 2.5 Distance threshold: below this value, ram (above it, only chase)

Death Drops death: drop-egg: true # Whether the dragon drops a Dragon Egg on death (can be re-hatched)

> **Note:** `config.yml` is only auto-generated on the **first run** of the plugin. After modifying parameters, use `/enderdragon reload` for a hot-reload. If an old config file already exists on the server, you must manually add new parameters or delete the file and regenerate it.

## VI. Technical Notes (Admin Reference)

- Supports Paper 1.21.10 only.
- The dragon uses `setNoPhysics(true)` + forced HOVER phase every tick + teleport movement (vanilla dragons do not respond to `setVelocity`).
- Data persistence: The dragon's PDC stores owner / baby / hatched / lastday / hatchday / wolf / sit. These survive server restarts (including wolf binding).
- Dragon's breath cloud damage is calculated by the plugin every tick, not by built-in potion effects, ensuring consistent "damage over time" and precise exclusion of allies.

# 末影龙伙伴 (EnderDragonCompanion)

一款 Paper 1.21.10 插件：孵化一只属于你的末影龙伙伴，它像驯服的狼一样跟随你、陪你战斗、帮你喷吐龙息，成年后还可以骑乘飞行。

## 一、玩法总览

| 阶段 | 说明 |
| --- | --- |
| 孵化 | 右键放置的龙蛋方块，生成一只幼年末影龙 |
| 幼龙期 | 像原版驯服狼一样跟随/游荡/坐下，自动攻击主人攻击的目标，被攻击时反击；默认 20 分钟成年 |
| 成年 | 体型恢复 1.0，可以骑乘飞行、喷吐龙息 |
| 每日成长 | 每过一个游戏日，生命值 +1（默认不封顶）、攻击力 +0.2（封顶 100） |

## 二、核心机制说明

1. 隐形狼 AI 大脑

每条龙都绑定一只**隐形、无声**的驯服狼作为"AI 大脑"：

- 龙不做自己的 AI 决策，而是每 tick 传送到狼头顶上方悬停（幼龙高 3 格、成年龙高 6 格），视觉效果就是龙在跟随/游荡/坐下。
- 狼继承原版驯服狼的所有行为：跟随主人、近距离游荡、坐下后原地不动、主人攻击的目标就是它的目标（`wolf.getTarget()`）。
- 狼的攻击力会实时同步为龙的成长攻击力，**狼咬目标就会造成伤害**（击杀归属主人的狼，掉落物归主人）。
- 狼每 5 秒自检一次：本龙名下只允许存在一只狼，多余（异常残留/重复生成）的会被自动清理，且不会触碰其他玩家龙绑定的狼。
- 狼意外丢失时自动在龙身旁重生，并重新绑定（PDC 记录同步更新）。

2. 龙的攻击（辅助战斗）

- 目标完全由原版狼 AI 选择：主人攻击谁，狼就咬谁；龙被打时狼会反击攻击者。
- 龙在**水平距离**内会扑到目标身上撞击：造成成长伤害 + 击退，并伴随咆哮声。
- 幼龙/成年龙的攻击距离和冷却不同（见配置）。
- 龙息（见下）只有骑乘状态下由玩家左键触发。

3. 成长系统

- **血量**：孵化时 1 点，每过一个游戏日 +1，**不设上限**（属性内部上限已放宽到 100 万）。
- **攻击力**：孵化时 1 点，每过一个游戏日 +0.2，**封顶 100**。
- 每天跨日时主人收到提示消息，显示当前生命值与攻击力。
- 幼龙成长计时基于孵化时刻（可跨服重启保持，PDC 记录），成年时体型复原并提示"可以骑乘了"。

4. 骑乘飞行

- **上龙**：成年龙后，手持驯龙哨右键（空气/龙）均可上龙（需在 32 格内）。
- **控制**：
  - W/S/左/右：前后左右飞行
  - 空格：上升
  - 左键：喷吐龙息
  - 潜行：下龙
- **龙息**：从龙头向前喷出 20 个移动的龙息云团，覆盖约 50 格距离，云团在路径上持续约 4 秒；范围内所有生物每 0.2 秒结算一次伤害（伤害值受 `ride.breath-damage` 配置），**自己的龙、主人、骑乘者、伙伴狼/龙免疫**，其他玩家是否受伤由配置决定。
- **骑乘保护**：骑乘期间免疫环境伤害（窒息、坠落、火焰、岩浆、溺水、撞墙、接触伤害）——龙无物理碰撞穿墙飞行时不会伤到骑手。

5. 坐下 / 站起（停止跟随）

以下任一方式都可以切换坐/站：

- 手持**驯龙鞭**右键龙，或右键空气（对自己的龙生效）

坐下后龙（及隐形狼）原地停留，不再跟随主人。

6. 死亡与掉落

- 龙死亡时，绑定的隐形狼一并移除，并掉落一枚龙蛋（可重新孵化，`death.drop-egg` 可关闭）。
- 幼龙默认免疫一切伤害，防止 1 血幼龙意外死亡（`baby.invulnerable` 可关闭）。
- 玩家同时最多只能拥有一条龙（`hatch.one-dragon-per-player`）。

## 三、物品道具

| 物品 | 获取 | 用途 |
| --- | --- | --- |
| 龙蛋 | `/enderdragon egg` | 右键放置孵化龙 |
| §d驯龙哨 | `/enderdragon whistle` | 手持右键骑乘自己的成年龙（右键空气或右键龙均可） |
| §6驯龙鞭 | `/enderdragon whip` | 手持右键让龙坐下/站起（右键龙或右键空气均可） |

## 四、命令

| 命令 | 权限 | 说明 |
| --- | --- | --- |
| `/enderdragon egg [玩家]` | enderdragon.admin | 给玩家发放龙蛋 |
| `/enderdragon grow [玩家]` | enderdragon.admin | 让该玩家的龙立刻成年（测试用） |
| `/enderdragon remove [玩家]` | enderdragon.admin | 删除该玩家的龙及其隐形狼 |
| `/enderdragon whistle [玩家]` | enderdragon.admin | 发放驯龙哨 |
| `/enderdragon whip [玩家]` | enderdragon.admin | 发放驯龙鞭 |
| `/enderdragon reload` | enderdragon.admin | 重新加载配置文件 |
| `/enderdragon info` | 无（所有玩家） | 查看自己龙的状态（名字/幼成年/生命/成长进度） |

`enderdragon.admin` 默认授予 op。

## 五、配置文件参数（config.yml）

```yaml
# 孵化设置
hatch:
  one-dragon-per-player: true   # 每位玩家最多同时拥有 1 条龙

# 幼龙设置
baby:
  scale: 0.5                    # 幼龙体型缩放（成年为 1.0，由于原版龙模型限制，该配置不生效，即龙出生时就为正常大小）
  follow-distance: 4.0          # 未骑乘时与主人的跟随距离（由狼 AI 控制）
  follow-height-offset: 3.0     # 悬停高度：龙位于狼头顶上方多少格
  follow-speed: 1.1             # 跟随飞行速度（格/tick 的移动步长）
  attack-distance: 3.5          # 龙扑击目标的水平距离阈值
  attack-cooldown-ticks: 25     # 龙撞击冷却（tick，20 tick = 1 秒）
  attack-damage: 2.0            # （保留项，实际伤害按攻击力成长计算）
  growth-seconds: 1200          # 成长为成年龙所需秒数（默认 20 分钟）
  invulnerable: true            # 幼龙是否免疫伤害
  teleport-range: 200           # 玩家过远时狼自动传送到主人附近的范围

# 成年龙设置
adult:
  follow-distance: 7.0          # 未骑乘时跟随距离
  follow-height-offset: 6.0     # 未骑乘时悬停高度
  follow-speed: 0.9             # 跟随飞行速度
  attack-distance: 4.5          # 扑击水平距离阈值
  attack-cooldown-ticks: 20     # 撞击冷却（tick）
  attack-damage: 5.0            # （保留项，实际伤害按攻击力成长计算）

# 骑乘设置
ride:
  speed: 1.6                    # 飞行速度（格/tick）
  vertical-speed: 1.0           # 按住空格上升速度
  breath-cooldown-seconds: 3.0  # 龙息冷却（秒）
  breath-damage: 6.0            # 龙息每次结算的伤害值
  breath-radius: 3.0            # 龙息云团半径
  breath-damage-players: true   # 龙息是否伤害其他玩家（自己的龙/主人/骑手免疫）

# 血量成长
health:
  initial: 1.0                  # 孵化时初始血量
  per-day: 1.0                  # 每过一天增加的血量
  max-cap: -1                   # 血量上限，-1 = 不封顶（默认不封顶）

# 攻击力成长
attack-damage:
  start: 1.0                    # 孵化时初始攻击力
  per-day: 0.2                  # 每过一天增加的攻击力
  max-cap: 100.0                # 攻击力上限（封顶伤害）

# 战斗辅助
combat:
  assist-range: 16.0            # 龙参与攻击的最大范围（对狼选中的目标）
  assist-against-players: false # 是否帮助主人攻击其他玩家
  retaliate: true               # 龙被攻击时是否反击攻击者
  ram-distance: 2.5             # 距离阈值：低于此值使用撞击（高于只追击）

# 死亡掉落
death:
  drop-egg: true                # 龙死亡时是否掉落龙蛋（可重新孵化）

注意：config.yml 只在插件首次运行时自动生成。修改参数后可用 /enderdragon reload 热重载；如果服务端已存在旧版配置文件，需手动添加新参数或删除该文件重新生成。

六、技术说明（管理员参考）

• 仅支持 Paper 1.21.10。
• 龙使用 setNoPhysics(true) + 每 tick 强制 HOVER 相位 + teleport 移动（原版龙不响应 setVelocity）。
• 数据持久化：龙的 PDC 记录 owner / baby / hatched / lastday / hatchday / wolf / sit，重启后自动恢复（含狼绑定）。
• 龙息云团伤害由插件每 tick 结算，而非云团自带药水效果，保证"持续掉血"且可精确排除友方。