# 我的世界服务器API插件

**Repository Path**: TieScript/MinecraftServerAPI

## Basic Information

- **Project Name**: 我的世界服务器API插件
- **Description**: 我的世界服务器API插件
- **Primary Language**: Java
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-26
- **Last Updated**: 2026-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MinecraftServerAPI

[![Java Version](https://img.shields.io/badge/Java-17%2B-blue)](https://www.oracle.com/java/)
[![Minecraft](https://img.shields.io/badge/Minecraft-1.21-green)](https://www.minecraft.net/)
[![License](https://img.shields.io/badge/License-GPL%20v3-red)](LICENSE)
[![API](https://img.shields.io/badge/API-REST-orange)](https://restfulapi.net/)

A comprehensive REST API solution for Minecraft server management, providing both server-side plugin and client-side SDK.

**[English](#english) | [中文](#中文)**

---

<a name="中文"></a>
## 中文文档

### 简介

MinecraftServerAPI 是一个为 Minecraft 服务器提供完整 REST API 管理能力的解决方案。项目包含两个核心模块：

| 模块 | 说明 |
|------|------|
| **ServerAPI Plugin** | Bukkit 服务端插件，提供 HTTP/HTTPS API 服务 |
| **ServerSDK** | Java 客户端 SDK，简化 API 调用 |

### 特性

- **完整的 REST API** - 覆盖服务器管理、玩家管理、世界管理等核心功能
- **双协议支持** - 同时支持 HTTP 和 HTTPS
- **灵活的权限控制** - 基于用户组的 API Key 认证机制
- **自动证书生成** - 支持自动生成自签名 SSL 证书
- **类型安全的 SDK** - 使用 Java Record 构建不可变数据模型
- **异步执行** - 自动处理 Bukkit 主线程调度
- **路径参数支持** - 支持 RESTful 风格的路径参数

### 系统要求

| 组件 | 版本要求 |
|------|----------|
| Java | 17+ |
| Minecraft | 1.21+ |
| Bukkit/Spigot/Paper | API 1.21 |

### 快速开始

#### 服务端安装

1. 下载最新版本的 `ServerAPI.jar`
2. 将 JAR 文件放入服务器的 `plugins/` 目录
3. 启动服务器，插件将自动生成配置文件
4. 编辑 `plugins/ServerAPI/serverapi.yml` 配置 API Key 和端口
5. 重启服务器或使用 `/serverapi reload` 重载配置

### API 文档

#### 基础信息

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| HTTP 端口 | 2345 | API 服务端口 |
| HTTPS 端口 | 2346 | HTTPS 服务端口 |
| 认证方式 | Bearer Token | API Key 通过 Authorization 头传递 |

#### 端点列表

##### 服务器管理

| 方法 | 端点 | 说明 |
|------|------|------|
| `GET` | `/v1/server/memory` | 获取内存使用情况 |
| `GET` | `/v1/server/status` | 获取服务器状态 |
| `GET` | `/v1/server/motd` | 获取服务器 MOTD |
| `GET` | `/v1/server/performance/tps` | 获取 TPS 信息 |
| `GET` | `/v1/server/performance/mspt` | 获取 MSPT 信息 |
| `POST` | `/v1/server/shutdown` | 关闭服务器 |
| `POST` | `/v1/server/commands` | 执行服务器命令 |
| `POST` | `/v1/server/reload` | 重载服务器配置 |
| `PATCH` | `/v1/server/properties` | 更新服务器属性 |

##### 插件管理

| 方法 | 端点 | 说明 |
|------|------|------|
| `GET` | `/v1/plugins` | 获取插件列表 |
| `GET` | `/v1/plugins/{name}` | 获取插件详情 |
| `POST` | `/v1/plugins/{name}/toggle` | 启用/禁用插件 |

##### 玩家管理

| 方法 | 端点 | 说明 |
|------|------|------|
| `GET` | `/v1/players` | 获取在线玩家列表 |
| `GET` | `/v1/players/{name}` | 获取玩家详情 |
| `POST` | `/v1/players/{name}/kick` | 踢出玩家 |
| `POST` | `/v1/players/{name}/messages` | 发送私聊消息 |
| `POST` | `/v1/broadcasts` | 全服广播 |
| `PUT` | `/v1/players/{name}/gamemode` | 设置游戏模式 |
| `POST` | `/v1/players/{name}/teleport` | 传送玩家 |
| `GET` | `/v1/players/{name}/location` | 获取玩家位置 |
| `GET` | `/v1/players/{name}/inventory` | 获取玩家背包 |
| `POST` | `/v1/players/{name}/inventory/items` | 给予物品 |
| `DELETE` | `/v1/players/{name}/inventory` | 清空背包 |
| `PUT` | `/v1/players/{name}/health` | 设置生命值 |
| `PUT` | `/v1/players/{name}/food` | 设置饥饿值 |

##### 封禁与白名单

| 方法 | 端点 | 说明 |
|------|------|------|
| `GET` | `/v1/bans` | 获取封禁列表 |
| `POST` | `/v1/bans` | 封禁玩家 |
| `DELETE` | `/v1/bans/{name}` | 解封玩家 |
| `POST` | `/v1/bans/ip` | IP 封禁 |
| `DELETE` | `/v1/bans/ip/{ip}` | IP 解封 |
| `POST` | `/v1/whitelist` | 添加白名单 |
| `DELETE` | `/v1/whitelist/{name}` | 移除白名单 |

##### 世界管理

| 方法 | 端点 | 说明 |
|------|------|------|
| `GET` | `/v1/worlds` | 获取世界列表 |
| `GET` | `/v1/worlds/{name}` | 获取世界详情 |
| `PUT` | `/v1/worlds/{name}/weather` | 设置天气 |
| `PUT` | `/v1/worlds/{name}/time` | 设置时间 |
| `PUT` | `/v1/worlds/{name}/difficulty` | 设置难度 |
| `POST` | `/v1/worlds` | 创建世界 |
| `DELETE` | `/v1/worlds/{name}` | 删除世界 |

##### 系统与健康检查

| 方法 | 端点 | 说明 |
|------|------|------|
| `GET` | `/v1/system/info` | 获取系统信息 |
| `GET` | `/v1/system/stats` | 获取 API 统计 |
| `GET` | `/health` | 健康检查 |
| `GET` | `/health/detail` | 详细健康状态 |

#### 请求示例

**获取服务器状态：**

```bash
curl -X GET "http://localhost:2345/v1/server/status" \
  -H "Authorization: Bearer your-api-key"
```

**响应示例：**

```json
{
  "status": "success",
  "data": {
    "basicInfo": {
      "serverName": "ServerAPI Server",
      "version": "1.21",
      "motd": "Welcome to my server!"
    },
    "playerInfo": {
      "onlineCount": 5,
      "maxPlayers": 20
    }
  }
}
```

**执行服务器命令：**

```bash
curl -X POST "http://localhost:2345/v1/server/commands" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"command": "say Hello from API!"}'
```

**踢出玩家：**

```bash
curl -X POST "http://localhost:2345/v1/players/Steve/kick" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "违反服务器规则"}'
```

### 配置说明

配置文件位于 `plugins/ServerAPI/serverapi.yml`：

```yaml
server:
  port: 2345
  https:
    enabled: false
    port: 2346
    keystore: "auto"
    keystore-password: "auto"
    key-password: "auto"

user-groups:
  admin:
    description: "管理员组"
    api-keys:
      - "your-admin-api-key"
    allowed-routes:
      - "*"
  bot:
    description: "机器人组"
    api-keys:
      - "your-bot-api-key"
    allowed-routes:
      - "*"
    denied-routes:
      - "serveractions.shutdown"

api-routes:
  serveractions:
    shutdown:
      require-auth: true
      required-group: "admin"
```

#### 用户组权限

| 用户组 | 权限范围 |
|--------|----------|
| `admin` | 完全访问权限 |
| `bot` | 可限制特定敏感操作 |
| `open` | 只读访问权限 |

### SDK 使用指南

#### 创建客户端

```java
MinecraftServerApi api = MinecraftServerApi.builder()
    .host("your-server.com")
    .port(2345)
    .apiKey("your-api-key")
    .https(true)
    .connectTimeout(10)
    .readTimeout(30)
    .build();
```

#### 服务器操作

```java
ServerClient server = api.server();

ServerStatus status = server.getStatus();
MemoryInfo memory = server.getMemory();
TpsInfo tps = server.getTps();

server.runCommand("gamemode creative @a");
server.reload();
```

#### 玩家操作

```java
PlayerClient player = api.player();

List<PlayerInfo> players = player.list();
PlayerDetails details = player.get("Steve");

player.kick("Steve", "违规操作");
player.sendMessage("Steve", "你好！");
player.broadcast("服务器公告");

player.setGameMode("Steve", "CREATIVE");
player.teleportToPlayer("Steve", "Alex");
```

#### 世界操作

```java
WorldClient world = api.world();

List<WorldInfo> worlds = world.list();
WorldDetails details = world.get("world");

world.setClearWeather("world");
world.setDay("world");
world.setDifficulty("world", "HARD");

world.create("new_world", "NORMAL", "NORMAL", 12345L);
```

#### 健康检查

```java
HealthClient health = api.health();

if (api.isHealthy()) {
    System.out.println("服务器运行正常");
}

HealthStatus status = health.check();
Map<String, Object> detail = health.checkDetail();
```

### 构建项目

#### 构建服务端插件

```bash
cd MinecraftServerAPI
./gradlew build
```

构建产物位于 `build/libs/ServerAPI-2.0.jar`

#### 构建 SDK

```bash
cd MinecraftServerAPI/ServerSDK
./gradlew build
```

构建产物位于 `ServerSDK/build/libs/ServerSDK-1.0.jar`

### 项目结构

```
MinecraftServerAPI/
├── src/main/java/com/langlang/serverapi/
│   ├── ServerApiPlugin.java      # 插件入口
│   ├── api/                      # API 处理器
│   │   ├── ApiRegistry.java
│   │   ├── ServerApi.java
│   │   ├── PlayerApi.java
│   │   ├── WorldApi.java
│   │   ├── SystemApi.java
│   │   └── HealthApi.java
│   ├── config/                   # 配置管理
│   ├── http/                     # HTTP 服务
│   │   ├── HttpServerWrapper.java
│   │   ├── Router.java
│   │   ├── Route.java
│   │   └── middleware/
│   └── util/                     # 工具类
├── ServerSDK/src/main/java/cn/langlang/
│   ├── MinecraftServerApi.java   # SDK 入口
│   ├── client/                   # 客户端模块
│   ├── config/                   # 配置类
│   ├── model/                    # 数据模型
│   ├── exception/                # 异常类
│   └── util/                     # 工具类
└── resources/
    ├── plugin.yml
    └── serverapi.yml
```

### 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 许可证

本项目采用 [GNU General Public License v3.0](LICENSE) 开源协议。

```
Copyright (C) 2024 LangLang

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
```

---

<a name="english"></a>
## English Documentation

### Introduction

MinecraftServerAPI is a comprehensive REST API solution for Minecraft server management. The project consists of two core modules:

| Module | Description |
|--------|-------------|
| **ServerAPI Plugin** | Bukkit server-side plugin providing HTTP/HTTPS API services |
| **ServerSDK** | Java client SDK for simplified API calls |

### Features

- **Complete REST API** - Covers server management, player management, world management, etc.
- **Dual Protocol Support** - Both HTTP and HTTPS supported
- **Flexible Permission Control** - User group-based API Key authentication
- **Auto Certificate Generation** - Self-signed SSL certificate support
- **Type-Safe SDK** - Immutable data models using Java Records
- **Async Execution** - Automatic Bukkit main thread scheduling
- **Path Parameter Support** - RESTful style path parameters

### Requirements

| Component | Version |
|-----------|---------|
| Java | 17+ |
| Minecraft | 1.21+ |
| Bukkit/Spigot/Paper | API 1.21 |

### Quick Start

#### Server Installation

1. Download the latest `ServerAPI.jar`
2. Place the JAR file in the server's `plugins/` directory
3. Start the server, the plugin will generate configuration files automatically
4. Edit `plugins/ServerAPI/serverapi.yml` to configure API Key and ports
5. Restart the server or use `/serverapi reload` to reload configuration

**Basic Usage:**

```java
MinecraftServerApi api = MinecraftServerApi.builder()
    .host("localhost")
    .port(2345)
    .apiKey("your-api-key")
    .build();

if (api.isHealthy()) {
    ServerStatus status = api.server().getStatus();
    System.out.println("Online players: " + status.onlineCount());
    
    api.player().broadcast("Welcome to the server!");
}
```

### API Endpoints

#### Server Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/server/memory` | Get memory usage |
| `GET` | `/v1/server/status` | Get server status |
| `GET` | `/v1/server/motd` | Get server MOTD |
| `GET` | `/v1/server/performance/tps` | Get TPS info |
| `GET` | `/v1/server/performance/mspt` | Get MSPT info |
| `POST` | `/v1/server/shutdown` | Shutdown server |
| `POST` | `/v1/server/commands` | Execute command |
| `POST` | `/v1/server/reload` | Reload server config |
| `PATCH` | `/v1/server/properties` | Update server properties |

#### Player Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/players` | Get online players |
| `GET` | `/v1/players/{name}` | Get player details |
| `POST` | `/v1/players/{name}/kick` | Kick player |
| `POST` | `/v1/players/{name}/messages` | Send private message |
| `POST` | `/v1/broadcasts` | Broadcast message |
| `PUT` | `/v1/players/{name}/gamemode` | Set game mode |
| `POST` | `/v1/players/{name}/teleport` | Teleport player |

#### World Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/worlds` | Get world list |
| `GET` | `/v1/worlds/{name}` | Get world details |
| `PUT` | `/v1/worlds/{name}/weather` | Set weather |
| `PUT` | `/v1/worlds/{name}/time` | Set time |
| `PUT` | `/v1/worlds/{name}/difficulty` | Set difficulty |
| `POST` | `/v1/worlds` | Create world |
| `DELETE` | `/v1/worlds/{name}` | Delete world |

### Building

```bash
# Build server plugin
./gradlew build

# Build SDK
cd ServerSDK && ./gradlew build
```

### Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Create a Pull Request

### License

This project is licensed under the [GNU General Public License v3.0](LICENSE).

---

**Author:** LangLang

**Project Links:** [GitHub Repository](https://github.com/langlang/MinecraftServerAPI)