NekoMusume

NekoMusume (Catgirl) Plugin Description Paper 1.21.10 dedicated plugin. Naturally spawns "Catgirl" entities in villages. Players can use an interaction GUI to build affection with them, make them follow, assist in combat, farm, trade, marry and breed, etc. Catgirl data is saved in the entity's PersistentDataContainer, so it is not lost on server restart.

1. Core Mechanics Entity model: Each catgirl is a Mannequin (dummy/body model) with no AI of its own. The plugin uses an invisible Cat as the "mover" responsible for pathfinding, teleporting the model onto the cat every tick. Equipment / held items: Items in the catgirl's backpack (9 slots) are applied to the model's appearance (main hand / off hand / helmet / chestplate / leggings / boots). Data persistence: Affection, follow state, owner, home, married status, farming/assist toggles, backpack contents, trade data, etc. are all stored in the PDC.

2. Natural Spawning (spawn) Scans villages (villager clusters) at an interval of interval_seconds (default 5 seconds). Each scan has a chance (default 5%) probability to spawn a catgirl. Each village has a maximum of max_per_village (default 3), within a cluster radius of spawn_radius (default 64 blocks). Use /nekospawn to spawn manually.

3. Interaction GUI Right-click a catgirl to open the panel (per-player cooldown of cooldown_seconds). The panel contains:

Head info: Shows name, skin, affection, status (following / free), and marriage status. Gift: Give the currently held item to the catgirl (or pet with empty hand) to increase affection. Dialogue: Plays different lines based on affection level. Follow / Stop following: Can be toggled once affection reaches follow_threshold (panel refreshes status after clicking). Rename: Once affection reaches rename_affection (default 100), click then enter a new name in chat. Propose / Marry: Can propose once affection is full. Breed: After marriage, limited to once per day; gives birth to a kitten catgirl (initial 0.5x scale, grows up after ~20 in-game days). Farming: Toggle auto-planting / harvesting (enabling it auto-disables assist combat). Assist combat: Toggle combat assistance (enabling it auto-disables farming). Trade: Random vanilla item buy/sell (priced in diamonds, daily cap of 64 each). Backpack: Once affection reaches inventory.affection_threshold (default 60), can open to view / organize the catgirl's items. Anti-spam affection: If you gift / talk repeatedly within spam_window_ms (default 2000ms), the catgirl gets angry and deducts spam_penalty (default 3) affection. 4. Affection System Default default 50, cap max 100. Gift +gift_increase (default 5); attacked by a player −attack_decrease (default 25) and stops following / loses owner. Thresholds: follow follow_threshold 70, rename/marry rename_affection 100. 5. Combat Assistance (assist_combat) When enabled, if the owner attacks a non-tamed hostile mob and the catgirl is within 24 blocks, she marks the target and adds bonus damage (base damage default 3.0).

Held-weapon bonus: Damage stacks the catgirl's main/off-hand item's Attack Damage attribute (including NBT custom attribute bonuses, e.g. netherite sword +8), plus the Sharpness enchantment bonus. Example: holding a netherite sword adds roughly +7 damage on top of the base.

1. Armor Damage Reduction When a catgirl takes damage, standard Minecraft armor reduction is applied:

Each piece's material base armor points + Armor / Armor Toughness NBT attribute bonuses; Stacked with Protection enchantment (EPF, max 80% reduction). Incoming damage is reduced by armor before being applied. 7. Farming / Harvesting (farming) When enabled, automatically works nearby farmland: plants seeds from the backpack on empty soil (wheat / carrot / potato / beetroot, block material names fixed), and auto-harvests mature crops, storing produce in the backpack and replanting the same crop.

1. Eating Fish to Heal Periodic check: when a catgirl is not at full health and has any fish in the backpack, automatically consumes 1 fish to heal — cooked fish (COOKED_COD / COOKED_SALMON) restore 2 HP, raw fish (COD / SALMON / TROPICAL_FISH / PUFFERFISH) restore 1 HP. Only one fish eaten per cycle.

2. Commands & Permissions Command Description Permission /nekospawn [player] Spawn a catgirl near a player neko.admin (default OP) /nekoremove <id> Remove a catgirl by id neko.admin /nekolist List all catgirls (coords, affection, id) neko.admin /nekoskin <id> <skin> Change skin (player name / url:… / file:…) neko.admin /nekoskin url <id> <url> Set skin via image URL neko.admin /nekoreload Reload config file neko.admin id supports prefix matching (first 8 chars is enough; Tab completion works).

3. config.yml Details (Can be hot-reloaded via /nekoreload)

spawn: enabled: true # whether to naturally spawn max_per_village: 3 # max per village spawn_radius: 64 # village detection radius (blocks) chance: 0.05 # spawn probability per scan interval_seconds: 5 # scan interval (seconds)

skins: # available skin list

• "Beruiiu_Fengxuan" # can be a player name / "url:<image url>" / "file:<local png>"

affection: default: 50 # initial affection max: 100 # affection cap gift_increase: 5 # affection gained from gifting attack_decrease: 25 # affection lost when hit by player follow_threshold: 70 # affection required to follow

interaction: cooldown_seconds: 5 # per-player interaction cooldown spam_window_ms: 2000 # anti-spam affection window spam_penalty: 3 # anti-spam penalty rename_affection: 100 # affection required to rename/marry

assist_combat: enabled: true # master toggle for combat assist damage: 3.0 # base assist damage (plus weapon/enchant bonuses)

farming: enabled: true # master toggle for farming planting_enabled: true # whether planting is on by default

inventory: affection_threshold: 60 # affection required to open backpack

trade: enabled: true # trade feature toggle

appearance: name_prefix: "猫娘 " # name prefix colored_armor: true # tint leather by skin (note: catgirls no longer spawn with forced leather armor; you must place armor into the backpack yourself) 11. Notes Only supports Paper 1.21.10, API version 1.21. Catgirls do not spawn with leather armor; you may freely equip them with any armor (still benefits from the damage reduction above). Healing depends on the catgirl actually losing HP (damage reduction on hit is implemented); she only auto-eats fish when low on health. Renaming takes effect via chat input — sent = applied; breeding / trade limits are counted per in-game day (every 24000 ticks).

NekoMusume（猫娘）插件简介 Paper 1.21.10 专用插件，在村庄中自然生成“猫娘”实体，玩家可通过互动面板与她们建立好感、让其跟随、辅助战斗、种地、交易、结婚繁殖等。猫娘数据保存在其实体的 PersistentDataContainer 中，服务器重启不丢失。

一、核心机制 实体模型：每只猫娘是一个 Mannequin（人体模型），本身无 AI。插件用一只隐形的猫（Cat）作为“移动者(mover)” 负责寻路，每 tick 把模型传送贴到猫身上。 装备/手持：猫娘背包（9 格）里的物品会应用到模型的外观上（主手/副手/头盔/胸甲/腿甲/靴子）。 数据持久化：好感度、跟随状态、主人、家园、是否结婚、种植/辅助开关、背包内容、交易数据等全部存于 PDC。 二、自然生成（spawn） 按 interval_seconds（默认 5 秒）扫描村庄（村民聚集区），以 chance（默认 5%）概率生成猫娘，每个村庄最多 max_per_village（默认 3）只，聚集半径 spawn_radius（默认 64 格）。可用 /nekospawn 手动生成。

三、互动面板（GUI） 右键猫娘打开面板（有 cooldown_seconds 每个玩家冷却）。面板包含：

头颅信息：显示名字、皮肤、好感度、状态（跟随中/自由）、婚姻状态。 送礼：把手持物品赠予猫娘（或空手抚摸），提升好感。 对话：根据好感度播放不同台词。 跟随/停止跟随：好感达 follow_threshold 后可切换（点击后面板会刷新状态）。 改名：好感达 rename_affection（默认 100）后，点击再在聊天输入新名字。 求婚/结婚：好感满后可求婚。 繁殖：结婚后每天限一次，生下小猫娘（初始 0.5 倍体型，约 20 游戏日后长大）。 种植：开关自动种地/收地（开启会自动关闭辅助战斗）。 辅助战斗：开关战斗协助（开启会自动关闭种植）。 交易：随机原版物品买卖（钻石计价，每种每日上限 64）。 背包：好感达 inventory.affection_threshold（默认 60）后可打开，查看/整理猫娘物品。 防刷好感：若在 spam_window_ms（默认 2000ms）内重复送礼/对话，猫娘会生气并扣除 spam_penalty（默认 3）好感。

四、好感系统（affection） 默认 default 50，上限 max 100。 送礼 +gift_increase（默认 5）；被玩家攻击 −attack_decrease（默认 25）并停止跟随、解除主人。 阈值：跟随 follow_threshold 70，改名/结婚 rename_affection 100。 五、战斗辅助（assist_combat） 开启后，当主人攻击一个非驯服敌对生物，且猫娘在 24 格内，她会标记目标并追加伤害（damage 基础值默认 3.0）。

手持武器加成：伤害会叠加猫娘主手/副手物品的 Attack Damage 属性（含 NBT 自定义属性加成，如下界合金剑 +8），并加上**锋利(Sharpness)**附魔加成。 例：手持下界合金剑时，基础值上额外增加约 +7 伤害。 六、盔甲减伤 猫娘受伤时，按所穿盔甲进行 Minecraft 标准减伤计算：

各部位材质基础护甲点 + Armor/Armor Toughness 的 NBT 属性加成； 叠加 保护(Protection) 附魔（EPF，最高 80% 减伤）。 受击伤害会先被盔甲减免再结算。 七、种植 / 收获（farming） 开启后在附近耕地自动：空地种下背包里的种子（小麦/胡萝卜/马铃薯/甜菜，已修复方块材质名）；成熟作物自动收获并把产物收回背包、补种同种作物。

八、吃鱼回血 周期性检测：当猫娘血量未满且背包里有任意鱼时，自动消耗 1 条鱼回血——熟鱼（COOKED_COD/COOKED_SALMON）回 2 点生命值，生鱼（COD/SALMON/TROPICAL_FISH/PUFFERFISH）回 1 点。每周期只吃一条。

九、命令与权限 命令 说明 权限 /nekospawn [玩家] 在玩家附近生成猫娘 neko.admin（默认 OP） /nekoremove <id> 按 id 移除猫娘 neko.admin /nekolist 列出全部猫娘（含坐标、好感、id） neko.admin /nekoskin <id> <皮肤> 修改皮肤（玩家名/url:…/file:…） neko.admin /nekoskin url <id> <url> 用图片 URL 设置皮肤 neko.admin /nekoreload 重载配置文件 neko.admin id 支持前缀匹配（取前 8 位即可，Tab 补全可用）。

十、配置文件 config.yml 详解 （可通过 /nekoreload 热重载）

spawn: enabled: true # 是否自然生成 max_per_village: 3 # 每个村庄上限 spawn_radius: 64 # 村庄判定半径(格) chance: 0.05 # 每次扫描生成概率 interval_seconds: 5 # 扫描间隔(秒)

skins: # 可用皮肤列表

• "Beruiiu_Fengxuan" # 可为玩家名 / "url:<图片地址>" / "file:<本地png>"

affection: default: 50 # 初始好感 max: 100 # 好感上限 gift_increase: 5 # 送礼提升 attack_decrease: 25 # 被玩家打减少 follow_threshold: 70 # 可跟随所需好感

interaction: cooldown_seconds: 5 # 每个玩家互动冷却 spam_window_ms: 2000 # 刷好感判定窗口 spam_penalty: 3 # 刷好感惩罚 rename_affection: 100 # 改名/结婚所需好感

assist_combat: enabled: true # 战斗辅助总开关 damage: 3.0 # 辅助基础伤害(再加武器/附魔加成)

farming: enabled: true # 种地功能总开关 planting_enabled: true # 默认是否开启种植

inventory: affection_threshold: 60 # 开放背包所需好感

trade: enabled: true # 交易功能开关

appearance: name_prefix: "猫娘 " # 名字前缀 colored_armor: true # 是否按皮肤着色皮革(注：生成时不再强制穿皮革，需自行放入背包装备) 十一、注意事项 仅支持 Paper 1.21.10，API 版本 1.21。 猫娘生成时不自带皮革盔甲，可自由给她装备任意盔甲（仍享受上文减伤）。 回血依赖猫娘实际会掉血（受击减伤已实装），残血时才会自动吃鱼。 改名经聊天输入，发送即生效；繁殖/交易按游戏日(每 24000 tick)计每日限制。