服务器TCPAPI接口使用文档。

[西柚木吉]

WA服务端TCP接口使用文档
本接口只适用于最新版本WA服务端,所以建议更新

概述​

此文档描述了由 TerminalEntry.Program内嵌的 TCP API Server 提供的接口。该服务器监听指定端口（默认 3264），处理简单的 HTTP-like 请求，用于与 Survivalcraft 服务器进行交互。
服务器控制变量：

• enableApiServer: 控制 API 服务器是否启动，从 settings.xml配置读取。
• apiServerPort: 监听端口，默认 3264，从 settings.xml配置读取。

重要注意事项：

1. 项目加载状态: 多数接口（除 /vs和 /ow外）需要游戏项目已加载（GameManager.Project != null），否则返回 503 Service Unavailable。
2. 认证: 如果在 settings.xml中配置了 ApiServerPassword，则必须在请求的查询字符串中包含 password参数且值正确，否则返回 401 Unauthorized。
3. HTTP 方法: 接口主要支持 GET和 POST方法。OPTIONS请求用于 CORS 预检。
4. 编码: 请求和响应均使用 UTF-8 编码。
5. CORS: 响应头包含 Access-Control-Allow-Origin: *以支持跨域请求。
6. 稳定性: 这是一个内置于游戏终端的内联服务器，并非高性能专业 HTTP 服务器，请勿进行高并发请求。
7. 错误处理: 大部分错误会返回相应的 HTTP 状态码和纯文本错误信息。

---

接口列表​

1. OPTIONS 请求 (预检)​

• 路径: 任何路径
• 方法: OPTIONS
• 功能: 处理 CORS 预检请求。
• 请求参数: 无
• 调用条件: 总是可用。
• 响应:
  • 状态码: 200 OK
  • Headers:
    • Access-Control-Allow-Origin: *
    • Access-Control-Allow-Methods: GET, POST, OPTIONS
    • Access-Control-Allow-Headers: Content-Type
  • Body: 空
• 示例:
  

  OPTIONS / HTTP/1.1
  Host: localhost:3264

2. 获取版本信息​

• 路径: /vs
• 方法: GET
• 功能: 获取服务器版本号。
• 请求参数: 无 (但若启用密码，需加 ?password=your_password)
• 调用条件: 总是可用，无需项目加载。
• 响应:
  • 状态码: 200 OK
  • Content-Type: text/plain
  • Body: 版本字符串 (例如 3.0)
• 示例:
  

  GET /vs HTTP/1.1
  Host: localhost:3264

3. 获取服务器日志​

• 路径: /log
• 方法: GET
• 功能: 获取服务器控制台的最新日志。
• 查询参数:
  • lines(可选): 指定要获取的日志行数，默认 20。使用 all获取全部日志。
  • password(可选): 如果配置了密码，则必须提供。
• 调用条件: 无需项目加载。
• 响应:
  • 状态码: 200 OK
  • Content-Type: text/plain
  • Body: 指定行数的日志内容
• 示例:
  

  GET /log?lines=50 HTTP/1.1
  Host: localhost:3264

4. 执行控制台命令​

• 路径: /cmd
• 方法: GET
• 功能: 在服务器上执行一条控制台命令并返回输出。
• 查询参数:
  • command(必需): 要执行的命令字符串。(例如 pl, say Hello)
  • lines(可选): 返回输出结果的行数，默认 20。
  • password(可选): 如果配置了密码，则必须提供。
• 调用条件: 需要项目加载 (GameManager.Project != null)。
• 响应:
  • 状态码: 200 OK(成功执行，即使命令本身错误也可能返回 200，输出中会包含错误信息)
  • Content-Type: text/plain
  • Body: 命令的执行输出
• 注意事项: 命令执行是异步的，可能会有轻微延迟。某些复杂命令可能无法通过此接口完美执行。
• 示例:
  

  GET /cmd?command=say%20Server%20Restarting&lines=10 HTTP/1.1
  Host: localhost:3264

5. 进入世界​

• 路径: /ow
• 方法: GET
• 功能: 根据索引进入一个世界存档。
• 查询参数:
  • index(必需): 世界存档的索引号 (基于 1，通过 ls命令在游戏内查看)。
  • password(可选): 如果配置了密码，则必须提供。
• 调用条件: 无需项目加载。
• 响应:
  • 状态码: 200 OK
  • Content-Type: text/plain
  • Body: 执行结果的文本消息 (例如 Entered world 1 successfully)
• 注意事项: 此操作会改变服务器状态，切换到指定的世界。
• 示例:
  

  GET /ow?index=1 HTTP/1.1
  Host: localhost:3264

6. 发送消息​

• 路径: /sendmessage
• 方法: GET| POST
• 功能: 向游戏内发送聊天消息。可以发给所有人或特定玩家。
• 参数:
  • GET 查询参数 / POST 表单/JSON 体:
    • player(可选): 目标玩家名。如果为空或不存在，则发送给所有人。
    • message(必需): 要发送的消息内容。长度限制 500 字符，不能以 /开头，不能为空。
    • password(可选): 如果配置了密码，则必须提供 (通常在查询参数中传递)。
• 调用条件: 需要项目加载 (GameManager.Project != null)。
• 请求体 (POST):
  • 可以是 application/x-www-form-urlencoded或 application/json。
  • JSON 格式示例: {"player": "PlayerName", "message": "Hello!"}
• 响应:
  • 状态码:
    • 200 OK: 消息发送成功。
    • 400 Bad Request: 参数错误、消息过长、消息格式无效。
    • 404 Not Found: 指定的玩家不存在。
    • 500 Internal Server Error: 服务器内部处理错误。
  • Content-Type: text/plain
  • Body: 结果描述文本
• 示例 (GET):
  

  GET /sendmessage?player=Steve&message=Welcome! HTTP/1.1
  Host: localhost:3264

• 示例 (POST JSON):
  

  POST /sendmessage HTTP/1.1
  Host: localhost:3264
  Content-Type: application/json
  Content-Length: 43
  
  {"player": "Alex", "message": "Hello there!"}

7. 获取死亡记录​

• 路径: /dr
• 方法: GET
• 功能: 获取尚未被标记为“已访问”的玩家死亡记录。
• 查询参数:
  • password(可选): 如果配置了密码，则必须提供。
• 调用条件: 需要项目加载 (GameManager.Project != null)。
• 响应:
  • 状态码: 200 OK
  • Content-Type: application/json
  • Body: JSON 对象，包含未访问的死亡记录列表。
    

    {
      "success": true,
      "count": 2,
      "players": ["Player1", "Player2"],
      "timestamp": "2023-10-27 10:30:00"
    }

• 注意事项: 调用成功后，这些记录会被标记为“已访问”，下次调用可能不会再次出现，除非有新的死亡事件。
• 示例:
  

  GET /dr HTTP/1.1
  Host: localhost:3264

8. 获取在线玩家列表​

• 路径: /players
• 方法: GET
• 功能: 获取当前在线玩家的详细信息列表。
• 查询参数:
  • password(可选): 如果配置了密码，则必须提供。
• 调用条件: 需要项目加载 (GameManager.Project != null)。
• 响应:
  • 状态码: 200 OK
  • Content-Type: application/json
  • Body: 复杂的 JSON 对象，包含玩家列表、计数、管理员信息等。
    

    {
      "success": true,
      "players": [
        {
          "Name": "Player1",
          "Guid": "a1b2c3d4...",
          "IsAdmin": true,
          "CommunityId": "123456789"
        }
      ],
      "player_count": 5,
      "admin_count": 1,
      "admin_list": ["Player1"],
      "all_guids": ["a1b2c3d4...", "e5f6g7h8..."],
      "timestamp": "2023-10-27 10:35:00"
    }

• 示例:
  

  GET /players HTTP/1.1
  Host: localhost:3264

---

通用错误响应​

状态码	含义	可能原因
400 Bad Request	错误请求	参数缺失、格式错误、消息无效
401 Unauthorized	未认证	密码错误或未提供密码
404 Not Found	未找到	请求的接口路径不存在
503 Service Unavailable	服务不可用	游戏项目未加载 (GameManager.Project == null)
500 Internal Server Error	服务器内部错误	接口处理过程中出现未捕获的异常

连接示例 (使用命令行工具 curl)​

1. 获取版本:
   curl "http://localhost:3264/vs"
2. 执行命令 (带密码):
   curl "http://localhost:3264/cmd?command=pl&password=your_secret_password"
3. 发送消息 (POST JSON):
   curl -X POST -H "Content-Type: application/json" -d "{\"message\": \"Server maintenance in 5 minutes.\"}" "http://localhost:3264/sendmessage?password=your_secret_password"

请根据您的实际配置和需求替换 localhost:3264和 your_secret_password。