# ArenaPlus

**Repository Path**: bat5801/arena-plus

## Basic Information

- **Project Name**: ArenaPlus
- **Description**: 神岛代码编辑器加强库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-14
- **Last Updated**: 2025-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ArenaPlus.js 使用文档

ArenaPlus.js 是一个功能丰富的游戏开发工具库，类似于 Python 库或 C++头文件，提供了多种实用功能来简化游戏开发过程。以下是对所有全局函数的详细说明：

## 目录

- [使用方法](#使用方法)
- [摔伤函数](#摔伤函数)
- [跑酷速用](#跑酷速用)
- [玩家加入退出提示](#玩家加入退出提示)
- [四季变换](#四季变换)
- [游戏内光照与现实时间对应](#游戏内光照与现实时间对应)
- [自动复活](#自动复活)

## 使用方法

在要使用该文件的地方引入 ArenaPlus.js 库

```javascript
// 引入 ArenaPlus.js 库
require("./arenaplus.js");
```

## 摔伤函数

### `fallPlayer(entityKind)`

**功能描述**：开启玩家衰落伤害机制，玩家从高处落下时会受到伤害。

**参数**：

- `entityKind` (string): 玩家实体选择器，如"player"、".\*"、"#"

**使用示例**：

```javascript
// 对所有玩家启用摔伤机制
fallPlayer("player");
```

**注意事项**：

- 选择器得到的结果必须是玩家实体
- 确保不再在代码中使用`player.fall`玩家实体附属变量

## 跑酷速用

### `parkour(entityIdStarts, blockId, { saveMessage, deadMessage })`

**功能描述**：跑酷功能工具，包含碰到特定方块死亡和碰到特定模型实体存档的功能。

**参数**：

- `entityIdStarts` (string): 模型实体 id 的前缀部分，例如存档点实体的 id 可以是'存档点-1'，此处填'存档点'
- `blockId` (string|number): 碰到会导致死亡的方块名称或 ID
- `saveMessage` (string, 可选): 到达存档点时的玩家消息提示，默认为"存档成功！"
- `deadMessage` (string, 可选): 玩家死亡时的消息提示，默认为无

**使用示例**：

```javascript
// 设置存档点前缀为"checkpoint"，碰到"lava01"方块死亡
parkour("checkpoint", "lava01", {
  saveMessage: "已到达 checkpoint!",
  deadMessage: "你掉进岩浆了!",
});
```

## 玩家加入退出提示

### `join()`

**功能描述**：玩家加入游戏时，在世界频道发送提示消息。

**使用示例**：

```javascript
// 启用玩家加入提示
join();
```

### `leave()`

**功能描述**：玩家退出游戏时，在世界频道发送提示消息。

**使用示例**：

```javascript
// 启用玩家退出提示
leave();
```

## 四季变换

### `seasonChange(seconds)`

**功能描述**：通过改变草和树叶的材质，实现四季变换效果。

**参数**：

- `seconds` (number): 一个季节持续的时间，单位秒

**使用示例**：

```javascript
// 设置每个季节持续60秒
seasonChange(60);
```

**季节效果**：

- 春季：绿色草地和绿叶
- 夏季：深绿色草地和茂盛树叶
- 秋季：黄色草地和秋叶
- 冬季：白色草地和冬叶

## 游戏内光照与现实时间对应

### `sunPhaseClock()`

**功能描述**：将游戏内光照与现实北京时间同步，根据当前时间自动调整太阳相位。

**返回值**：无

**使用示例**：

```javascript
// 启用游戏内光照与现实时间同步
// 立即设置一次太阳相位
await sunPhaseClock();

// 每1分钟更新一次太阳相位
setInterval(async () => {
  await sunPhaseClock();
}, 60000);
```

**工作原理**：

1. 通过`getBeijingTimeParts()`函数获取当前北京时间的小时、分钟、秒和毫秒
2. 使用`calculateSunPhase()`函数计算太阳相位（基于 6:00 为 0，18:00 为 0.5 的 24 小时周期）
3. 设置`world.sunPhase`属性来调整游戏内光照

**注意事项**：

- 函数会自动计算北京时间，无需手动设置时区
- 建议使用定时器定期调用此函数以保持光照同步
- 太阳相位值范围为 0 到 1，其中 0 表示日出，0.5 表示日落

## 自动复活

### `autoRespawn(seconds, { message, isBroadcast })`

**功能描述**：玩家死亡时自动复活功能，可设置复活倒计时和提示消息。

**参数**：

- `seconds` (number): 复活倒计时，单位秒
- `message` (string, 可选): 复活倒计时提示消息(使用${lessTime}表示剩余秒数)
- `isBroadcast` (boolean, 可选): 是否广播复活倒计时

**使用示例**：

```javascript
// 基本使用：设置5秒后自动复活
autoRespawn(5);

// 自定义提示消息
autoRespawn(10, {
  message: `秒后复活，请等待...`,
});

// 倒计时提示
autoRespawn(8, {
  isBroadcast: true,
});
```

**工作原理**：

1. 监听玩家死亡事件(`world.onDie`)
2. 在死亡事件触发后开始倒计时
3. 倒计时期间可显示自定义消息
4. 倒计时结束后调用`entity.player.forceRespawn()`强制复活玩家

**注意事项**：

- 提示消息中的`${lessTime}`会自动替换为剩余秒数
- 设置`message`时，`isBroadcast`默认为 true
- 若设置`isBroadcast`为 true，而不设置`message`时，默认为`n秒后复活......`

## 注意事项

1. 所有函数均需在游戏环境中运行，依赖于游戏提供的 API
2. 四季变换功能会修改整个地图的方块，可能会影响性能

   希望本文档能帮助您更好地使用 ArenaPlus.js 库开发游戏！