[MD]
# ARC 真实生存插件 (ARC Realistic Survival Plugin)
[](https://github.com/EndStoneMC/python-example-plugin)
[](https://github.com/EndStoneMC/endstone)
[](https://www.python.org/)
一个基于 EndStone 框架开发的 Minecraft 真实生存插件，为服务器添加了逼真的口渴系统，让生存体验更加真实和具有挑战性。
## 🎯 功能特性
### 💧 口渴系统
- **实时口渴值**: 玩家拥有0-100的口渴值，随时间自然衰减
- **移动加速消耗**: 移动时口渴值衰减速度加倍，鼓励玩家合理规划行动
- **口渴伤害**: 口渴值为0时每10秒受到伤害，增加生存挑战
- **死亡重置**: 玩家死亡后口渴值重置为初始值，避免复活后立即死亡
- **可视化提示**: 实时显示口渴值变化和警告信息
### 🍎 物品效果系统
- **自定义物品配置**: 管理员可为任意物品配置口渴值变化和Buff效果
- **智能物品识别**: 支持物品ID、名称、附魔等多种识别方式
- **Buff系统**: 物品可提供临时Buff效果，增强游戏策略性
- **背包集成**: 直接从玩家背包选择物品进行配置，操作简便
### ⚙️ 配置管理
- **热重载**: 配置修改后立即生效，无需重启服务器
- **图形化界面**: 现代化的表单界面，直观易用
- **多语言支持**: 完整的中英双语支持
- **参数调节**: 可调节口渴衰减速度、移动倍数、初始值等参数
### 📊 数据持久化
- **SQLite数据库**: 轻量级数据库存储玩家数据和物品配置
- **XUID支持**: 使用玩家XUID确保数据永久关联，支持改名
- **自动保存**: 玩家离线时自动保存数据，防止数据丢失
## 📦 安装说明
1. **下载插件**: 将插件文件放置到服务器的 `plugins` 目录
2. **重启服务器**: 重启服务器或使用插件管理器重新加载
3. **自动初始化**: 插件将自动创建必要的数据库和配置文件
4. **开始配置**: 使用 `/ars` 命令开始配置口渴系统
## 🎮 使用指南
### 📋 指令详解
| 指令 | 权限要求 | 语法 | 功能描述 |
|------|----------|------|----------|
| `/ars` | OP | `/ars` | 打开生存配置面板，管理口渴系统 |
### 💧 口渴系统机制
#### 口渴值衰减
- **基础衰减**: 每秒减少0.1点口渴值（可配置）
- **移动加速**: 移动时衰减速度加倍（2.0倍，可配置）
- **伤害机制**: 口渴值为0时每10秒受到伤害
- **初始值**: 新玩家口渴值默认为100（可配置）
#### 物品恢复
- **自定义配置**: 管理员可为任意物品设置口渴值变化
- **Buff效果**: 物品可提供临时Buff，增强游戏体验
- **智能识别**: 支持物品ID、名称、附魔等多种识别方式
### 🔧 配置管理
#### 口渴系统配置
1. **打开配置**: 使用 `/ars` 命令打开配置面板
2. **选择配置**: 点击"口渴系统配置"
3. **调整参数**: 修改以下参数：
- `thirst_decay_per_second`: 每秒衰减的口渴值
- `thirst_moving_multiplier`: 移动时衰减倍数
- `thirst_initial`: 初始口渴值
4. **保存生效**: 提交后立即生效
#### 物品效果管理
1. **物品管理**: 在配置面板中选择"管理物品口渴值设定"
2. **添加物品**: 选择"从背包添加物品"，选择要配置的物品
3. **设置效果**: 配置口渴值变化和Buff效果
4. **保存配置**: 提交后立即生效
## 🔧 技术架构
### 🏗️ 数据库设计
#### 核心表结构
**player_thirst** - 玩家口渴值表
- `xuid` - 玩家XUID（主要标识符）
- `player_name` - 玩家名称（用于显示）
- `thirst` - 当前口渴值
- `updated_at` - 更新时间
**thirst_items** - 物品效果配置表
- `id` - 自增主键
- `item_id` - 物品ID
- `item_name` - 物品名称
- `thirst_delta` - 口渴值变化量
- `buffs` - Buff效果（JSON格式）
- `created_at` - 创建时间
- `updated_at` - 更新时间
### 📡 API 接口文档
插件提供完整的 API 接口供其他插件调用：
#### 口渴值管理接口
##### `_get_player_thirst(player) -> float`
获取玩家当前口渴值
```python
thirst_plugin = server.plugin_manager.get_plugin("arc_realistic_survival")
thirst_value = thirst_plugin._get_player_thirst(player)
print(f"玩家口渴值: {thirst_value}")
```
##### `_apply_thirst_delta(player, delta: float) -> float`
修改玩家口渴值
```python
# 增加10点口渴值
new_thirst = thirst_plugin._apply_thirst_delta(player, 10.0)
print(f"新的口渴值: {new_thirst}")
```
#### 物品配置接口
##### `_get_item_config(item_id: str) -> dict | None`
获取物品配置
```python
config = thirst_plugin._get_item_config("minecraft:apple")
if config:
print(f"口渴值变化: {config['thirst_delta']}")
print(f"Buff效果: {config['buffs']}")
```
## ⚙️ 配置系统
### 🌐 语言文件配置
语言文件位于项目根目录：
- `CN.txt` - 中文语言包
- `EN.txt` - 英文语言包
### 自定义文本
您可以编辑语言文件来自定义所有游戏内提示信息：
```ini
# CN.txt 示例 - 口渴系统文本
THIRST_PREFIX=[口渴]
THIRST_VALUE=当前口渴值: {value}
THIRST_DECREASED=你的口渴值减少了 {amount}
THIRST_INCREASED=你的口渴值增加了 {amount}
THIRST_LOW_WARNING=你的口渴值过低，请尽快补充水分！
# ... 更多配置项
```
### 配置参数
```python
# 插件内置配置参数
thirst_decay_per_second = 0.1 # 每秒衰减的口渴值
thirst_moving_multiplier = 2.0 # 移动时衰减倍数
thirst_initial = 100.0 # 初始口渴值
thirst_damage_timer = 10 # 口渴伤害间隔（秒）
```
## 🛡️ 系统要求
- **EndStone**: 0.10 或更高版本
- **Python**: 3.13 或更高版本
- **操作系统**: Windows, Linux, macOS
- **内存**: 建议至少 512MB 可用内存
- **存储**: 约 10MB 磁盘空间（不含数据库增长）
## 🎮 使用场景
### 🏔️ 硬核生存服务器
- 增加生存挑战性和真实感
- 鼓励玩家合理规划资源和行动
- 提升团队合作和资源管理
### 🏛️ 角色扮演服务器
- 为角色扮演增加真实的身体需求
- 促进玩家间的互动和交易
- 增强沉浸式游戏体验
### 🎲 冒险/探索服务器
- 为长途探险增加挑战
- 鼓励玩家寻找水源和食物
- 增加探索的紧迫感
### 🎪 小游戏服务器
- 为生存类小游戏增加机制
- 提供可配置的难度调节
- 增强游戏策略性
## 📝 更新日志
### v0.1.0 (当前版本)
- ✨ 全新的口渴系统
- 🎨 现代化配置界面
- 🌍 完整多语言支持（中英双语）
- ⚡ 实时口渴值衰减和伤害机制
- 🔌 完整的API接口供其他插件调用
- 📊 SQLite数据库高效存储
- 🛒 支持物品效果自定义配置
- 🔍 智能物品识别和Buff系统
- 🆔 **XUID支持**：使用玩家XUID确保数据永久关联
- 🎒 **标准背包API**：基于EndStone官方inventory API
- 🔒 **数据安全**：完整的错误处理和异常恢复机制
- 🛡️ **死亡重置**：玩家死亡后自动重置口渴值
### 计划功能 (v0.2.0)
- 🍖 **饥饿系统集成**: 与口渴系统联动，提供更真实的生存体验
- 🌡️ **体温系统**: 根据环境温度调节体温，影响玩家状态
- 💤 **疲劳度系统**: 长时间活动导致疲劳，影响移动速度和效率
- 📈 **健康状态综合显示**: 统一的生命值、口渴值、饥饿值、体温显示界面
- 🎯 **更多生存挑战机制**: 增加生存的复杂性和策略性
### 未来功能展望 (v0.3.0+)
#### 🦴 摔落断腿系统
- **骨折机制**: 从高处摔落可能导致腿部骨折
- **移动限制**: 骨折后移动速度大幅降低，无法跳跃
- **治疗需求**: 需要特定物品或时间才能恢复
#### 🦠 疾病系统
- **感染机制**: 接触特定生物或环境可能感染疾病
- **症状表现**: 不同疾病有不同的症状和影响
- **传播风险**: 某些疾病可能在玩家间传播
- **治疗系统**: 需要特定药物或治疗方法才能治愈
#### 🌡️ 温度生存系统
- **环境温度**: 不同生物群系有不同的环境温度
- **体温调节**: 玩家体温会根据环境温度变化
- **服装影响**: 不同材质的装备提供不同的保暖效果
- **极端天气**: 暴风雪、热浪等极端天气事件
- **体温伤害**: 体温过低或过高都会造成伤害
- **季节性变化**: 温度随游戏内时间季节变化
#### 🌿 营养系统
- **营养均衡**: 不同食物提供不同的营养成分
- **维生素缺乏**: 长期缺乏某种营养会导致疾病
- **食物保质期**: 食物会腐烂，需要妥善保存
- **烹饪系统**: 烹饪可以改善食物的营养价值和保质期
## 🤝 贡献指南
我们热烈欢迎社区贡献！
### 🐛 报告问题
- 使用 GitHub Issues 报告 bug
- 提供详细的错误信息和复现步骤
- 包含 EndStone 版本和插件版本信息
- 附上相关的日志文件
### 💡 功能建议
- 在 Issues 中提出新功能建议
- 详细描述功能需求和使用场景
- 考虑功能的可行性和实用性
- 参与社区讨论和投票
### 👨💻 代码贡献
- Fork 项目并创建功能分支
- 遵循 PEP 8 Python 代码风格
- 添加必要的单元测试
- 更新相关文档
- 提交清晰的 Pull Request
### 🌍 本地化支持
- 翻译语言文件到其他语言
- 改进现有翻译质量
- 适配不同地区的使用习惯
## 📄 许可证
本项目采用 [MIT 许可证](LICENSE)，您可以：
- ✅ 自由使用和修改源代码
- ✅ 用于商业和非商业目的
- ✅ 分发修改后的版本
- ⚠️ 需要保留原始许可证声明
## 📞 技术支持
获取帮助的多种方式：
- 📧 **邮箱支持**: DEVILENMO@gmail.com
- 🐛 **问题反馈**: [GitHub Issues](https://github.com/DEVILENMO/EndstoneMC-ARC-Realistic-Survival/issues)
- 💬 **社区讨论**: 参与项目讨论区
- 📚 **文档中心**: 查阅完整文档和教程
### 常见问题快速解答
1. **Q**: 如何备份数据？
**A**: 复制 `plugins/ARCRealisticSurvival/ars_survival.db` 文件
3. **Q**: 如何为物品添加口渴效果？
**A**: 在配置面板中选择"管理物品口渴值设定"，从背包选择物品进行配置
4. **Q**: 插件会影响服务器性能吗？
**A**: 插件经过优化，对服务器性能影响极小，适合大型服务器使用
---
**💧 ARC 真实生存插件** - 让 Minecraft 生存更加真实和具有挑战性！
*Built with ❤️ for the Minecraft community by DEVILENMO*
[/MD]
