ArenaEdit 用户手册

Appearance

如何阅读API手册 ​

API（Application Programming Interface，应用程序编程接口）是不同软件应用程序之间的通信桥梁。

在本章节中，将会把学到的JavaScript语言，并结合神岛API，共同踏上创作游戏的旅程。

在正式启程之前，掌握如何有效阅读并理解API手册将是不可或缺的一课，它将为你的游戏开发之路奠定坚实的基础。

神岛API手册：https://docs.box3lab.com/api/

信息

手册运用了关于TypeScript语言的知识，我们将在下一章节介绍它，这属于进阶章节。

你可以学完TypeScript语言章节后，再回来看这里。会有不同的收获。

手册中 declare关键字，表示该变量或类是编译时定义的，而不是运行时定义的。

我们接下来举个简单的例子，带你看懂API手册。

🌏游戏世界 ​

从🌏游戏世界界面，我们可以得到以下信息：

typescript
declare const world: GameWorld;
declare class GameWorld {
    //...
}

  1. declare const world: GameWorld;：

    • 这行代码声明了一个名为world的常量，其类型为GameWorld。这意味着在脚本中已经存在了一个GameWorld类型的world常量。

  2. declare class GameWorld { ... }：

    • 这行声明了一个名为GameWorld的类。

我们可以通过访问world常量来访问GameWorld。

属性 ​

从projectName界面，我们可以得到以下信息：

这段代码是一个类型声明代码。它声明了一个名为projectName的只读属性，其类型为string。

这意味着projectName是一个返回的数据是一个字符串。

所以，我们通过world.projectName可以获取当前地图的名称。

javascript
console.log(world.projectName);

方法 ​

从onPlayerJoin界面，我们可以得到以下信息：

这段代码是一个函数声明的示例，它定义了一个名为onPlayerJoin的函数，该函数接受一个参数，并返回一个GameEventHandlerToken类型的值。下面是对这个声明的详细解释：

  • handler:(event:GameEntityEvent)=>void：这是onPlayerJoin函数的唯一参数，名为handler。它是一个函数类型，意味着你需要传递一个函数给onPlayerJoin。这个handler函数接受一个参数event，其类型为GameEntityEvent，并且没有返回值（返回类型为void）。
    • GameEntityEvent：这是一个自定义类型，用于表示与游戏实体相关的事件。这个类型包含了事件发生时所需的所有信息。
    • void：表示handler函数不返回任何值。
  • GameEventHandlerToken：onPlayerJoin函数返回一个GameEventHandlerToken类型的值。这个类型是一个用于标识或管理事件处理程序的令牌（token）。在事件驱动的编程中，这种令牌通常用于取消或管理事件监听器。它允许你之后来移除或禁用这个特定的handler函数。

接口 ​

我们点击GameEntityEvent，可以得到以下信息：

这段代码描述了一个名为GameEntityEvent的接口（Interface），该接口用于定义一个特定类型的事件，这个事件在游戏中创建或销毁实体时被触发。

具体来说，GameEntityEvent接口定义了两个属性：

  1. entity（类型：GameEntity）：这个属性表示了被创建或销毁的实体。GameEntity是玩家实体本身一个类，它定义了游戏玩家实体的属性和方法。

  2. tick（类型：number）：这个属性表示事件发生的时间。在游戏开发中，tick通常指的是游戏循环中的某一时刻或帧数，它允许开发者知道事件是在游戏的哪个阶段发生的。这个信息对于调试、动画同步、时间管理等方面都非常有用。

关于GameEntity类具体内容可以查看：👤游戏玩家

所以，我们通过world.onPlayerJoin设置当玩家加入时，执行的操作。

javascript
world.onPlayerJoin(({ entity }) => {
  console.log(`你好，${entity.player.name}`)
});

枚举 ​

在从👤游戏玩家中，有一个cameraMode界面，我们可以得到以下信息：

这段代码的含义是：

  • cameraMode：这是一个属性名，用于引用或存储与相机模式相关的信息。
  • GameCameraMode：这是一个枚举（Enum），它定义了游戏中相机可以处于的不同模式。

我们点击GameCameraMode，可以得到以下信息：

这段代码定义了一个名为GameCameraMode的枚举，它用于表示游戏中玩家的相机视角模式。

以下是GameCameraMode枚举的详细解释：

  • FIXED：这个成员表示第三人称固定视角模式。在这种模式下，相机位于一个固定的位置，并且不随玩家的移动而移动，为玩家提供了一个从外部观察游戏世界的视角。

  • FOLLOW：这个成员表示第三人称跟随视角模式，并且被标记为默认模式。在这种模式下，相机会跟随玩家的移动，但始终保持在玩家后面的一定距离和角度，提供类似电影摄影机的效果。

  • FPS：这个成员表示第一人称视角模式。在这种模式下，相机视角与玩家的视角完全一致，就像玩家直接通过角色的眼睛在看世界一样，这是许多射击游戏和第一人称冒险游戏所采用的视角。

  • RELATIVE：这个成员表示相对于玩家位置的第三人称视角模式。在这种模式下，相机的位置可能会根据玩家的位置进行某种形式的动态调整。它用于在保持第三人称视角的同时，根据玩家的移动或朝向来调整相机的位置或角度。

所以，我们通过entity.player.cameraMode设置玩家摄像机视角 。

javascript
world.onPlayerJoin(({ entity }) => {
  // 当玩家加入地图时候，设置玩家摄像机为第一人称视角 
  entity.player.cameraMode = GameCameraMode.FPS;
});