# 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(...)`: 这是 `GamePlayerEntity` 对象的一个方法，用于向该玩家发送一条只有他自己能看到的聊天信息。

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

## 接下来

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

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

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