SuperAPI AI 工具集

gaia-character

智能体与模型

查看项目

更新于 11-08 11:40

技能介绍

gaia-character 是 drawcall-ai/game-skills 中的一项技能,用途是在 three.js 场景中驱动带动画的人形角色。其角色行为由 @drawcall/acta 定义,Acta 是一种基于 JSON 的语言,用于描述人形角色的行为。

主要能力方面,该技能支持状态机与状态转场,调用时描述角色状态(例如 idle、waving)即可由 update 方法驱动;行走与奔跑动画会根据 worldMoveVelocity 的大小自动混合,无需手动切换;角色会自动旋转朝向移动方向,调用方不应手动设置 character.rotation 或使用 lookAt;支持把物品挂载到角色骨骼上(角色本身不能直接持有物品,需另行创建模型并 attach 到骨骼);支持跳跃与下落,通过 applyJump 回调与物理系统配合;支持动画事件(animationStarted、animationFinished),用于在动画结束时同步游戏状态。

使用方式上,不应自行创建角色行为,而应使用 createCharacter 工具生成角色、使用 editCharacter 修改角色;不能提供或创建动画资源,acta 工具会从自身动画库中选用合适动画,调用 createCharacter 前不要尝试创建动画文件。加载角色使用 Character.load(),每帧必须调用 character.update(delta, {...}),即使属性没有变化也要调用。使用物理时需向 Character.load() 传入 applyMove 回调,这样移动只在移动动画播放时生效,避免在 idle、攻击等非移动状态下滑动;跳跃物理需传入 applyJump 回调。内置属性 isMoving 会在 worldMoveVelocity.length() > 0 时自动计算为 true,无需手动传入。

适用场景包括需要在 three.js 中为游戏角色实现状态驱动行为的项目,尤其是需要行走/奔跑混合、骨骼挂载物品、跳跃物理以及与物理世界集成的场景。

限制方面,该技能依赖 @drawcall/acta 与 @pmndrs/viverse,示例代码还使用了 elics 等库;它不提供动画资产,动画只能使用 acta 自带库;角色不能直接持有物品,需要单独创建模型后挂载到骨骼;必须始终传递 worldMoveVelocity 并由 applyMove 决定何时实际应用。