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 = <char*>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 文件。