EasyBox3Lib库
一个适用于大部分地图的通用代码库
- Version
- 0.1.6
- License
- MIT
- Source
- Version
- 0.1.6
- License
- MIT
- Source
Classes
- DataStorage
- Menu
- Pages
- EntityGroup
- Item
- Thing
- ThingStorage
- DataStorage
- Menu
- Pages
- EntityGroup
- Item
- Thing
- ThingStorage
Members
(inner, constant) CONFIG
配置文件
- Source
(inner) gameLoops :Map.<string, {statu: ("running"|"stop"|"awaiting_deletion"|"awaiting_stop"), init: EventCallBack, times: number}>
- Map.<string, {statu: ("running"|"stop"|"awaiting_deletion"|"awaiting_stop"), init: EventCallBack, times: number}>
- Source
(inner) started
地图是否完全启动（预处理函数执行完成）@type {boolean}
- Source
(inner) itemRegistry
物品注册表 @private @type {Map<string, Item>}
- Source
(inner) storageQueue :Map.<string, StorageTask>
Storage Queue - Storage任务队列 队列只会在start方法调用时才会开始，或者手动调用startStorageQueue函数
- Map.<string, StorageTask>
- Source
(inner) storageQueueStarted :boolean
- boolean
- Source
(inner) registryClassIndex :Map.<any, function()>
注册函数类别索引
- Map.<any, function()>
- Source
(inner) onOpen :Array.<dialogCallBack>
当该页被打开时执行的操作
- Array.<dialogCallBack>
- Source
(inner) onClose :Array.<dialogCallBack>
当该菜单被关闭时执行的操作
- Array.<dialogCallBack>
- Source
(inner) onOpen :Array.<dialogCallBack>
当该页被打开时执行的操作
- Array.<dialogCallBack>
- Source
(inner) onClose :Array.<dialogCallBack>
当该菜单被关闭时执行的操作
- Array.<dialogCallBack>
- Source
(inner, constant) CONFIG
配置文件
- Source
(inner) gameLoops :Map.<string, {statu: ("running"|"stop"|"awaiting_deletion"|"awaiting_stop"), init: EventCallBack, times: number}>
- Map.<string, {statu: ("running"|"stop"|"awaiting_deletion"|"awaiting_stop"), init: EventCallBack, times: number}>
- Source
(inner) started
地图是否完全启动（预处理函数执行完成）@type {boolean}
- Source
(inner) itemRegistry
物品注册表 @private @type {Map<string, Item>}
- Source
(inner) storageQueue :Map.<string, StorageTask>
Storage Queue - Storage任务队列 队列只会在start方法调用时才会开始，或者手动调用startStorageQueue函数
- Map.<string, StorageTask>
- Source
(inner) storageQueueStarted :boolean
- boolean
- Source
(inner) registryClassIndex :Map.<any, function()>
注册函数类别索引
- Map.<any, function()>
- Source
(inner) onOpen :Array.<dialogCallBack>
当该页被打开时执行的操作
- Array.<dialogCallBack>
- Source
(inner) onClose :Array.<dialogCallBack>
当该菜单被关闭时执行的操作
- Array.<dialogCallBack>
- Source
(inner) onOpen :Array.<dialogCallBack>
当该页被打开时执行的操作
- Array.<dialogCallBack>
- Source
(inner) onClose :Array.<dialogCallBack>
当该菜单被关闭时执行的操作
- Array.<dialogCallBack>
- Source
Methods
(inner) nullc(a, b) → {*}
空值合并
| Name | Type | Description |
|---|---|---|
a | * | |
b | * |
- Source
- Type:
- *
(inner) copyObject(obj) → {any}
复制一个object
| Name | Type | Description |
|---|---|---|
obj | any | 要复制的 |
- Source
- Type:
- any
(inner) getEntity(id) → {Box3Entity}
使用实体ID获取一个实体
| Name | Type | Description |
|---|---|---|
id | string | 实体ID |
- Source
- Type:
- Box3Entity
(inner) getEntities(tag) → {Array.<Box3Entity>}
使用实体标签获取一组实体
| Name | Type | Description |
|---|---|---|
tag | string | 实体标签 |
- Source
- Type:
- Array.<Box3Entity>
(inner) getPlayer(value, key) → {Box3PlayerEntity|undefined}
通过玩家的昵称/BoxID/userKey找到一个玩家
如果没有找到，返回undefined
也可以在key参数中填入其他的东西，但不建议，因为可能有多个玩家满足该条件
判断方法：
entity.player[key] == value
| Name | Type | Default | Description |
|---|---|---|---|
value | * | 见上 | |
key | string | name | 见上，一般填入 |
- Source
- Type:
- Box3PlayerEntity |
undefined
(inner) getTheCodeExecutionLocation() → {Object}
获取当前代码的执行位置
- Source
- Type:
- Object
(inner) output(type, …data) → {string}
输出一段日志，并记录到日志文件中
| Name | Type | Attributes | Description |
|---|---|---|---|
type | 'log' | | 输出类型 | |
data | string | <repeatable> | 要输出的内容 |
- Source
- Type:
- string
(inner) throwError(…data)
抛出错误
| Name | Type | Attributes | Description |
|---|---|---|---|
data | string | <repeatable> | 错误内容 |
- Source
(inner) isAdmin(entity) → {boolean}
通过管理员列表，判断一个玩家是不是管理员
注意：对于在运行过程中添加的管理员（即entity.player.isAdmin为true但管理员列表中没有该玩家的userKey，返回false
对于这种情况，应该使用：
entity.player.isAdmin
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要判断的实体 |
- Source
- Type:
- boolean
(inner) setAdminStatus(entity, type)
设置一个玩家是否是管理员
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要设置的玩家 |
type | boolean | 是否设置为管理员 |
- Source
(inner) resizePlayer(entity, size)
缩放一个玩家，包括玩家的移动速度&跳跃高度
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要缩放的玩家 |
size | number | 缩放尺寸 |
- Source
(inner) createEntity(mesh, position, collides, gravity, meshScale, meshOrientation) → {Box3Entity|null}
简单创建一个实体（其实也没简单到哪去）
| Name | Type | Description |
|---|---|---|
mesh | string | 实体外形 |
position | Box3Vector3 | 实体位置 |
collides | boolean | 实体是否可碰撞 |
gravity | boolean | 实体是否会下落 |
meshScale | Box3Vector3 | 实体的缩放比例 |
meshOrientation | Box3Quaternion | 实体的旋转角度 |
- Source
- Type:
- Box3Entity |
null
(async, inner) textDialog(entity, title, content, hasArrow, otherOptions) → {'success'|number|null}
弹出一个/若干个文本对话框
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要弹出对话框的玩家 |
title | string | 对话框的标题 |
content | string | | 对话框的正文，也可以输入一个列表来实现多个对话框依次弹出（相当于一个低配版的 |
hasArrow | 'auto' | | 是否显示箭头提示， |
otherOptions | object | 对话框的其他选项 |
- Source
如果完成了所有对话，则返回success（只有一个对话框）或者完成对话框的数量（有多个对话框）；否则返回null（只有一个对话框）
- Type:
- 'success' |
number | null
(async, inner) inputDialog(entity, title, content, confirmText, placeholder, otherOptions) → {string|null}
弹出一个输入对话框
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要弹出对话框的玩家 |
title | string | 对话框的标题 |
content | string | 对话框的正文 |
confirmText | undefined | | 可选，确认按钮文字 |
placeholder | undefined | | 可选，输入框提示文字 |
otherOptions | object | 对话框的其他选项 |
- Source
输入框填写的内容字符串
- Type:
- string |
null
(async, inner) selectDialog(entity, title, content, options, otherOptions) → {Box3DialogSelectResponse}
弹出一个选项对话框
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要弹出对话框的玩家 |
title | string | 对话框的标题 |
content | string | 对话框的正文 |
options | Array.<string> | 选项列表 |
otherOptions | object | 对话框的其他选项 |
- Source
玩家选择的选项
- Type:
- Box3DialogSelectResponse
(inner) shuffleTheList(oldList) → {Array.<any>}
打乱一个列表
| Name | Type | Description |
|---|---|---|
oldList | Array.<any> | 要打乱的列表 |
- Source
- Type:
- Array.<any>
(inner) random(min, max, integer) → {number}
随机生成一个数
| Name | Type | Default | Description |
|---|---|---|---|
min | number | 0 | 生成范围的最小值 |
max | number | 1 | 生成范围的最大值 |
integer | boolean | false | 是否生成一个整数 |
- Source
- Type:
- number
(inner) toChineseDate(date) → {string}
将Unix时间戳转换为中文日期
| Name | Type | Description |
|---|---|---|
date | number | Unix时间戳 |
- Source
- Type:
- string
toChineseDate(Date.now())(async, inner) executeSQLCode(code) → {any}
执行一段SQL命令
仅在旧岛中使用
| Name | Type | Description |
|---|---|---|
code | string |
- Source
- Type:
- any
(async, inner) tryExecuteSQL(func, msg)
尝试执行SQL代码
| Name | Type | Description |
|---|---|---|
func | function | 要执行的代码 |
msg | string | 当代码执行失败时，输出的信息 |
- Source
(async, inner) getDataStorage(key) → {DataStorage}
连接指定数据存储空间，如果不存在则创建一个新的空间。
| Name | Type | Description |
|---|---|---|
key | string | 指定空间的名称，长度不超过50个字符 |
- Source
- Type:
- DataStorage
(async () => {
await EasyBox3Lib.storage.getDataStorage('test');
})();(inner) getDataStorageInCache(storageKey) → {DataStorage}
在缓存中直接获取指定数据存储空间
比getDataStorage更快，但不能创建数据存储空间
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定数据存储空间名称 |
- Source
- Type:
- DataStorage
await EasyBox3Lib.storage.getDataStorage('test');
var playerStorage = EasyBox3Lib.storage.getDataStorageInCache('test');(async, inner) setData(storageKey, key, value)
设置一个键值对
与DataStorage.set方法不同，该方法调用后不会立即写入数据，而是移动到Storage Queue中
建议添加 await
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定空间的名称，不需要提前获取空间 |
key | string | 需要设置的键 |
value | string | 需要设置的值 |
- Source
await EasyBox3Lib.storage.setData('test', entity.player.userKey, {
money: entity.player.money,
experience: entity.player.experience,
itemList: entity.player.itemList.toString(),
});(async, inner) getData(storageKey, key) → {ReturnValue}
查找一个键值对
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定空间的名称，不需要提前获取空间 |
key | string | 指定的键 |
- Source
- Type:
- ReturnValue
var data = await EasyBox3Lib.storage.getData('test', entity.player.userKey);(async, inner) listData(storageKey, options) → {QueryList}
批量获取键值对注意：该方法不会创建缓存和读取缓存，所以比 目前在完全缓存的情况下可以在此使用缓存，需要更改配置文件get更慢
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定空间的名称，不需要提前获取空间 |
options | ListPageOptions | 批量获取键值对的配置项 |
- Source
- Type:
- QueryList
var datas = await EasyBox3Lib.storage.listData('test', {cursor: 0});(async, inner) removeData(storageKey, key)
删除表中的键值对 与DataStorage.remove方法不同，该方法调用后不会立即写入数据，而是移动到Storage Queue中
建议添加 await
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定空间的名称，不需要提前获取空间 |
key | string | 指定的键 |
- Source
await EasyBox3Lib.storage.removeData('test', entity.player.userKey);(async, inner) dropDataStorage(storageKey)
删除指定数据存储空间
警告：删除之后无法恢复，请谨慎使用！！！
不支持Arena，只支持旧岛
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定数据存储空间，不需要提前获取空间 |
- Source
await EasyBox3Lib.storage.dropDataStorage('player');(inner) createGameLoop(name, callbackfn)
创建游戏循环
需要手动调用runGameLoop运行
| Name | Type | Description |
|---|---|---|
name | string | 循环名称 |
callbackfn | EventCallBack | 要执行的函数。提供一个参数：time，代表循环执行的次数 |
- Source
EasyBox3Lib.createGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});(async, inner) startGameLoop(name, callbackfn)
创建并运行游戏循环
如果循环已存在，则直接运行循环
| Name | Type | Description |
|---|---|---|
name | string | 循环名称 |
callbackfn | EventCallBack | | 要执行的函数。提供一个参数：time，代表循环执行的次数。如果为空且循环存在，则继续循环 |
- Source
EasyBox3Lib.startGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});EasyBox3Lib.createGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});
EasyBox3Lib.startGameLoop('test1');(inner) stopGameLoop(name)
停止游戏循环
该游戏循环可能不会立即停止，而是在当前循环运行完后真正停止
| Name | Type | Description |
|---|---|---|
name | string | 循环名称 |
- Source
EasyBox3Lib.startGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});
EasyBox3Lib.stopGameLoop('test1');
//这个例子可能不是很好，因为设计的时候就没想过这么用，比这个复杂多了，参见Storage Queue的实现(async, inner) runGameLoop(name)
运行游戏循环
| Name | Type | Description |
|---|---|---|
name | string | 循环名称 |
- Source
EasyBox3Lib.createGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});
EasyBox3Lib.runGameLoop('test1');(inner) deleteGameLoop(name)
删除游戏循环，之后不能再对该循环进行操作
如果循环正在运行中，那么循环结束后才会删除
| Name | Type | Description |
|---|---|---|
name | string | 循环名称 |
- Source
EasyBox3Lib.createGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});
EasyBox3Lib.deleteGameLoop('test1');//刚创建还没运行就删除（）
//这个例子可能不是很好，因为设计的时候就没想过这么用，比这个复杂多了，参见Storage Queue的实现(inner) registerEvent(name)
注册一个事件
| Name | Type | Description |
|---|---|---|
name | string | 事件名称 |
- Source
registerEvent('testEvent');(inner) addEventHandler(eventName, handler)
添加事件监听器
不可使用此方法注册onTick事件
| Name | Type | Description |
|---|---|---|
eventName | string | 事件名称 |
handler | EventCallBack | 事件监听器 |
- Source
EasyBox3Lib.registerEvent('testEvent');
EasyBox3Lib.addEventHandler('testEvent', () => {
output("log", '触发事件');
});EasyBox3Lib.addEventHandler('onStart', () => {
EasyBox3Lib.output('地图启动成功');
});
EasyBox3Lib.addEventHandler('onPlayerJoin', ({ entity }) => {
world.say('欢迎', entity.player.name, '加入地图！');
});(async, inner) triggerEvent(eventName, data)
触发一个事件
| Name | Type | Description |
|---|---|---|
eventName | string | 事件名称 |
data | object | 监听器使用的参数 |
- Source
EasyBox3Lib.registerEvent('testEvent');
EasyBox3Lib.addEventHandler('testEvent', () => {
EasyBox3Lib.output("log", '触发事件');
});
EasyBox3Lib.triggerEvent('testEvent');EasyBox3Lib.registerEvent('testEvent');
EasyBox3Lib.addEventHandler('testEvent', ({ data }) => {
EasyBox3Lib.output("log", '触发事件 data =', data);
});
EasyBox3Lib.triggerEvent('testEvent', { data: 114514 });(inner) removeEvent(eventName)
移除一个事件，之后不能监听该事件
| Name | Type | Description |
|---|---|---|
eventName | string | 事件名称 |
- Source
(inner) onTick(handler, tpc, performanceImpact, enforcement) → {OnTickHandlerToken}
注册一个onTick事件，类似于Box3中的onTick事件，但有一些优化
需要在预处理时注册
| Name | Type | Default | Description |
|---|---|---|---|
handler | onTickEventCallBack | 要执行的函数 | |
tpc | number | 每个循环的执行次数（times per cycles） | |
performanceImpact | number | 1 | 性能影响程度 |
enforcement | boolean | false | 如果为false，则如果上一次未执行完，则不会执行 |
- Source
- Type:
- OnTickHandlerToken
EasyBox3Lib.onTick(({ tick }) => {
EasyBox3Lib.output("log", 'tick', tick);
}, 16);(inner) preprocess(callbackfn, priority)
添加预处理函数
| Name | Type | Description |
|---|---|---|
callbackfn | preprocessCallback | 要执行的函数 |
priority | number | 优先级，值越大越先执行 |
- Source
EasyBox3Lib.preprocess(() => {
EasyBox3Lib.output("log", '这是一个预处理函数，会第一个执行');
}, 2);
EasyBox3Lib.preprocess(() => {
EasyBox3Lib.output("log", '这是一个预处理函数，会第二个执行');
}, 1);
EasyBox3Lib.preprocess(() => {
EasyBox3Lib.output("log", '优先级甚至可以是负数和小数！');
}, -114.514);(async, inner) planningOnTickEvents()
规划onTick事件
一般不需要自行调用
- Source
(async, inner) start()
启动地图（执行预处理函数）
- Source
EasyBox3Lib.start();EasyBox3Lib.addEventHandler('onStart', () => {
EasyBox3Lib.output('地图启动成功');
});
EasyBox3Lib.addEventHandler('onPlayerJoin', ({ entity }) => {
world.say('欢迎', entity.player.name, '加入地图！');
});
EasyBox3Lib.start();(inner) changeVelocity(velocity, time)
转换速度单位
把velocity/time转换为result/64ms
公式为：
result = velocity * time / 64
| Name | Type | Description |
|---|---|---|
velocity | number | 移动的速度，每 |
time | number | 速度的单位时间，单位：ms。默认为1s |
- Source
changeVelocity(1, 1000); // 1格/schangeVelocity(299792458, 1000); // 光速，299792458格/s(inner) registerItem(item) → {boolean}
注册一种物品
如果成功注册物品，返回true，否则返回false
| Name | Type | Description |
|---|---|---|
item | Item | 要注册的物品 |
- Source
- Type:
- boolean
(inner) startStorageQueue()
启动Storage Queue
只有启动了Storage Queue，setData和removeData的任务才会被处理
- Source
(inner) stopStorageQueue()
停止Storage QueuesetData和removeData仍会将任务放到队列中，但不会再次处理，除非运行startStorageQueue
- Source
EasyBox3Lib.stopStorageQueue();(inner) translationError(message) → {string}
翻译报错信息
| Name | Type | Description |
|---|---|---|
message | string | 报错内容 |
- Source
翻译后的信息
- Type:
- string
(inner) register(any)
万用注册函数
| Name | Type | Description |
|---|---|---|
any | any | 你要注册的东西 |
- Source
EasyBox3Lib.register(new EasyBox3Lib.Item('豆奶', '豆奶', 16, ['食物'], undefined, { recovery: 6 }));EasyBox3Lib.register(new BehaviorLib.Behavior("findAttackTarget", (self, data) => {
self.attackTarget = world.querySelectorAll(data.selector).filter(data.filter)[0];
}, 1));(inner) registerRegistryClassIndex(fn)
注册注册函数类别索引
满足any instanceof type时调用fn(any)
| Name | Type | Description |
|---|---|---|
fn | function |
- Source
EasyBox3Lib.registerRegistryClassIndex(EasyBox3Lib.Item, registerItem);(inner) spiltWord(word) → {Array.<string>}
根据大小写和符号，拆分单词
| Name | Type | Description |
|---|---|---|
word | string |
- Source
- Type:
- Array.<string>
(inner) createEntityGroup(entities, position) → {EntityGroup}
创建一个实体组
更改entities中每个实体的indexInEntityGroup属性为该实体在实体组内的编号
| Name | Type | Description |
|---|---|---|
entities | Array.<Box3Entity> | 实体组内的实体 |
position | Box3Vector3 | 实体组中心位置. |
- Source
- Type:
- EntityGroup
(inner) nullc(a, b) → {*}
空值合并
| Name | Type | Description |
|---|---|---|
a | * | |
b | * |
- Source
- Type:
- *
(inner) copyObject(obj) → {any}
复制一个object
| Name | Type | Description |
|---|---|---|
obj | any | 要复制的 |
- Source
- Type:
- any
(inner) getEntity(id) → {Box3Entity}
使用实体ID获取一个实体
| Name | Type | Description |
|---|---|---|
id | string | 实体ID |
- Source
- Type:
- Box3Entity
(inner) getEntities(tag) → {Array.<Box3Entity>}
使用实体标签获取一组实体
| Name | Type | Description |
|---|---|---|
tag | string | 实体标签 |
- Source
- Type:
- Array.<Box3Entity>
(inner) getPlayer(value, key) → {Box3PlayerEntity|undefined}
通过玩家的昵称/BoxID/userKey找到一个玩家
如果没有找到，返回undefined
也可以在key参数中填入其他的东西，但不建议，因为可能有多个玩家满足该条件
判断方法：
entity.player[key] == value
| Name | Type | Default | Description |
|---|---|---|---|
value | * | 见上 | |
key | string | name | 见上，一般填入 |
- Source
- Type:
- Box3PlayerEntity |
undefined
(inner) getTheCodeExecutionLocation() → {Object}
获取当前代码的执行位置
- Source
- Type:
- Object
(inner) output(type, …data) → {string}
输出一段日志，并记录到日志文件中
| Name | Type | Attributes | Description |
|---|---|---|---|
type | 'log' | | 输出类型 | |
data | string | <repeatable> | 要输出的内容 |
- Source
- Type:
- string
(inner) throwError(…data)
抛出错误
| Name | Type | Attributes | Description |
|---|---|---|---|
data | string | <repeatable> | 错误内容 |
- Source
(inner) isAdmin(entity) → {boolean}
通过管理员列表，判断一个玩家是不是管理员
注意：对于在运行过程中添加的管理员（即entity.player.isAdmin为true但管理员列表中没有该玩家的userKey，返回false
对于这种情况，应该使用：
entity.player.isAdmin
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要判断的实体 |
- Source
- Type:
- boolean
(inner) setAdminStatus(entity, type)
设置一个玩家是否是管理员
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要设置的玩家 |
type | boolean | 是否设置为管理员 |
- Source
(inner) resizePlayer(entity, size)
缩放一个玩家，包括玩家的移动速度&跳跃高度
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要缩放的玩家 |
size | number | 缩放尺寸 |
- Source
(inner) createEntity(mesh, position, collides, gravity, meshScale, meshOrientation) → {Box3Entity|null}
简单创建一个实体（其实也没简单到哪去）
| Name | Type | Description |
|---|---|---|
mesh | string | 实体外形 |
position | Box3Vector3 | 实体位置 |
collides | boolean | 实体是否可碰撞 |
gravity | boolean | 实体是否会下落 |
meshScale | Box3Vector3 | 实体的缩放比例 |
meshOrientation | Box3Quaternion | 实体的旋转角度 |
- Source
- Type:
- Box3Entity |
null
(async, inner) textDialog(entity, title, content, hasArrow, otherOptions) → {'success'|number|null}
弹出一个/若干个文本对话框
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要弹出对话框的玩家 |
title | string | 对话框的标题 |
content | string | | 对话框的正文，也可以输入一个列表来实现多个对话框依次弹出（相当于一个低配版的 |
hasArrow | 'auto' | | 是否显示箭头提示， |
otherOptions | object | 对话框的其他选项 |
- Source
如果完成了所有对话，则返回success（只有一个对话框）或者完成对话框的数量（有多个对话框）；否则返回null（只有一个对话框）
- Type:
- 'success' |
number | null
(async, inner) inputDialog(entity, title, content, confirmText, placeholder, otherOptions) → {string|null}
弹出一个输入对话框
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要弹出对话框的玩家 |
title | string | 对话框的标题 |
content | string | 对话框的正文 |
confirmText | undefined | | 可选，确认按钮文字 |
placeholder | undefined | | 可选，输入框提示文字 |
otherOptions | object | 对话框的其他选项 |
- Source
输入框填写的内容字符串
- Type:
- string |
null
(async, inner) selectDialog(entity, title, content, options, otherOptions) → {Box3DialogSelectResponse}
弹出一个选项对话框
| Name | Type | Description |
|---|---|---|
entity | Box3PlayerEntity | 要弹出对话框的玩家 |
title | string | 对话框的标题 |
content | string | 对话框的正文 |
options | Array.<string> | 选项列表 |
otherOptions | object | 对话框的其他选项 |
- Source
玩家选择的选项
- Type:
- Box3DialogSelectResponse
(inner) shuffleTheList(oldList) → {Array.<any>}
打乱一个列表
| Name | Type | Description |
|---|---|---|
oldList | Array.<any> | 要打乱的列表 |
- Source
- Type:
- Array.<any>
(inner) random(min, max, integer) → {number}
随机生成一个数
| Name | Type | Default | Description |
|---|---|---|---|
min | number | 0 | 生成范围的最小值 |
max | number | 1 | 生成范围的最大值 |
integer | boolean | false | 是否生成一个整数 |
- Source
- Type:
- number
(inner) toChineseDate(date) → {string}
将Unix时间戳转换为中文日期
| Name | Type | Description |
|---|---|---|
date | number | Unix时间戳 |
- Source
- Type:
- string
toChineseDate(Date.now())(async, inner) executeSQLCode(code) → {any}
执行一段SQL命令
仅在旧岛中使用
| Name | Type | Description |
|---|---|---|
code | string |
- Source
- Type:
- any
(async, inner) tryExecuteSQL(func, msg)
尝试执行SQL代码
| Name | Type | Description |
|---|---|---|
func | function | 要执行的代码 |
msg | string | 当代码执行失败时，输出的信息 |
- Source
(async, inner) getDataStorage(key) → {DataStorage}
连接指定数据存储空间，如果不存在则创建一个新的空间。
| Name | Type | Description |
|---|---|---|
key | string | 指定空间的名称，长度不超过50个字符 |
- Source
- Type:
- DataStorage
(async () => {
await EasyBox3Lib.storage.getDataStorage('test');
})();(inner) getDataStorageInCache(storageKey) → {DataStorage}
在缓存中直接获取指定数据存储空间
比getDataStorage更快，但不能创建数据存储空间
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定数据存储空间名称 |
- Source
- Type:
- DataStorage
await EasyBox3Lib.storage.getDataStorage('test');
var playerStorage = EasyBox3Lib.storage.getDataStorageInCache('test');(async, inner) setData(storageKey, key, value)
设置一个键值对
与DataStorage.set方法不同，该方法调用后不会立即写入数据，而是移动到Storage Queue中
建议添加 await
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定空间的名称，不需要提前获取空间 |
key | string | 需要设置的键 |
value | string | 需要设置的值 |
- Source
await EasyBox3Lib.storage.setData('test', entity.player.userKey, {
money: entity.player.money,
experience: entity.player.experience,
itemList: entity.player.itemList.toString(),
});(async, inner) getData(storageKey, key) → {ReturnValue}
查找一个键值对
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定空间的名称，不需要提前获取空间 |
key | string | 指定的键 |
- Source
- Type:
- ReturnValue
var data = await EasyBox3Lib.storage.getData('test', entity.player.userKey);(async, inner) listData(storageKey, options) → {QueryList}
批量获取键值对注意：该方法不会创建缓存和读取缓存，所以比 目前在完全缓存的情况下可以在此使用缓存，需要更改配置文件get更慢
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定空间的名称，不需要提前获取空间 |
options | ListPageOptions | 批量获取键值对的配置项 |
- Source
- Type:
- QueryList
var datas = await EasyBox3Lib.storage.listData('test', {cursor: 0});(async, inner) removeData(storageKey, key)
删除表中的键值对 与DataStorage.remove方法不同，该方法调用后不会立即写入数据，而是移动到Storage Queue中
建议添加 await
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定空间的名称，不需要提前获取空间 |
key | string | 指定的键 |
- Source
await EasyBox3Lib.storage.removeData('test', entity.player.userKey);(async, inner) dropDataStorage(storageKey)
删除指定数据存储空间
警告：删除之后无法恢复，请谨慎使用！！！
不支持Arena，只支持旧岛
| Name | Type | Description |
|---|---|---|
storageKey | string | 指定数据存储空间，不需要提前获取空间 |
- Source
await EasyBox3Lib.storage.dropDataStorage('player');(inner) createGameLoop(name, callbackfn)
创建游戏循环
需要手动调用runGameLoop运行
| Name | Type | Description |
|---|---|---|
name | string | 循环名称 |
callbackfn | EventCallBack | 要执行的函数。提供一个参数：time，代表循环执行的次数 |
- Source
EasyBox3Lib.createGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});(async, inner) startGameLoop(name, callbackfn)
创建并运行游戏循环
如果循环已存在，则直接运行循环
| Name | Type | Description |
|---|---|---|
name | string | 循环名称 |
callbackfn | EventCallBack | | 要执行的函数。提供一个参数：time，代表循环执行的次数。如果为空且循环存在，则继续循环 |
- Source
EasyBox3Lib.startGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});EasyBox3Lib.createGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});
EasyBox3Lib.startGameLoop('test1');(inner) stopGameLoop(name)
停止游戏循环
该游戏循环可能不会立即停止，而是在当前循环运行完后真正停止
| Name | Type | Description |
|---|---|---|
name | string | 循环名称 |
- Source
EasyBox3Lib.startGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});
EasyBox3Lib.stopGameLoop('test1');
//这个例子可能不是很好，因为设计的时候就没想过这么用，比这个复杂多了，参见Storage Queue的实现(async, inner) runGameLoop(name)
运行游戏循环
| Name | Type | Description |
|---|---|---|
name | string | 循环名称 |
- Source
EasyBox3Lib.createGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});
EasyBox3Lib.runGameLoop('test1');(inner) deleteGameLoop(name)
删除游戏循环，之后不能再对该循环进行操作
如果循环正在运行中，那么循环结束后才会删除
| Name | Type | Description |
|---|---|---|
name | string | 循环名称 |
- Source
EasyBox3Lib.createGameLoop('test1', async (time) => {
await world.nextChat();
EasyBox3Lib.output('log', '第', time, '次收到消息');
});
EasyBox3Lib.deleteGameLoop('test1');//刚创建还没运行就删除（）
//这个例子可能不是很好，因为设计的时候就没想过这么用，比这个复杂多了，参见Storage Queue的实现(inner) registerEvent(name)
注册一个事件
| Name | Type | Description |
|---|---|---|
name | string | 事件名称 |
- Source
registerEvent('testEvent');(inner) addEventHandler(eventName, handler)
添加事件监听器
不可使用此方法注册onTick事件
| Name | Type | Description |
|---|---|---|
eventName | string | 事件名称 |
handler | EventCallBack | 事件监听器 |
- Source
EasyBox3Lib.registerEvent('testEvent');
EasyBox3Lib.addEventHandler('testEvent', () => {
output("log", '触发事件');
});EasyBox3Lib.addEventHandler('onStart', () => {
EasyBox3Lib.output('地图启动成功');
});
EasyBox3Lib.addEventHandler('onPlayerJoin', ({ entity }) => {
world.say('欢迎', entity.player.name, '加入地图！');
});(async, inner) triggerEvent(eventName, data)
触发一个事件
| Name | Type | Description |
|---|---|---|
eventName | string | 事件名称 |
data | object | 监听器使用的参数 |
- Source
EasyBox3Lib.registerEvent('testEvent');
EasyBox3Lib.addEventHandler('testEvent', () => {
EasyBox3Lib.output("log", '触发事件');
});
EasyBox3Lib.triggerEvent('testEvent');EasyBox3Lib.registerEvent('testEvent');
EasyBox3Lib.addEventHandler('testEvent', ({ data }) => {
EasyBox3Lib.output("log", '触发事件 data =', data);
});
EasyBox3Lib.triggerEvent('testEvent', { data: 114514 });(inner) removeEvent(eventName)
移除一个事件，之后不能监听该事件
| Name | Type | Description |
|---|---|---|
eventName | string | 事件名称 |
- Source
(inner) onTick(handler, tpc, performanceImpact, enforcement) → {OnTickHandlerToken}
注册一个onTick事件，类似于Box3中的onTick事件，但有一些优化
需要在预处理时注册
| Name | Type | Default | Description |
|---|---|---|---|
handler | onTickEventCallBack | 要执行的函数 | |
tpc | number | 每个循环的执行次数（times per cycles） | |
performanceImpact | number | 1 | 性能影响程度 |
enforcement | boolean | false | 如果为false，则如果上一次未执行完，则不会执行 |
- Source
- Type:
- OnTickHandlerToken
EasyBox3Lib.onTick(({ tick }) => {
EasyBox3Lib.output("log", 'tick', tick);
}, 16);(inner) preprocess(callbackfn, priority)
添加预处理函数
| Name | Type | Description |
|---|---|---|
callbackfn | preprocessCallback | 要执行的函数 |
priority | number | 优先级，值越大越先执行 |
- Source
EasyBox3Lib.preprocess(() => {
EasyBox3Lib.output("log", '这是一个预处理函数，会第一个执行');
}, 2);
EasyBox3Lib.preprocess(() => {
EasyBox3Lib.output("log", '这是一个预处理函数，会第二个执行');
}, 1);
EasyBox3Lib.preprocess(() => {
EasyBox3Lib.output("log", '优先级甚至可以是负数和小数！');
}, -114.514);(async, inner) planningOnTickEvents()
规划onTick事件
一般不需要自行调用
- Source
(async, inner) start()
启动地图（执行预处理函数）
- Source
EasyBox3Lib.start();EasyBox3Lib.addEventHandler('onStart', () => {
EasyBox3Lib.output('地图启动成功');
});
EasyBox3Lib.addEventHandler('onPlayerJoin', ({ entity }) => {
world.say('欢迎', entity.player.name, '加入地图！');
});
EasyBox3Lib.start();(inner) changeVelocity(velocity, time)
转换速度单位
把velocity/time转换为result/64ms
公式为：
result = velocity * time / 64
| Name | Type | Description |
|---|---|---|
velocity | number | 移动的速度，每 |
time | number | 速度的单位时间，单位：ms。默认为1s |
- Source
changeVelocity(1, 1000); // 1格/schangeVelocity(299792458, 1000); // 光速，299792458格/s(inner) registerItem(item) → {boolean}
注册一种物品
如果成功注册物品，返回true，否则返回false
| Name | Type | Description |
|---|---|---|
item | Item | 要注册的物品 |
- Source
- Type:
- boolean
(inner) startStorageQueue()
启动Storage Queue
只有启动了Storage Queue，setData和removeData的任务才会被处理
- Source
(inner) stopStorageQueue()
停止Storage QueuesetData和removeData仍会将任务放到队列中，但不会再次处理，除非运行startStorageQueue
- Source
EasyBox3Lib.stopStorageQueue();(inner) translationError(message) → {string}
翻译报错信息
| Name | Type | Description |
|---|---|---|
message | string | 报错内容 |
- Source
翻译后的信息
- Type:
- string
(inner) register(any)
万用注册函数
| Name | Type | Description |
|---|---|---|
any | any | 你要注册的东西 |
- Source
EasyBox3Lib.register(new EasyBox3Lib.Item('豆奶', '豆奶', 16, ['食物'], undefined, { recovery: 6 }));EasyBox3Lib.register(new BehaviorLib.Behavior("findAttackTarget", (self, data) => {
self.attackTarget = world.querySelectorAll(data.selector).filter(data.filter)[0];
}, 1));(inner) registerRegistryClassIndex(fn)
注册注册函数类别索引
满足any instanceof type时调用fn(any)
| Name | Type | Description |
|---|---|---|
fn | function |
- Source
EasyBox3Lib.registerRegistryClassIndex(EasyBox3Lib.Item, registerItem);(inner) spiltWord(word) → {Array.<string>}
根据大小写和符号，拆分单词
| Name | Type | Description |
|---|---|---|
word | string |
- Source
- Type:
- Array.<string>
(inner) createEntityGroup(entities, position) → {EntityGroup}
创建一个实体组
更改entities中每个实体的indexInEntityGroup属性为该实体在实体组内的编号
| Name | Type | Description |
|---|---|---|
entities | Array.<Box3Entity> | 实体组内的实体 |
position | Box3Vector3 | 实体组中心位置. |
- Source
- Type:
- EntityGroup
Type Definitions
EventCallBack(data) → {void}
事件回调函数
| Name | Type | Description |
|---|---|---|
data | any | 传递的参数 |
- Source
- Type:
- void
onTickEventCallBack() → {void}
onTick事件回调函数
- Source
- Type:
- void
dialogCallBack(entity, value) → {void}
对话框回调函数
| Name | Type | Description |
|---|---|---|
entity | Box3Entity | 打开对话框的实体 |
value | Box3DialogResponse | 玩家选择/输入的结果 |
- Source
- Type:
- void
dataStorageUpdateCallBack(prevValue) → {JSONValue}
DataStorage.update的回调函数
| Name | Type | Description |
|---|---|---|
prevValue | ReturnValue | 更改前的数据 |
- Source
- Type:
- JSONValue
preprocessCallback() → {void}
预处理函数回调函数
- Source
- Type:
- void
ItemSelectorString
用于选择/测试物品用的选择器
可以一次使用多个选择器，使用,分隔多个选择器，只需满足任意一个选择器
前缀为#，则检测id是否满足
前缀为.，则检测tag是否满足
前缀为!，则该选择器结果取反
添加前缀&，代表该选择器必须满足（必须是第一个字符）
如果为null，则检测物品是否为null；前缀为!时，返回所有非null物品
选择器前后不能有其他字符id的优先级比tag高
不允许有任何无意义的空格和非法字符
- string
- Source
thingStorageForEachCallback(thing, index, array)
ThingStorage.forEach回调函数
| Name | Type | Description |
|---|---|---|
thing | Thing | 物品 |
index | number | 编号 |
array | Array.<Thing> | 原数组 |
- Source
Output
Properties| Name | Type | Description |
|---|---|---|
type | string | 类型 |
data | string | 内容 |
location | Array.<any> | 代码执行位置 |
- Source
ThingString
物品（Thing）转换为string的结果
格式为：
i[id](|n[name])|s[stackSize]|d[data](|w)
例如：
itest1|n测试物品1|s114514|d{}
itest2|s1919810|d{hello: 'world!'}
- string
- Source
StorageTask
Storage任务
用于Storage Queue
| Name | Type | Description |
|---|---|---|
type | "set" | | 任务类型 |
storageKey | string | 数据储存空间名称 |
key | string | 数据键 |
value | any | 数据值 |
- Source
ThingDialogCallback(thing) → {string}
物品对话框正文内容
| Name | Type | Description |
|---|---|---|
thing | Thing | 物品 |
- Source
对话框正文内容
- Type:
- string
(async) ThingUseCallback(entity, thing, onlyUpdate)
物品被使用回调函数
| Name | Type | Description |
|---|---|---|
entity | Box3Entity | 使用物品的玩家 |
thing | Thing | 使用的物品 |
onlyUpdate | boolean | 是否只是为了更新穿戴状态而触发（ |
- Source
EventCallBack(data) → {void}
事件回调函数
| Name | Type | Description |
|---|---|---|
data | any | 传递的参数 |
- Source
- Type:
- void
onTickEventCallBack() → {void}
onTick事件回调函数
- Source
- Type:
- void
dialogCallBack(entity, value) → {void}
对话框回调函数
| Name | Type | Description |
|---|---|---|
entity | Box3Entity | 打开对话框的实体 |
value | Box3DialogResponse | 玩家选择/输入的结果 |
- Source
- Type:
- void
dataStorageUpdateCallBack(prevValue) → {JSONValue}
DataStorage.update的回调函数
| Name | Type | Description |
|---|---|---|
prevValue | ReturnValue | 更改前的数据 |
- Source
- Type:
- JSONValue
preprocessCallback() → {void}
预处理函数回调函数
- Source
- Type:
- void
ItemSelectorString
用于选择/测试物品用的选择器
可以一次使用多个选择器，使用,分隔多个选择器，只需满足任意一个选择器
前缀为#，则检测id是否满足
前缀为.，则检测tag是否满足
前缀为!，则该选择器结果取反
添加前缀&，代表该选择器必须满足（必须是第一个字符）
如果为null，则检测物品是否为null；前缀为!时，返回所有非null物品
选择器前后不能有其他字符id的优先级比tag高
不允许有任何无意义的空格和非法字符
- string
- Source
thingStorageForEachCallback(thing, index, array)
ThingStorage.forEach回调函数
| Name | Type | Description |
|---|---|---|
thing | Thing | 物品 |
index | number | 编号 |
array | Array.<Thing> | 原数组 |
- Source
Output
Properties| Name | Type | Description |
|---|---|---|
type | string | 类型 |
data | string | 内容 |
location | Array.<any> | 代码执行位置 |
- Source
ThingString
物品（Thing）转换为string的结果
格式为：
i[id](|n[name])|s[stackSize]|d[data](|w)
例如：
itest1|n测试物品1|s114514|d{}
itest2|s1919810|d{hello: 'world!'}
- string
- Source
StorageTask
Storage任务
用于Storage Queue
| Name | Type | Description |
|---|---|---|
type | "set" | | 任务类型 |
storageKey | string | 数据储存空间名称 |
key | string | 数据键 |
value | any | 数据值 |
- Source
ThingDialogCallback(thing) → {string}
物品对话框正文内容
| Name | Type | Description |
|---|---|---|
thing | Thing | 物品 |
- Source
对话框正文内容
- Type:
- string
(async) ThingUseCallback(entity, thing, onlyUpdate)
物品被使用回调函数
| Name | Type | Description |
|---|---|---|
entity | Box3Entity | 使用物品的玩家 |
thing | Thing | 使用的物品 |
onlyUpdate | boolean | 是否只是为了更新穿戴状态而触发（ |
- Source