kons-9动画系统完全指南：ANIMATOR、SHAPE-ANIMATOR与MOTION-GROUP时间轴调度详解-育师

kons-9动画系统完全指南：ANIMATOR、SHAPE-ANIMATOR与MOTION-GROUP时间轴调度详解

【免费下载链接】kons-9Common Lisp 3D Graphics Project项目地址: https://gitcode.com/gh_mirrors/ko/kons-9

kons-9 是一个用 Common Lisp 编写的 3D 计算机图形学与动画系统。本文面向新手，完整、易懂地拆解 kons-9 的动画系统：MOTION 如何掌管时间轴、ANIMATOR 与 SHAPE-ANIMATOR 如何驱动形状运动、MOTION-GROUP 如何编排并排与顺序动画，并给出安装运行步骤，帮助你快速做出第一个 3D 动画。

🧩 如何理解 kons-9 动画架构：场景的“双树结构”

kons-9 中的每个场景（SCENE）同时管理两棵独立层级树（见src/kernel/scene.lisp）：

形状树（shape-root）：存放立方体、网格、组等 3D 几何
运动树（motion-root）：存放所有动画对象（MOTION）

核心类的继承关系如下（完整说明见doc/kernel-overview.md）：

ITEM ├── SCENE └── SCENE-ITEM ├── SHAPE（几何对象）… └── MOTION（运动基类） ├── MOTION-GROUP（运动组） └── ANIMATOR（动画执行器） └── SHAPE-ANIMATOR（形状动画器）

这与传统 DCC 软件的理念一致：几何与动画分离，动画通过引用绑定到形状上。

场景的时间轴按“帧”管理，关键参数有start-frame、end-frame、current-frame、fps（默认 24）。全局时钟只有一个：current-time = current-frame / fps，整个动画系统的所有时间判断都基于它。

⏱️ MOTION 的 5 个核心时间属性与调度原理

MOTION 是全部运动对象的基类，定义在src/kernel/motion.lisp，只有 5 个时间属性：

属性	默认值	作用
`start-time`	0.0	开始时间（秒）
`duration`	1.0	持续时长，`nil`表示无限
`is-active?`	t	启用 / 暂停开关
`timing-mode`	`:relative-to-parent`	时间计算模式
`local-time`	0.0	归一化进度 0~1（系统写入）

两种计时模式是调度的关键

:relative-to-parent（相对父区间）：本运动的开始与时长都相对于父时间区间计算，相当于在父时间轴内再开一条“子时间轴”，可以无限嵌套；
:absolute-time（绝对时间）：直接使用绝对秒数，不受父级缩放影响。

每帧渲染时，系统从运动树根节点向下递归，把每个节点换算成绝对时间窗口；只有当前全局时钟落在这个窗口内（in-time-interval?判断通过），才会执行该运动的更新函数，并把local-time写成 0→1 的归一化进度。场景本身作为“根时间轴”，其起点与时长就是帧区间换算出的秒数。

常用的调度辅助方法有三个：

(set-timing motion 0.5 2.0) ;; 0.5 秒开始，持续 2 秒 (offset-start-time motion 1.0) ;; 整体后移 1 秒 (scale-duration motion 0.5) ;; 时长压缩一半（变快 2 倍）

⚙️ ANIMATOR 详解：setup / update 双回调执行器

ANIMATOR 是“可执行动画”的基类（src/kernel/animator.lisp），只有两个函数槽：

setup-fn：初始化回调，在动画首次进入时间窗口时执行一次（惰性初始化，未到时间不空耗）；
update-fn：帧回调，只要运动处于时间窗口内，每帧都执行。

它适合驱动“与具体几何无关”的状态。例如test/demo-animation.lisp中用当前帧号切换多帧 OBJ 模型的可见索引，实现序列变形：

(make-instance 'animator :setup-fn (lambda () (setf (visible-index group) 0)) :update-fn (lambda () (setf (visible-index group) (current-frame *scene*))))

🎬 SHAPE-ANIMATOR：如何让 3D 形状随时间运动

SHAPE-ANIMATOR 在 ANIMATOR 基础上增加两个槽：

shape：被驱动的 3D 对象；
data：自定义数据表，用anim-data按键读写。

它的帧回调会收到动画器自身作为参数，因此可以用(local-time anim)（0~1 进度）驱动任何变换。test/demo-animation.lisp的开场示例就是让一个锥体在动画区间内自旋 1440°：

(make-instance 'shape-animator :scene *scene* :shape top :update-fn (lambda (anim) (setf (angle xform-op-spin) (lerp (local-time anim) 0 1440))))

💡缓动曲线与 Channel：kons-9 内置 10 大类缓动函数——sine、quad、cubic、quart、quint、exp、circ、elastic、back、bounce，每类都有in/out/in-out三种变体（源码见src/plugins/channel.lisp）。配合procedural-channel，可以把进度采样成“动画参数”：

(defparameter *channel* (make-instance 'procedural-channel :value-fn #'out-elastic-fn)) ;; 在 update-fn 中使用 (let ((val (get-value *channel* (local-time anim)))) (scale-to (shape anim) (p! val val val)))

示例中同一条out-elastic-fn通道同时驱动立方体缩放、八面体旋转与二十面体平移——同一缓动，三种效果，这正是通道设计的价值。

📋 MOTION-GROUP 调度法：并排、顺序、随机一键排布

MOTION-GROUP 是动画分组（src/kernel/motion-group.lisp），它既是一个 MOTION（可被放进更大的时间轴），也是容器。系统内置三种编排方法：

方法	效果	典型用途
`parallel-order`	所有子运动同时占满 [start, start+duration]	旋转 + 平移同时进行
`sequential-order`	子运动按顺序等分时长接力	镜头接力、连续动作
`random-order`	随机开始点与时长（限范围内）	自然的氛围运动

(let ((group (make-motion-group (list anim-a anim-b)))) (parallel-order group 0.0 1.0) ; 两个动画同时开始 (add-motion *scene* group))

由于子运动区间默认“相对父区间”，整组动画放进大时间轴后可以整体移位、整体伸缩，就像剪辑软件里选中一段轨道拖动一样。

🚀 新手上手步骤：安装并运行 kons-9 动画窗口

1️⃣ 获取代码（需要 SBCL，支持 macOS / Linux / Windows）：

git clone https://gitcode.com/gh_mirrors/ko/kons-9 cd kons-9

2️⃣ 在 SBCL 交互环境中加载系统并打开 3D 窗口：

(push (uiop:getcwd) ql:*local-project-directories*) (ql:quickload "kons-9") (in-package :kons-9) (run)

3️⃣ 打开test/demo-animation.lisp，从上到下逐段评估代码，即可在窗口中看到锥体旋转、缓动曲线网格与弹性缩放动画。

📁核心文件速查：

时间轴与运动基类：src/kernel/motion.lisp
动画执行器与形状动画器：src/kernel/animator.lisp
运动组调度：src/kernel/motion-group.lisp
场景与帧循环：src/kernel/scene.lisp
缓动函数与通道：src/plugins/channel.lisp
物理动画器（重力、碰撞）：src/plugins/dynamics-animator.lisp
弹簧柔性变形：src/plugins/flex-animator.lisp
完整示例：test/demo-animation.lisp

❓ 新手常见问题：3 个高频动画问题

Q1：ANIMATOR 和 SHAPE-ANIMATOR 到底选哪个？A：纯函数式的逐帧回调、操作非几何状态（如切换序列帧）用 ANIMATOR；需要改动某个具体 3D 对象的变换时用 SHAPE-ANIMATOR。

Q2：形状不运动，应该检查什么？A：按顺序排查：① 是否用add-motion挂进了场景的运动树；②is-active?是否为t；③ 当前帧是否已进入start-time/duration窗口；④ 放在组里时timing-mode是否为默认的:relative-to-parent。

Q3：想让动画“放得更慢”怎么办？A：三个手段：提高fps拉长时间轴；用scale-duration放大某段运动的时长；或把场景end-frame调大。