简化引擎使用

[cloudwu]

目前 Ant Engine 的用法比较杂乱，缺乏详细的文档，很多功能只能从源码中求证。

如果只是写一些简单的 demo 的话，其实用不上太多的功能。所以我打算维护一个精简版的框架，从最基本的功能做起，争取同步提供 API 文档。因为 Ant 已有较为完善的包管理机制，所以我用一个独立 package 的形式提供，不侵入已有代码。使用者完全可以只使用精简框架提供的一组 api ，不用了解任何引擎的底层细节。

因为这个框架刚开始做，提供的功能非常有限。它比较适合做第三人称视角的 demo 。框架放在 ant.framework.demo 这个包中。以后如果有其它想法，可以再提供其它类型的框架。

使用它可参考 https://github.com/ejoy/ant/tree/master/test/demo ，启动命令行为：

bin/mingw/release/ant.txt test/demo/main.lua

运行后，会看到如下画面

这个 demo 演示了：

1. 加载所需的资源，设置光照环境
2. 设置游戏每帧更新函数
3. 控制摄像机
4. 监听鼠标键盘消息
5. 创建图形界面 HUD ，并与之交互
6. 读取配置文件

在启动文件 main.lua 中，只需要写：

import_package "ant.framework.demo".start {
	window_size = "1280x720",
	vsync = true,
	log = "info",
	path = "/code/main.lua",
	setting = "/code/config.ant",
}

其中：

• path 必填，游戏代码的入口文件。
• setting 选填，datalist 格式的配置文件，可在游戏代码中随时读取，不可修改。
• window_size 选填，初始化窗口大小。
• vsync 选填，开启垂直同步。
• log 选填，设定日志输出级别。
• profile 选填，开关性能统计。

在这个例子中，设置了配置文件 /code/config.ant

fps : 50  # 游戏运行帧率
font : 微软雅黑  # HUD 使用字体，需要和 html 文件中一致。

/code/main.lua 是入口文件，它演示了框架支持的一系列特性。

callback

入口文件必须返回一个 table (game)，里面设置必要的回调函数。其中：

function game.update()

必填项，框架每帧会调用这个函数。

function game.keyboard(key)

选填项，每次按键抬起时框架会调用它。

function game.mouse(btn, state, x, y)

选填项，每次鼠标案件按下时框架会调用它。
注：鼠标移动不会触发这个函数，关于获取鼠标位置，见下面的 API 文档。

API

require(name)

和 Lua 标准的 require 用法类似，但不支持 package.path 等设置项。

print_r

用于调试。可递归打印 table 的内容。

ant.import_prefab(name)

导入一个 prefab 文件，无返回值。通常用于导入光照信息等。

obj = ant.primitive(name, obj)

创建一个预制体，设定初始参数 obj 。返回控制器对象，直接修改控制器即可更新对象属性。

name 可以为 cube ，plane ，sphere 。

obj 为 table 其中

• x,y,z 为其空间坐标
• r 为绕 z 轴的旋转量，单位是角度
• s 为缩放比，默认为 1
• material 是材质表
  • visible 可见性
  • color 颜色，使用 24bit 整数

例：

local cube = ant.primitive("cube", { x = 0, y = 0, r = 0, z = 0.5, material = { visible = true, color = 0xff0000 } )

这可以创建一个立方体，大小为 1x1x1 。其中心点在 (0,0, 0.5) 处，并设其为可见（默认），颜色为红色。

obj = ant.prefab(name, obj)

同 ant.primitive ，但加载一个 glb 或 gltf 文件。

obj = ant.sprite2d(texture_name, obj)

同 ant.primitive ，但生成一个 2d 面片，并贴上 texture_name 指定的贴图。

ant.sprite2d_base(pixels)

设置 sprite2d 使用贴图的像素比例，默认为 128 ，即当贴图宽度为 128 像素时，在 3d 空间宽一个单位。

ant.remove(obj)

删除一个对象。

ant.maxfps(n)

设置最高帧率

ant.gui_open(html)

打开一个 html 文件作为图形界面

ant.gui_listen(message_name, callback)

监听从图形界面发来的消息

ant.gui_send(...)

像图形界面发送一个消息，不等待回应。

ant.gui_call(...)

像图形界面发送一个消息，并等待返回值。

ant.setting

如果启动时填了 setting 文件名，那么这会指向对应的表。如果未填，该项为空。

ant.key_press

查询当前键盘按键状态。例如，ant.key_press.A 为 true 时，表示 A 键按下，为 false 时，A 键抬起。

ant.mouse_state

鼠标的状态：.x .y 为鼠标光标所在屏幕坐标。.left 和 .right 为左右两个键的状态。

ant.camera_ctrl

摄像机控制器，可以通过修改这张表的项目，控制摄像机的状态：

• x y z 摄像机观察点的空间位置。
• yaw 摄像机绕 z 轴的旋转量，单位为角度
• pitch 摄像机的俯仰角，单位为角度。pitch 为 0 时，摄像机平视，为 90 时，垂直向下。
• distance 摄像机距离观察点的距离。
• min max 用来设置以上项目的取值范围。

x, y = ant.camera_ctrl.screen_to_world(x, y)

将屏幕坐标（通常是鼠标位置）换算成 XY 平面的坐标。返回值可能为空（无法转换到 XY 平面上）。

ant.gesture_listen(name, callback)

监听图形界面没有处理的手势事件。建议处理手势而不是直接处理鼠标消息。这可以和图形界面协同工作。手势会先发送给 GUI 处理，只有当 GUI 处理不了时，这个 api 才会触发回调。

callback 函数接收一个 table 参数，是手势的参数。所有手势均有参数 timestamp ，是消息发生的时间戳。

目前支持以下手势：

• tap 点击：x y 为 tap 发生时的坐标。
• longpress 长按：x y 为坐标；state 为状态值：began 或 ended
• pan 平移（拖动）：x y 为坐标；state 为状态值：began ended 或 changed；velocity_x velocity_y 为速度。
• pinch 缩放（鼠标滚轮）：x y 为坐标，velocity 为速度。

ant.show_debug(enable)

开关 debug 文本显示

ant.print(obj, text)

在 obj 的屏幕所谓位置输出 text 。需要把 show_debug 打开。

ant.profile_enable(enable)

在 debug 文本中列出性能分析数据。

[xsxz01]

关注了

[ylme]

手机码字，就简单反馈一下。
我觉得 ant 的第一个产品目标可以是，让有经验的程序员独立做游戏。
基于此，由于是面向程序，日常的工作流就是：

1. 用编辑器去创建或修改 prefab 。（就是云大说的创建游戏数据）
2. 编写 gameplay 逻辑并在此中熟悉引擎 API 。（就是这篇 blog 想解决的问题）
3. 用美术资源进行包装。（ UI 资源，特效资源，模型资源，以及 shader 优化渲染表现）

这几天周末空闲时跑了一下 ant 的 simple 例子，特别又把 deepspace 那个仓库也运行起来了，就是没有找到怎么通过编辑器修改已有的 entity 。然后之前提了 Fail to running editor test/simple 那里发现，无论是 simple 还是 deepspace ，setting 文件的 effect 的 enable 都是 false ，这样运行 editor 会有报错，改成 true 时 editor 能运行，但是游戏又显示异常。即使 editor 能运行，也是一个空场景，还是未能成功修改 prefab 数据。
就我个人而言，挺希望我上面提到的工作流第一步能有文档或示例能参考跑通这一步。
第三步暂时还没有到这一步，等后面到这一步了再具体沟通。

还有 ant 现阶段是不是可以创一个电报群或者 discord 群来实时沟通一些报错信息呢？我个人觉得有个群沟通会挺好的，有需要的话我可以创一个电报或者 discord 。

[cloudwu]

1. setting effect 的 bug 今天应该已经修了。
2. 我最近没怎么跑编辑器，所以编辑器可能问题比较多。编辑器主要由 @aimoonchen 实现，因为现在不是全职工作了，他其他工作可能比较忙。等我把手头游戏 demo 再往下做一点后，我会回头来熟悉编辑器的代码，争取可以自己维护。
3. 文档也是一样的问题。需要晚一点有精力来写。其实我自己因为不是 100% 熟悉所有细节，我在开发中也会遇到很多问题。正好借弄清楚的机会，理解哪些点是最需要文档的。（注：除了读代码，通常我会在 https://github.com/ejoy/vaststars 找对应用法）
4. 因为过去全职工作时，我们在阿里使用钉钉。现在部分同学还在阿里工作（但正职不做这个项目），所以关于引擎开发，我们还在继续用钉钉沟通。有需要可以私下找我要钉钉群的邀请。我们有一个 discord 群，但是不是每个人都常开。暂时我觉得在 discussion 贴报错信息也问题不大。

[ylme]

大概了解了 ant 现状后，我觉得我自己可以调换一下我自己想象的工作流也就行了。先去写了解如何去写 gameplay 逻辑，这样也有助于了解引擎的基本结构。由于近期一段时间工作很忙，也就只有周日有空玩玩，所以这一块儿也会用相当长一段时间了，过程中手工改写已经有的 prefab 文本也未尝不可。之后再考虑如何用 editor 创建和修改 prefab ，做些复杂的表现。

[tzngit]

1. setting effect 的 bug 今天应该已经修了。
2. 我最近没怎么跑编辑器，所以编辑器可能问题比较多。编辑器主要由 @aimoonchen 实现，因为现在不是全职工作了，他其他工作可能比较忙。等我把手头游戏 demo 再往下做一点后，我会回头来熟悉编辑器的代码，争取可以自己维护。
3. 文档也是一样的问题。需要晚一点有精力来写。其实我自己因为不是 100% 熟悉所有细节，我在开发中也会遇到很多问题。正好借弄清楚的机会，理解哪些点是最需要文档的。（注：除了读代码，通常我会在 https://github.com/ejoy/vaststars 找对应用法）
4. 因为过去全职工作时，我们在阿里使用钉钉。现在部分同学还在阿里工作（但正职不做这个项目），所以关于引擎开发，我们还在继续用钉钉沟通。有需要可以私下找我要钉钉群的邀请。我们有一个 discord 群，但是不是每个人都常开。暂时我觉得在 discussion 贴报错信息也问题不大。

我也打算学习使用下ant，云大求一个钉钉群的邀请链接(我去年从灵犀出来了) 链接可以发[email protected]么？

[constly]

能不能提升下日志刷新频率（或者提供一个可以修改的接口），目前大概是0.5秒左右刷一次，在通过观察日志调试逻辑的时候（或者点击某个按钮打印一条输出）不太方便，体验类似于顶着300ms的延迟在开发游戏 = =

[constly]

100ms的体感我感觉倒没啥问题，现在主要问题是，如果没日志，ltask就会sleep 1秒，如果在这期间产生了日志，就会有非常明显的延迟。看起来是改漏了，需要把sleep的默认值改为10，或者writelog函数固定返回10~

[cloudwu]

我觉得偶尔慢一点无所谓吧。如果 log 频繁输出，就让它响应高频一点，如果不频繁，低延迟我觉得问题不大。 sleep 1s ，应该是平均等待 500ms 。

之前我们在手机上做性能测试，似乎 log 服务太高频会浪费一些电。

[cloudwu]

我埋了一个接口，需要的时候可以改 efdba12

[constly]

好的。我对这个比较执着是因为，假设这样的场景：在角色碰到某个区域时输出日志。如果这个输出有比较明显的延迟，会让做功能的人崩溃，可能怀疑是不是自己碰撞检查写得有问题等等之类的。我觉得这个延迟参数编辑器和真机就应该是不一样的。

[cloudwu]

如果需要关注时间差，要看 log 里的时间戳，那个是按写 log 的时间标注的，而不是 log 输出的时刻。

比方说你按了鼠标触发功能，然后功能写 log ，那么，鼠标操作本身也应该写 log 。这样才好比较时间戳。

[constly]

我想到一个问题。wiki中对RmlUI的介绍有这样一段话：

注：游戏界面模块工作在 ltask 的一个独立服务中，和游戏的主服务是隔离的，它不是 ecs 的一部分。

这是不是意味中场景与UI的更新频率是不一致的。
假如我们要在UI上显示场景中Npc的名字，且Npc处于不断移动中，名字在视觉上会不会出现拉扯的情况呢？（因为两边更新频率不一致）
当然这是我目前脑补可能出现的情况，我还没去验证这个问题。

[cloudwu]

目前是一致的，它们在 bgfx 的刷新服务中同步。