Nullbot Mapart 文檔

Appearance

API 概覽 ​

歡迎使用 Nullbot Mapart API 文檔。本文檔提供完整的 API 參考資訊，幫助開發者整合和擴展 Nullbot Mapart 功能。

快速導航 ​

REST API ​

完整的 HTTP REST API 參考文檔，包含所有端點、參數和回應格式。

主要功能：

  • 系統管理和監控
  • 地圖畫建造任務管理
  • 後處理操作 (掃描、複製、重新命名)
  • 背景圖片管理
  • 資料查詢和資源存取

WebSocket API ​

即時雙向通訊 API 文檔，用於監聽系統狀態和進度更新。

主要功能：

  • 遊戲狀態資料同步 (健康、經驗、位置等)
  • 背包物品管理和更新通知
  • 任務管理和歷史更新
  • 後處理進度和狀態通知
  • 系統連接狀態監控
  • 頁尾狀態資訊推送
  • 即時日誌和除錯訊息推送

API 基礎資訊 ​

服務端點 ​

  • REST API: http://localhost:65530/api
  • WebSocket: ws://localhost:65530/ws

資料格式 ​

  • 請求格式: JSON (除檔案上傳使用 multipart/form-data)
  • 回應格式: JSON 或二進位資料 (圖片等)
  • 字元編碼: UTF-8

驗證 ​

目前 API 不需要特殊驗證，但建議：

  • 僅在信任的網路環境中使用
  • 考慮設定防火牆限制存取
  • 定期檢查存取日誌

主要 API 類別 ​

🔧 系統 API ​

管理核心系統功能和監控

  • 系統測試: 檢查服務健康狀態
  • 效能分析: 產生系統效能報告
  • 程式控制: 安全退出和重啟

🎨 地圖畫建造 API ​

完整的地圖畫建造生命週期管理

  • 任務管理: 新增、更新、刪除建造任務
  • 建造控制: 開始、停止、重新建造
  • 進度監控: 即時建造進度和狀態
  • 自動化: 自動建造排程功能

⚙️ 後處理 API ​

地圖掃描、複製和命名管理

  • 地圖掃描: 自動掃描伺服器中的地圖
  • 批次複製: 大量複製地圖物品
  • 智慧重新命名: 使用範本批次重新命名
  • 排序管理: 自訂地圖排列順序

🖼️ 背景管理 API ​

WebUI 背景圖片管理

  • 圖片上傳: 支援多種格式上傳
  • 縮圖生成: 自動產生預覽縮圖
  • 位置調整: 精確控制背景位置
  • 快取管理: 高效能圖片快取機制

📊 資料 API ​

Minecraft 遊戲資料查詢

  • 物品資料: 完整物品資訊和本地化
  • 耐久度資料: 工具耐久度對照表
  • 資源檔案: 物品圖示和頭像渲染

3. 建立 WebSocket 連接 ​

javascript
const ws = new WebSocket('ws://localhost:65530/ws');
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('收到訊息:', message);
};

效能考量 ​

請求限制 ​

  • 避免短時間內大量 API 請求
  • 使用適當的請求間隔
  • 利用快取機制減少重複請求

WebSocket 連接 ​

  • 實作斷線重連機制
  • 適當處理連接狀態變化
  • 避免創建過多同時連接

資源管理 ​

  • 及時關閉不需要的連接
  • 使用適當的超時設定
  • 監控記憶體使用情況

支援與回饋 ​

如果您在使用 API 過程中遇到問題或有改進建議，請：

  1. 查閱本文檔尋找解決方案
  2. 檢查伺服器日誌了解錯誤詳情
  3. 在 Discord 頻道 尋求協助
  4. 提交 Issue 報告問題

提示

建議先閱讀 REST API 文檔 了解完整的端點資訊，然後參考 WebSocket API 文檔 實作即時功能。

Copyright © 2025 Nullbot Mapart