English

Nekomusume brings a nekomusume companion to the edge of your screen. She is not a HUD decoration or a chatbot skin — she is a quiet presence who watches, reacts, and stays close on her own terms.

Portrait Companion

A 2D portrait lives at the edge of your screen, expressing mood through subtle expressions and body language — quiet, curious, watchful, worried, relaxed, shy, happy, and more. She stays by you without constant chatter, and only draws closer when something changes.

Ambient AI Observation

When the panel is closed, she periodically observes your situation — health, hunger, surroundings, time of day, recent activity — and adjusts her expression or offers a quiet line. This can be toggled independently; when AI is off, local rule templates take over transparently.

AI Dialogue Panel

Open the panel and she draws closer to listen. Hold full conversations through a dedicated chat panel. She stays in character — warm but not clingy, gentle but with boundaries. When the panel closes, the conversation is compressed into a short-term summary that continues to influence her mood and behavior.

Data-Driven Rule System

Ambient speech rules — JSON-defined conditions controlling what she says and when, with compound predicate support.
Portrait reaction rules — Real-time state switching based on player keywords or AI mood, with priority, duration, and cooldown.
Portrait appearance definitions — Each state's look is data-driven, supporting 2D spritesheets, 3D player skins, and 3D Geo models.

All rule types support custom JSON files and ZIP packs from the game directory, with instant reload via client command.

Three Portrait Render Modes

2D Spritesheet — Data-driven frame animation with configurable sequences, looping, and hold-last playback.
3D Player Skin — Renders your companion as a Minecraft skin-format model with optional custom textures.
3D Geo Model — Powered by GeckoLib for custom .geo.json models, textures, and animations. Gracefully falls back to 2D when GeckoLib is not installed.

Player Status Awareness

A comprehensive sensing system tracks identity, position, behavior, environment, and condition — the data that drives her emotional responses and conversation context. Sensors can be extended through KubeJS scripting.

Memory System

Persistent memory across game sessions. Dialogue records and summaries are saved and restored on next launch. The memory system can be toggled independently, with optional raw conversation persistence and async summary compaction.

In-Game Configuration Screen

Adjust every aspect of your companion through a built-in config screen — portrait render mode, default state, AI behavior toggles, context sharing, memory settings, and more. Changes apply after saving.

KubeJS Integration (Optional)

When KubeJS is installed, the Nekomusume global binding in startup and client scripts lets you register custom status sensors, read and write status memory — extending her awareness and capabilities through scripting.

Client-Side Reload Command

/nekomusume reload refreshes ambient speech rules, portrait reaction rules, and portrait appearance definitions in real time — no restart required.

Built-in Localization

Full support for Simplified Chinese and English UI text.

Optional Dependencies

GeckoLib 4.8.3 — Enables 3D Geo model portrait rendering.
KubeJS 2001.6.5 — Enables scripting API for custom sensors.

中文

Nekomusume 是一个 Minecraft 猫娘同伴模组，为你的冒险旅途带来一位安静陪伴在屏幕边缘的猫娘。她不是 HUD 装饰，不是聊天机器人皮肤——她有自己的情绪、边界和观察方式。

肖像共处

猫娘以 2D 立绘常驻屏幕边缘，通过细腻的表情和肢体语言传递情绪——安静、好奇、警觉、担心、放松、害羞、开心……她大多数时候安静相伴，只在状态明显变化时才靠近。

AI 环境观察

不开面板时，猫娘会周期性地观察你的处境：生命值、饱食度、环境、时间、近期行为，并据此调整表情或轻声说一句话。该功能可独立关闭，关闭后自动回退至本地规则模板，反应机制保持一致。

AI 对话面板

打开面板，她便会靠近倾听。通过专用面板进行多轮对话，她始终保持角色个性——亲近但不啰嗦，温柔但有边界。关闭面板后，对话内容被压缩为短期摘要，持续影响她回到立绘后的情绪和表现。

数据驱动规则系统

环境说话规则 — JSON 定义的条件系统，控制猫娘在何时、何情境下说话，支持复合条件判断。
肖像反应规则 — 根据玩家输入的关键词或 AI 返回的情绪，实时切换立绘状态，支持优先级、持续时间和冷却。
肖像外观定义 — 每种状态的外观由数据驱动，支持 2D 精灵表、3D 玩家皮肤和 3D Geo 模型三种渲染模式。

所有规则均支持从游戏目录加载自定义 JSON 文件或 ZIP 包，通过命令即时重载。

三种肖像渲染模式

2D 精灵表模式 — 数据驱动的逐帧动画，支持自定义帧序列、循环和停尾播放。
3D 玩家皮肤模式 — 以 Minecraft 皮肤格式呈现猫娘，可指定自定义皮肤纹理。
3D Geo 模型模式 — 借助 GeckoLib 加载自定义 Geo 模型、纹理和动画；未安装 GeckoLib 时自动回退至 2D。

玩家状态感知

全面的感知系统追踪你的身份、位置、行为、环境和状态——这些数据支撑她的情绪判断和对话上下文。可通过 KubeJS 脚本注册自定义传感器。

记忆系统

跨游戏会话的持久记忆。对话记录和摘要会在下次启动时恢复。记忆系统可独立开关，支持原始对话持久化和异步摘要压缩。

游戏内配置界面

通过内置配置界面调整猫娘的方方面面——肖像渲染模式、默认状态、AI 开关、上下文传递、记忆设置等，保存后即时生效。

KubeJS 集成（可选）

安装 KubeJS 后，启动脚本和客户端脚本中可通过 Nekomusume 全局绑定注册自定义状态传感器、读写状态内存，扩展她的感知和能力。

客户端重载命令

/nekomusume reload 即时重载环境说话规则、肖像反应规则和肖像外观定义，无需重启游戏。

内置双语界面

完整支持简体中文和英文界面文本。

可选依赖

GeckoLib 4.8.3 — 启用 3D Geo 模型肖像渲染。
KubeJS 2001.6.5 — 启用脚本 API 自定义传感器。

Nekomusume 不是宠物、不是助手、不是战斗随从。她只是在你冒险时，安静陪在旁边的猫娘。

Nekomusume

GeckoLib

Kotlin for Forge

KubeJS