Mcpy

🚀 MCPy：高性能Minecraft服务器引擎

MCPy 是一款由Python、Cython和先进的科学计算库驱动的下一代超优化Minecraft服务器引擎。我们的目标是提供卓越的性能和灵活性，让Minecraft服务器开发变得轻松且具有前瞻性。

⚠️ 重要提示

MCPy 正在积极开发中，功能尚未完善。代码库存在已知错误且不稳定。我们欢迎您提交 错误报告和贡献，以帮助我们更快地实现目标！

🚀 快速开始

安装

前提条件

• Python 3.9+（推荐 3.11+）
• 现代 C++ 编译器（VS 2019+ / GCC 9+）
• PostgreSQL 13+（用于生产环境）
• 至少 8 GB 内存（推荐 16 GB）

快速设置

git clone https://github.com/magi8101/mcpy.git
cd mcpy
# Windows
setup.bat
# Linux/macOS
chmod +x setup.sh
./setup.sh

手动安装

git clone https://github.com/magi8101/mcpy.git
cd mcpy
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
pip install -r _requirements.txt
pip install -e ".[dev]"
pip install -e ".[ai]"  # 可选：启用 AI 功能
python check_dependencies.py
python setup.py build_ext --inplace

运行服务器

# 使用设置脚本
# Windows:
setup.bat run
# Linux/macOS:
./setup.sh run

# 直接从命令行运行
python -m mcpy.server
python -m mcpy.server --config custom_config.toml --world my_world
python -m mcpy.server --performance-mode --max-players 100
python -m mcpy.server --debug --log-level debug

命令行选项

✨ 主要特性

• Cython加速核心：事件驱动的服务器引擎，性能接近 C 语言水平。
• 科学计算支持：集成 NumPy、SciPy 和 Polars 进行高效运算。
• 零开销网络：异步、非阻塞、协议优化的网络通信。
• 复杂实体系统：高效、可扩展的实体管理，支持先进的 AI。
• 强大的持久层：由 PostgreSQL 和 SQLAlchemy ORM 驱动，实现可靠的数据存储。
• 全面的基准测试：内置性能分析和性能剖析工具。
• 可扩展的插件框架：轻松添加服务器修改。
• 实时监控：集成 Prometheus 和 Grafana 进行实时指标监控。

📦 安装指南

前提条件

• Python 3.9+（推荐 3.11+）
• 现代 C++ 编译器（VS 2019+ / GCC 9+）
• PostgreSQL 13+（用于生产环境）
• 至少 8 GB 内存（推荐 16 GB）

快速设置

git clone https://github.com/magi8101/mcpy.git
cd mcpy
# Windows
setup.bat
# Linux/macOS
chmod +x setup.sh
./setup.sh

手动安装

git clone https://github.com/magi8101/mcpy.git
cd mcpy
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
pip install -r _requirements.txt
pip install -e ".[dev]"
pip install -e ".[ai]"  # 可选：启用 AI 功能
python check_dependencies.py
python setup.py build_ext --inplace

💻 使用示例

基础用法

# 运行服务器
python -m mcpy.server

高级用法

# 自定义配置和世界
python -m mcpy.server --config custom_config.toml --world my_world

# 启用性能模式和设置最大玩家数
python -m mcpy.server --performance-mode --max-players 100

# 启用调试模式和设置日志级别
python -m mcpy.server --debug --log-level debug

📚 详细文档

架构概述

MCPy 是模块化的，包含五个高性能核心组件：

1. server_core.pyx

   • 事件驱动的请求处理
   • 自适应、高精度的 tick 系统
   • 动态工作线程池管理
   • 实时性能剖析

2. world_engine.pyx

   • 基于多八度噪声和先进生物群系的程序地形生成
   • 多线程区块生成和内存高效的地形存储

3. network_core.pyx

   • 零拷贝数据包序列化和协议级压缩
   • 强大的连接池和 DDoS 缓解

4. entity_system.pyx

   • 基于空间哈希的实体跟踪和多线程物理模拟
   • 模块化 AI 行为树

5. persistence

   • 用于 PostgreSQL/SQLite 的 SQLAlchemy ORM
   • 高效的区块序列化和事务性世界状态

数据库配置

SQLite（默认）

[database]
type = "sqlite"
path = "world/mcpy.db"
journal_mode = "WAL"
synchronous = "NORMAL"

PostgreSQL（生产环境）

[database]
type = "postgresql"
host = "localhost"
port = 5432
dbname = "mcpy"
user = "postgres"
password = "your_password"
pool_size = 10
max_overflow = 20
echo = false

持久化特性

• 事务性世界保存

  with session.begin():
  for chunk in dirty_chunks:
  session.add(ChunkModel.from_chunk(chunk))
  

• 高效的区块序列化

  chunk_data = np.savez_compressed(io_buffer,
  blocks=chunk.blocks,
  heightmap=chunk.heightmap,
  biomes=chunk.biomes)
  

• 玩家数据管理

  player_model = PlayerModel(
  uuid=player.uuid,
  username=player.username,
  position=json.dumps([player.x, player.y, player.z]),
  inventory=pickle.dumps(player.inventory, protocol=5),
  stats=json.dumps(player.stats)
  )
  

• 智能自动保存：仅保存修改过的区块/实体
• 自动备份：可配置的间隔和保留策略

开发与测试

pytest                                # 运行完整测试套件
pytest tests/test_entity_system.py     # 实体系统测试
python -m benchmarks.benchmark        # 基准测试
python -m mcpy.profiling.profile_module world_engine  # 模块性能剖析
pytest --cov=mcpy --cov-report=html   # 测试覆盖率报告

性能调优示例

• 实体系统

  entity_spatial_hash = {(int(e.x/16), int(e.z/16)): [] for e in entities}
  for entity in entities:
  entity_spatial_hash[(int(entity.x/16), int(entity.z/16))].append(entity)
  

• 世界引擎

  with ThreadPoolExecutor(max_workers=os.cpu_count()) as executor:
  futures = [executor.submit(generate_chunk, x, z) for x, z in chunk_coords]
  chunks = [f.result() for f in futures]
  

• 网络优化

  cdef char* buffer = malloc(packet_size)
  memcpy(buffer, &packet_header, sizeof(packet_header))
  memcpy(buffer + sizeof(packet_header), packet_data, packet_data_size)
  

高级特性

插件系统

轻松添加自定义命令和行为：

from mcpy.plugins import Plugin, event

class TeleportPlugin(Plugin):
    @event("player.command")
def on_command(self, player, command, args):
if command == "tp" and len(args) >= 1:
target = self.server.get_player_by_name(args[0])
if target:
player.teleport(target.x, target.y, target.z)
return True
return False

实时监控

集成 Prometheus/Grafana 支持：

[monitoring]
enabled = true
prometheus_port = 9090
metrics = ["tps", "memory_usage", "players_online", "chunks_loaded"]

AI 实体行为

灵活的、基于行为树的 AI：

class ZombieAI(MobAI):
def setup_behaviors(self):
self.behaviors = BehaviorTree(
Selector([
Sequence([
CheckPlayerNearby(radius=16),
PathfindToPlayer(),
AttackPlayer()
]),
Sequence([
Wait(random.randint(20, 100)),
MoveToRandomPosition(radius=10)
])
])
)

🔧 技术细节

Cython 与性能

• 静态类型 (cdef) 和激进的编译器指令
• 直接的 NumPy 缓冲区访问和指针运算
• 通过线程池实现多线程并行

实体系统

• 分层、基于组件的设计
• 通过自定义内存池实现 O(1) 空间分区
• 自适应细节层次（LOD）实体管理

世界生成

• 多八度 Perlin/Simplex 噪声
• 基于 Voronoi 的生物群系过渡
• 侵蚀、洞穴和结构算法
• 10 倍的区块压缩以提高存储效率

📊 性能目标

🗺️ 路线图

短期

• [ ] 实体碰撞系统
• [ ] 合成与库存管理
• [ ] 基本战斗机制
• [ ] 世界生成优化

中期

• [ ] 多世界支持和传送门
• [ ] 自定义方块行为
• [ ] 增强的生物 AI
• [ ] 游戏内脚本 API

长期

• [ ] 分布式服务器架构
• [ ] 机器学习驱动的生物 AI
• [ ] 实时光线追踪照明
• [ ] 自定义物理引擎

🤝 贡献

我们欢迎您的贡献！请查看我们的 贡献指南 以开始：

1. 分叉仓库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到您的分支 (git push origin feature/amazing-feature)
5. 打开一个拉取请求

📄 许可证

本项目采用 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。