ArenaEdit 用户手册

Appearance

API 入门：编写你的第一个游戏脚本 ​

欢迎来到 神奇代码岛 API 的世界！通过 API，你可以用 JavaScript 控制游戏里的一切，从创建实体、修改天气，到设计复杂的 UI 和游戏逻辑。本篇教程将带你迈出第一步。

理解 API 文档的核心 ​

在开始写代码前，最重要的是学会如何阅读 API 文档。这能让你独立地找到需要的功能。

1. 客户端 vs. 服务器 ​

神奇代码岛的脚本分为两类，你在文档中会看到 C- 和 S- 前缀：

  • S- (Server/服务器): 这些 API 运行在服务器上，负责核心游戏逻辑。比如创建生物、管理玩家数据、判断胜负等。所有玩家共享同一个服务器状态。服务器脚本通常是 .js 文件（例如 index.js）。
  • C- (Client/客户端): 这些 API 运行在每个玩家自己的设备上，主要负责显示和输入。比如显示 UI 界面、播放音效、响应玩家按键等。每个玩家的客户端是独立的。客户端脚本是 .js 文件（例如 clientIndex.js）。

经验法则: 当你不确定代码该写在哪里时，先问自己：“这个功能是所有玩家共享的，还是单个玩家独有的？” 如果是共享的，就写在服务器端；如果是独有的，就写在客户端。

2. 全局对象：你的 API 入口 ​

你不需要 import 或 require 任何东西来使用 API。引擎已经为我们提供了一些强大的全局对象，它们是所有功能的入口：

  • world: 服务器端的核心对象，用于管理游戏世界、实体、玩家和全局事件。
  • ui: 客户端的核心对象，用于创建和管理用户界面 (UI)。
  • storage: 服务器端的对象，用于持久化存储数据（就像一个小型数据库）。

第一个脚本：玩家加入时的欢迎语 ​

让我们来写一个简单的功能：当有玩家进入游戏时，服务器向该玩家发送一条欢迎私信。这是一个典型的服务器端逻辑。

目标: 玩家加入游戏 -> 触发事件 -> 执行代码 -> 发送私信

根据这个目标，我们可以在 world 对象中寻找“玩家加入”相关的事件。通过查阅 GameWorld 的文档，我们可以找到 onPlayerJoin 事件。

现在，打开你的项目文件，找到服务器主脚本 index.js，并写入以下代码：

javascript
// index.js

console.log("服务器脚本已启动！");

// 监听玩家加入事件
world.onPlayerJoin(({ entity }) => {
  // 从事件参数中获取加入的玩家实体
  const playerName = entity.player.name;

  // 准备欢迎消息
  const welcomeMessage = `你好，${playerName}！欢迎来到我的世界！`;

  // 通过玩家对象的 directMessage 方法发送私信
  entity.player.directMessage(welcomeMessage);

  console.log(`已向玩家 ${playerName} 发送欢迎消息。`);
});

代码解析 ​

  • world.onPlayerJoin(...): 我们在 world 对象上注册了一个事件监听器。每当有新玩家连接到服务器，括号内的函数就会被执行一次。
  • ({ entity }) => { ... }: onPlayerJoin 事件会提供一个包含 entity 属性的对象作为参数。这个 entity 就是刚刚加入的那个玩家的实体对象。
  • entity.player.name: 每个实体都有一个 player 属性，如果这个实体是玩家的话。通过 player 属性，我们可以访问到所有与玩家相关的信息和功能，比如用 .name 获取昵称。
  • entity.player.directMessage(...): 这是 GamePlayer 对象的一个方法，用于向该玩家发送一条只有他自己能看到的聊天信息。

现在，保存文件并启动游戏。当你进入地图时，检查你的聊天窗口，应该能看到服务器发来的欢迎语！

接下来 ​

恭喜你，你已经成功编写并运行了第一个与 神奇代码岛 API 交互的脚本！

这只是一个开始。接下来，你可以尝试：

  • 探索 world 对象的其他事件，比如 onPlayerLeave (玩家离开) 或 onChat (玩家聊天)。
  • 查阅 GameWorld 的 createEntity 方法，尝试在玩家加入时，在他们面前创建一个物品。