第一次看到 MiroFish 这个名字我脑子里蹦出来的画面是一缸不受控制的鱼——每条鱼只看得见身边巴掌大的范围没有总指挥没有全局地图可整群鱼却能在零点几秒内同时转向像一块会呼吸的绸缎。MiroFish 就是冲着这件事来的一个用群体智能思路做的鱼群模拟与可视化项目核心是把个体只懂几条傻规则整体却能涌现出高级行为这件事从抽象概念变成屏幕上看得见、参数拧得动、代码抄得走的东西。它可以用来做游戏 NPC 的集群行为、数据可视化里的流动意象、教学演示中的涌现现象、甚至艺术装置里的实时生成画面。适合两类人一类是刚接触 Agent 仿真、想找个不到五百行就能跑通的项目练手的新手另一类是已经在做实时图形或仿真系统、需要一套稳定的邻域查询和转向力结算方案的老手。我会把 MiroFish 的设计取舍、核心算法、参数怎么算、性能怎么抠、坑怎么填全部摊开讲一遍。1. MiroFish 到底在解决什么问题1.1 从一缸真鱼说起个体简单群体复杂养过鱼的人都会注意到一件事你往缸里撒一把饲料鱼群不会像士兵一样排队冲过去而是先散、再聚、再整体平移路线上带着一点犹豫和一点随机。这种整体有序、局部混乱的状态用传统的方式去写代码非常难受。如果你尝试用一条全局路径去指挥每一条鱼立刻会遇到三个麻烦第一全局路径无法应对动态障碍一旦有新的捕食者或者突然出现的边界整条路径作废第二计算量会随着鱼的数量线性甚至更高地增长因为每条鱼都要维护自己的目标第三也是最要命的写出来的动画假——每条鱼的运动轨迹过于干净没有那种互相挤压、临时让位、转身时尾巴甩一下的自然感。MiroFish 的思路是从源头换掉这件事不给任何一条鱼全局信息每条鱼只做三件极小的事剩下的交给涌现。这三件事就是经典 Boids 模型里的分离Separation、对齐Alignment和聚合Cohesion。分离让鱼不要撞到邻居对齐让鱼和邻居保持大致相同的方向聚合让鱼往邻居的中心靠。三条规则各自都很笨但叠在一起之后鱼群会自己长出绕障、分流、收拢、绕圈这些谁也没写进代码的行为。我用一句话概括 MiroFish 的价值它把复杂行为从复杂规则里解放出来改用简单规则 大量个体 局部交互来生成。这个思路一旦掌握你再看鸟群、蚁群、车流、人群疏散、粒子特效会发现背后是同一套骨架。这是我认为它比很多效果炫酷但看完学不到东西的演示项目更值得动手的原因。1.2 适合谁上手又能落到哪些真实场景先说适合谁。如果你是刚学完面向对象、想找个能立刻看到画面的项目MiroFish 的门槛很低——一个 Agent 类、一个主循环、几十行向量运算就能跑起来。如果你已经在做 Unity、Godot、或者 Web 端的 Canvas/WebGL 项目MiroFish 更像一份可以直接移植的行为层参考转向力怎么结算、邻域怎么查、边界怎么处理这三块在任何实时集群系统里都是绕不开的。如果你是做数据可视化或者交互艺术的MiroFish 提供的是活的素材——同样的画面里光标的移动可以成为一股外力把鱼群推开或者吸引过来交互感和叙事性都很强。再说落地场景。游戏里最常见的是鱼群、鸟群、蝙蝠群、虫群这类环境生物它们不需要复杂 AI但必须看起来成群影视和广告里的预演镜头需要快速生成大量群集运动MiroFish 这套参数化的做法改几个数就能出不同风格城市交通和人群疏散仿真里行人之间的避让、跟随、聚集和 Boids 是同一个数学结构只是把鱼换成人、把速度上限换成步行速度另外像粒子系统、流体近似、噪声场驱动的抽象动画也都能借这套骨架。说白了凡是很多个体、各自只有局部视野、整体要有秩序的场景MiroFish 都是那个可以拿来铺底的模板。注意MiroFish 不是物理引擎它做的是行为近似而不是刚体精确碰撞。如果你需要的是精确到毫米的碰撞响应请把 Boids 当作上层行为层碰撞交给物理引擎去处理两者分工不要混在一起算。2. 核心思路拆解三条规则怎么撑起一整群鱼2.1 分离、对齐、聚合的直觉解释与力的叠加把三条规则翻译成人话大概是这样的。分离如果我离邻居太近我就往反方向挪一点这是保命。对齐我看周围邻居大致朝哪走就把自己的方向往那个平均方向拧一点这是随大流。聚合我看看周围邻居的重心在哪往那边靠一点这是别掉队。三条规则的输出都是转向力steering force也就是一个向量表示我希望自己的速度朝这个方向改多少。把它们按权重加权求和得到这一帧的总转向力再把它加到速度上最后用速度更新位置。这里有个很关键的认知这三条规则输出的是加速度而不是位置。新手最常犯的错误是直接改位置——x (center_x - x) * 0.1。这么写也能动但动出来的东西像被橡皮筋拴住一抽一抽的速度不连续没有惯性。正确做法是让力去改速度、让速度去改位置中间夹一层速度钳制和转向力钳制。有了这一层鱼群的运动才会带上游的感觉——有加速、有滑行、有减速。另外三条规则的权重不是随便给的。我的经验值是分离明显偏重对齐中等聚合稍轻。原因很简单分离是对不自然最敏感的规则一旦分离权重不够鱼会叠在一起变成一坨而聚合权重过大鱼群会塌成一个点然后绕着中心疯狂打转看起来像漩涡而不是鱼群。对齐权重给太高整个群会变成一块僵硬的板子所有鱼像被冻住方向一样整齐失去生命感。2.2 为什么不做全局最优而是坚持局部规则这里必须解释一个为什么因为它是 MiroFish 全部设计选择的根。假设你给每条鱼一个全局目标点让它算最短路径会发生什么在静态环境里确实能得到最优路线但鱼群是一个高动态耦合系统每条鱼都在动每条鱼的动又会改变别人的邻域整个系统的状态每一帧都在变。这时候最优这个词是失效的因为你在为上一帧算最优等算完环境已经变了。硬追最优的结果就是所有鱼抢同一条路线挤成一团然后抖动。局部规则的好处是每次决策只依赖一小块邻域计算稳定、响应快、天然分布式。它不追求最优追求的是鲁棒。这个取舍在工程上非常典型分布式系统的局部启发式往往比中心化的全局求解更适合实时场景。MiroFish 选了后者所以它能跑几千上万个体而不崩也能随便加障碍、加外力、加捕食者而不需要重算任何东西。提示别把局部理解成短视。局部规则叠加后产生的宏观行为在统计意义上是稳定的你会看到鱼群自然地绕过障碍、自然地分流、自然地重新聚合。这正是群体智能最有意思的地方。2.3 感知半径与分离半径两个参数决定群的整体气质MiroFish 里有几个半径参数很多人第一次调的时候会随手写同一个值结果就是鱼群要么散沙要么铁板。这两个半径的分工必须分清。参数作用调大的后果调小的后果我的常用值2D单位像素感知半径 perception决定了谁算我的邻居对齐和聚合都在这个范围内找鱼群更团结、更整体但转向迟钝、容易整体僵化鱼群分裂成小簇各走各的55 ~ 80分离半径 separation只在这个更小的范围内排斥负责防重叠个体之间留白过大群看起来松散空洞鱼会挤在一起出现重叠抖动20 ~ 28最大速度 maxSpeed单帧位移上限动作夸张、边界处容易穿出去像慢放的蜗牛没有群体张力2.5 ~ 4.0按 60FPS 归一化最大转向力 maxForce单帧速度改变量的上限转向过于生硬像在打方向盘的机器人追不上邻居掉队后拉不回来0.06 ~ 0.12感知半径必须明显大于分离半径常见的比例是 2.5 倍到 3 倍。这个关系的物理直觉是鱼需要一大一小两圈视野外圈用来社交对齐、聚合内圈用来保命分离。如果两个半径一样你会发现在鱼群边缘的鱼会反复横跳——因为同一批邻居既在拉它又在推它力相互抵消位置却一直抖。2.4 权重组合的调参直觉从散调到聚调权重这件事与其说是工程不如说是在找一个手感。我一般从一组保守值起步然后按症状去动特定一项先设分离 1.5、对齐 1.0、聚合 0.9作为基线这个组合在大多数情况下不会出错。鱼群分裂成几团、互相不搭理先别加聚合先加感知半径。只有当半径确实够大了还分裂再把聚合提到 1.3。鱼群缩成一坨来回打转把聚合降到 0.6同时把分离提到 1.8立刻就能散开。所有鱼像一队仪仗兵把对齐降到 0.5同时给最大转向力加一点让个体有机会偏离。整体太安静、没有生命感加一点点随机扰动每帧给转向力叠一个极小的随机向量或者加游荡行为作为第四项力权重给 0.2 左右。实测下来第 5 条是最容易被忽略但收益最大的一步。纯粹的 Boids 在参数调得很稳的时候画面会变得太完美反而假。一点点噪声能让鱼群的边缘出现薄薄的散兵整群在移动时像有一层绒毛观感提升非常明显。3. 关键技术点与实现细节3.1 向量运算把力写成一个能复用的对象MiroFish 里 90% 的数学都是向量加减、点乘和求模。为了代码干净我会先写一个极简的向量工具不引第三方库几十行就能覆盖全部需求。下面这版是我在多个项目里反复用过的接口小但够用import math class Vec2: __slots__ (x, y) def __init__(self, x0.0, y0.0): self.x float(x) self.y float(y) def __add__(self, o): return Vec2(self.x o.x, self.y o.y) def __sub__(self, o): return Vec2(self.x - o.x, self.y - o.y) def __mul__(self, k): # 标量乘也用于 -1 求反向 return Vec2(self.x * k, self.y * k) def __truediv__(self, k): # 除零保护邻域为空时返回零向量而不是崩掉 if k 0: return Vec2(0.0, 0.0) return Vec2(self.x / k, self.y / k) def length_sq(self): # 只要比较远近就用平方长度省一次开方 return self.x * self.x self.y * self.y def length(self): return math.sqrt(self.length_sq()) def normalized(self): l self.length() if l 1e-8: return Vec2(0.0, 0.0) return Vec2(self.x / l, self.y / l) def limited(self, m): l self.length() if l m and l 1e-8: return self.normalized() * m return Vec2(self.x, self.y)几个细节值得单独说。第一length_sq的存在不是为了炫技而是因为邻域筛选时你只需要比较距离是否小于半径比较平方值就够了开方是纯浪费。当个体数量上千、每帧要做几十万次距离判断时这个优化能省下相当可观的 CPU。第二normalized里必须处理零向量。这在 Boids 里出现的频率极高——比如一条鱼正好落在邻居的几何中心上聚合力方向就是零向量如果不判断你会得到 NaN然后整条鱼的坐标变成 NaN接着扩散到整群画面直接消失。这是新手最常见的鱼群集体消失事故。第三__slots__是给大量对象的场景准备的能给每个实例省下字典开销几千个 Agent 的时候内存和分配速度都有提升。提示如果项目里已经用了 numpy2D 场景下我仍然建议保留这个轻量类只在批量距离计算那一层用 numpy 做向量化。原因是单个 Agent 的逻辑用 numpy 反而更慢——每个小数组都有创建开销几百次循环下来损失很明显。3.2 邻域查询从 O(n²) 暴力扫描到网格加速邻域查询是 MiroFish 的性能命门。最直白的写法是两层循环每条鱼遍历所有鱼for a in flock: for b in flock: if a is b: continue if a.pos.sub(b.pos).length_sq() percep_sq: neighbors.append(b)这段代码在 200 条鱼时完全没问题一帧大约 4 万次比较现代 CPU 毫秒级就过了。但数量涨到 2000比较次数就是 400 万一帧几十毫秒帧率直接掉到十几帧。这时候需要上空间划分。最实用的是均匀网格uniform grid把世界切成边长等于感知半径的方格每条鱼只登记在自己所在的格子里查询时只看自己格子和周围 8 个格子。因为格子边长等于感知半径任何超出 3×3 范围的鱼距离一定大于感知半径可以直接排除。这样每个个体的候选邻居从 n 降到常数级别整体复杂度从 O(n²) 变成接近 O(n)。class Grid: def __init__(self, width, height, cell): self.cell cell self.cols int(math.ceil(width / cell)) 1 self.rows int(math.ceil(height / cell)) 1 self.buckets {} def clear(self): self.buckets.clear() def key(self, x, y): return (int(x // self.cell), int(y // self.cell)) def insert(self, agent): self.buckets.setdefault(self.key(agent.pos.x, agent.pos.y), []).append(agent) def neighbors(self, agent, radius_sq): cx, cy self.key(agent.pos.x, agent.pos.y) out [] for dx in (-1, 0, 1): for dy in (-1, 0, 1): for other in self.buckets.get((cx dx, cy dy), ()): if other is agent: continue if agent.pos.sub(other.pos).length_sq() radius_sq: out.append(other) return out这里有个不那么显然的坑格子边长必须取感知半径而不是分离半径。因为网格服务的对象是对齐 聚合这两个用大半径的规则。如果你按分离半径建格子查询范围就得扩到 5×5 甚至更大反而更慢。反过来分离规则可以用同一批候选再筛一遍小半径成本几乎为零。还有个细节网格每帧都要clear()重建。有人会想省这一步做增量更新但鱼每帧都在动跨格判断的复杂度不比重建低而且容易出幽灵邻居的 bug。重建的成本是 O(n) 的字典插入相对整帧开销可以忽略老老实实重建最稳。3.3 边界处理环绕、反弹与软边界三种方案边界是决定看起来自不自然的关键。MiroFish 里我实践过三种各有适用场景。环绕torus鱼从右边出去从左边进来。实现最简单只要对坐标取模。它的好处是完全没有边界效应鱼群永远不会被墙逼成一堆坏处是视觉上不连续鱼会在边缘突然消失又出现除非你的画面本身就是无缝平铺的。适合做无限大场景的抽象动画。硬反弹碰到边界就把速度的法向分量取反。实现也不难但它有个很明显的副作用——鱼群会沿着墙蹭形成一条压在边上的带状结构看起来像被吸在玻璃上。而且当鱼群整体冲向边界时会出现明显的挤压和抖动。软边界转向式我最推荐的做法。给每条鱼定义一个安全边距当它进入边距区域时施加一个指向画面内部的转向力力度按距离边界越近越大。它不强行改变位置只施加力所以运动是连续的、有惯性的鱼群在边界处会自然地拐弯回流像真的撞到了看不见的水墙。def boundary_force(a, width, height, margin80.0, strength1.6): f Vec2(0.0, 0.0) if a.pos.x margin: f.x strength * (margin - a.pos.x) / margin elif a.pos.x width - margin: f.x - strength * (a.pos.x - (width - margin)) / margin if a.pos.y margin: f.y strength * (margin - a.pos.y) / margin elif a.pos.y height - margin: f.y - strength * (a.pos.y - (height - margin)) / margin return f注意这个力是线性渐变的不是阶跃。用阶跃会出现进了边距突然被猛推一下的突兀感线性渐变则让鱼在靠近边界的过程中逐渐感受到阻力转身很平滑。margin一般取画面短边的 8% 到 12%太小了来不及转太大了鱼群活动范围被压缩。3.4 渲染为什么必须用批量绘制最后说渲染。MiroFish 在 2D 下最常见的实现是 pygame 或者 Web 的 Canvas 2D。这两个 API 都有一个共同特性单次绘制调用有固定开销。你画一百个三角形没事画三千个就会明显掉帧问题不在 GPU 而在 CPU 侧的调用分发。解决办法是批量绘制。pygame 里可以用pygame.draw.polygon配合一次性构造的点列表或者更彻底一点把鱼的所有三角面片顶点收集到一个大列表里用一次pygame.gdraw.polygon。Canvas 2D 里则是一条Path2D里塞进所有moveTo/lineTo最后一次性fill()。另外鱼的身体不需要画成复杂的鱼形。一个等腰三角形就足够底边垂直于速度方向顶点指向速度方向。这个箭头形状在快速移动时人眼会自动脑补成小鱼。你想更有味道可以让三角形的腰长随速度变化——速度快的时候拉长一点慢的时候缩短一点就带上了游动的形变感。def draw_flock(surface, flock, color): import pygame for a in flock: v a.vel.normalized() n Vec2(-v.y, v.x) # 垂直方向用来拉出底边 size 6.0 a.vel.length() * 1.2 p1 (a.pos.x v.x * size, a.pos.y v.y * size) p2 (a.pos.x - v.x * size * 0.6 n.x * size * 0.5, a.pos.y - v.y * size * 0.6 n.y * size * 0.5) p3 (a.pos.x - v.x * size * 0.6 - n.x * size * 0.5, a.pos.y - v.y * size * 0.6 - n.y * size * 0.5) pygame.draw.polygon(surface, color, (p1, p2, p3))这段代码在个体数上千时会成为瓶颈因为每条鱼调了一次draw.polygon。真正上量的时候改成用numpy算出所有三角形的顶点数组然后用pygame.surfarray或者gfxdraw批量提交。不过在 500 条以内的场景上面这版就够用优先保证可读性。4. 完整实操流程从零跑起一个 MiroFish4.1 环境准备与项目骨架我推荐用 Python pygame 起步因为这套组合的反馈循环最快改一行代码就能看到画面变化调参的时候极其舒服。装依赖只有一步python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install pygame项目结构我习惯分成三个文件vec2.py放向量工具boids.py放 Agent 和群体逻辑main.py放主循环和渲染。分开的理由不是为了架构好看而是因为调参的时候你会反复改 boids.py 里的常数而主循环基本不动分开之后每次改动的影响范围很清晰不会被无关代码干扰。# main.py 骨架 import pygame from boids import Flock WIDTH, HEIGHT 1280, 720 FPS 60 pygame.init() screen pygame.display.set_mode((WIDTH, HEIGHT)) clock pygame.time.Clock() flock Flock(count300, widthWIDTH, heightHEIGHT) running True while running: dt clock.tick(FPS) / (1000 / 60) # 归一化到 1.0帧率波动时行为不变 for e in pygame.event.get(): if e.type pygame.QUIT: running False flock.update(dt) screen.fill((10, 18, 30)) flock.draw(screen) pygame.display.flip() pygame.quit()这里那个dt归一化值得单独强调。很多人直接写死每帧固定步长结果在帧率波动的时候鱼群的速度会跟着变卡一下之后鱼群突然加速。把步长归一化到每秒 60 帧然后所有参数都按这个基准调行为就跟帧率解耦了。注意dt要参与速度更新和位置更新两处而且不能拿它去乘转向力上限——力的上限是每帧能改变多少速度这个限制应该是绝对的否则掉帧时鱼会突然获得超大的转向能力看起来像瞬移。4.2 Agent 的三个核心方法Flock 里每个个体我会拆成三个方法neighbors找邻居steer算三条合力update做积分。这样拆的好处是调试时可以在任意一层打日志比如直接把steer返回的三个分力分别记下来看看是哪个力把鱼群搞崩的。import math from vec2 import Vec2 class Boid: __slots__ (pos, vel, acc, wander_phase) def __init__(self, x, y): self.pos Vec2(x, y) self.vel Vec2(math.cos(a : random_angle()), math.sin(a)) * 3.0 self.acc Vec2(0.0, 0.0) self.wander_phase random.random() * math.tau # 游荡相位见 4.4 def separation(self, nbrs, radius_sq): steer Vec2(0.0, 0.0) count 0 for o in nbrs: d_sq self.pos.sub(o.pos).length_sq() if 0 d_sq radius_sq: # 距离越近排斥越强除以距离本身 diff self.pos.sub(o.pos).normalized() / math.sqrt(d_sq) steer steer diff count 1 if count 0: return Vec2(0.0, 0.0) steer steer / count return self.limit_steer(steer) def alignment(self, nbrs): if not nbrs: return Vec2(0.0, 0.0) avg Vec2(0.0, 0.0) for o in nbrs: avg avg o.vel avg avg / len(nbrs) return self.limit_steer(avg.normalized() * 3.0 - self.vel) def cohesion(self, nbrs): if not nbrs: return Vec2(0.0, 0.0) center Vec2(0.0, 0.0) for o in nbrs: center center o.pos center center / len(nbrs) return self.limit_steer((center - self.pos).normalized() * 3.0 - self.vel) def limit_steer(self, v): return v.limited(MAX_FORCE)分离力里那个diff / sqrt(d_sq)本质上是方向单位向量除以距离也就是反比衰减。距离越近排斥力越大趋近于无穷距离到了分离半径力衰减到很小。这个 1/r 的形式比线性衰减更符合直觉真正贴到一起的时候要狠推一把稍微远一点就该不管了。当然 1/r 在极近距离会爆炸所以实际代码里我会再加一个下限钳制比如距离小于 2 像素时就当作 2 像素处理避免数值溢出。这一条是我踩过坑才加的——曾经有一次因为两条鱼坐标完全重合除零之后整个鱼群坐标变成 NaN画面变成一片空白排查了半小时。4.3 主循环里的积分顺序与参数选择过程update的顺序非常关键我把它固定成感知 → 结算力 → 限力 → 改速度 → 限速 → 改位置六步顺序不能乱def update(self, dt, grid, sep_sq, percep_sq, width, height): nbrs grid.neighbors(self, percep_sq) sep self.separation(nbrs, sep_sq)* SEP_W ali self.alignment(nbrs) * ALI_W coh self.cohesion(nbrs) * COH_W bnd boundary_force(self, width, height) * BND_W wan self.wander() * WAN_W self.acc sep ali coh bnd wan self.vel (self.vel self.acc * dt).limited(MAX_SPEED) self.pos self.pos self.vel * dt为什么限力要放在加权求和之后因为三个力各自限一次、加起来还会超只有对总和限一次才能保证单帧速度改变量是有界的行为才不会突然爆冲。这和限制单条鱼速度上限的道理是一样的你需要一个全局的物理约束而不是给每个来源单独设限。参数的具体数值我是这么推出来的。先定最大速度。画面宽度 1280我希望一条鱼横穿整个画面大概用 6 到 8 秒那么每秒位移约 160 到 210 像素除以 60 帧就是每帧 2.7 到 3.5 像素取 3.2 作为MAX_SPEED。再定最大转向力。转向力决定了鱼能多快改变方向如果给 1.0那 3 帧之内速度就能反向太灵敏给 0.01要几百帧才能转过来太迟钝。我取MAX_SPEED的 2.5% 到 4%也就是 0.08 到 0.13这组值在视觉上最舒服。最后定感知半径。假设我希望每条鱼周围平均有 5 到 8 个邻居画面里 300 条鱼密度是 300 / (1280×720) ≈ 3.3e-4 每平方像素那么 5 个邻居对应的圆面积约 15000 平方像素半径约 69 像素。这就是我默认感知半径 70 的由来。密度变了这个值就要跟着变比如鱼多了到 600 条半径可以降到 50 左右维持邻居数量大致不变行为才稳定。注意感知半径和个体数量的这个反比关系是很多人忽略的一点。同一组参数在 100 条鱼的时候好看加到 1000 条就会变成一坨原因不是参数错了而是密度变了平均邻居数从 5 涨到了 50。4.4 加一点游荡与噪声让画面活过来前面提过纯 Boids 调稳了会显得太完美。我在 MiroFish 里固定加了一个游荡力做法是让每条鱼带一个自己的相位相位随时间缓慢推进输出一个方向随相位旋转的单位向量def wander(self): self.wander_phase 0.035 if self.wander_phase math.tau: self.wander_phase - math.tau return Vec2(math.cos(self.wander_phase), math.sin(self.wander_phase))相位增速 0.035 对应的周期大约是 180 帧也就是 3 秒鱼会缓慢地改变自己想去的方向形成一种有自己的小心思的感觉。这个力权重给 0.15 到 0.25太高就会让对齐和聚合失效鱼群散掉。除了游荡我还会在转向力上叠一个极小的随机量量级在 0.01 左右。它的作用不是让鱼随机乱跑而是打破对称性。Boids 系统有一个很讨厌的特性如果初始状态完全对称比如所有鱼排成一个整齐的矩阵速度完全一致整个系统会锁死在对称状态里永远不产生群体结构。一点点随机就能打破这个平衡态让结构自然长出来。这个现象在物理上叫对称性自发破缺在仿真里就是个必须手动处理的小坑。4.5 调试与观测把看不见的量画出来调 Boids 最痛苦的是看得到结果看不到原因。我一般会加一个调试模式按空格切换把三类信息叠在画面上邻居连线只画前 20 条鱼的邻域否则满屏都是线、三条分力的方向箭头、以及一个实时显示平均邻居数和平均速度的文本。有了这三个参数出问题的时候基本一眼就能定位。还有一个更狠的招是把每条鱼的三个分力的模长写进日志跑 300 帧之后统计均值。正常状态下三项应该在同一量级如果分离的均值比另外两项高一个数量级说明密度过高或者分离半径太大鱼群会显得非常紧张如果聚合的均值几乎是零说明感知半径太小鱼根本感知不到同伴这时候画面里会出现大量孤立的鱼在原地打转。5. 常见问题排查与避坑清单5.1 鱼群炸开、塌缩、成环的三大症状这三种是最典型的行为异常我整理成一张速查表按症状直接对因处理症状最可能的原因快速验证方法处理方式鱼群瞬间炸开成散沙分离力权重过大或分离半径接近感知半径临时把 SEP_W 设为 0看是否立刻聚合降 SEP_W 到 1.2 左右或缩小分离半径所有鱼塌缩成一个点来回抖聚合权重过大且分离失效打印平均邻居距离看是否持续下降提 SEP_W降 COH_W检查分离半径是否过小鱼群绕着一个圈永不停歇聚合与对齐形成了稳定的环状吸引子观察是否所有鱼速度方向与半径垂直加入游荡力打破环或降低对齐权重边缘的鱼反复横跳感知半径和分离半径太接近打印边界附近鱼的分力方向拉开两个半径的比例到 2.5 倍以上整群贴着边界走使用了硬反弹而非软边界观察是否只在墙边聚集换成 3.3 节的转向式软边界卡顿一段时间后集体瞬移用了固定步长没有做 dt 归一化打印每帧 dt 看波动按 4.1 节做步长归一化那张表里聚合与对齐形成环状吸引子是最有意思的一条。它不是 bug而是这套动力学的一个真实解——当聚合把鱼拉向中心、对齐让它们保持一致方向而速度上限又阻止它们冲向中心时物理上唯一稳定的解就是绕着中心做圆周运动。很多人第一次遇到会以为是代码错了其实这是系统在告诉你参数组合走到了一个退化状态。加个游荡力或者降低对齐权重就能出来。5.2 帧率掉下去的排查路径性能问题要按顺序排查不要一上来就想着上 GPU。第一步确认瓶颈在哪儿。最粗暴也最有效的方法是把三个环节分别关掉跑一遍只做邻域查询不画图、只画图不做查询、什么都做。哪一个关掉帧率就回来了问题就在哪儿。第二步如果瓶颈在邻域查询先看是不是没上网格。200 条以内不用管超过 500 条必须上。上了网格还慢检查格子边长是不是按感知半径建的以及每帧是不是有重复的字典分配。第三步如果瓶颈在渲染看每次绘制调用是不是逐个个体提交的。换成批量路径通常能有 3 到 5 倍的提升。第四步如果以上都排除了还慢问题多半在 Python 的对象分配上。每帧创建几万个 Vec2 实例GC 压力会起来。这时候可以把acc、临时向量这些改成复用字段或者干脆把整个核心循环用 numpy 数组重写一遍做全量向量化。numpy 版在 2000 条以上时优势很明显但代价是调试难度大幅上升所以我一般撑得住就不改。# numpy 版的关键一步一次性算出全对距离矩阵的下三角 d pos[:, None, :] - pos[None, :, :] # (n, n, 2) d_sq (d * d).sum(axis2) # (n, n) mask (d_sq percep_sq) (d_sq 0) # 布尔邻接矩阵 counts mask.sum(axis1, keepdimsTrue) counts[counts 0] 1 # 防止除零 center (pos[None, :, :] * mask[..., None]).sum(axis1) / counts这段代码的代价是内存n 2000 时d_sq是 400 万个浮点数d更是 800 万个单帧分配好几百 MBGC 直接崩。真要上量必须分块计算比如每 256 条一组算一次把峰值内存压下来。这是 numpy 向量化最容易翻车的地方——纸面上复杂度降了实际上被内存带宽卡死。我的经验是 n 在 1000 以内numpy 全量矩阵可以接受超过 1000老老实实回到空间网格。5.3 数值稳定性的几个小手段最后补几个不显眼但很关键的小处理。第一所有除法都加零保护normalized和__truediv__里都要。第二速度做上限钳制时用limited而不是乘一个缩放系数因为缩放在速度为 0 的时候会产生新的零向量行为不一致。第三如果坐标跑出了世界范围比如因为外力加了很大的推力要在 update 末尾做一次 wrap 或者 clamp否则鱼会跑到坐标十万之外的荒原上看起来像消失了。第四随机扰动必须有上限random.uniform(-0.01, 0.01)和random.uniform(-100, 100)是两个完全不同的系统后者会让整个模型失去意义。6. 参数调优表与我的实践心得调参这件事最有效的办法不是一次动一个参数然后看着画面发呆而是先定密度、再定速度、再定力、最后定权重。这个顺序不能反。密度决定了平均邻居数平均邻居数是行为的基础速度决定了时间尺度是所有力能被感知到的前提力决定了灵活性权重才是最后的微调。我见过太多人一上来就狂调权重结果发现怎么调都不对原因是他 300 条鱼用了 30 像素的感知半径平均邻居数是 0.6根本没有社交可言。下面这张表是我在 1280×720、60FPS 基准下几组不同气质的配置可以直接抄风格数量感知半径分离半径最大速度最大转向力权重分/对/聚/游温顺慢游20080262.40.061.4 / 1.0 / 1.1 / 0.15紧凑急行40060223.60.111.8 / 1.2 / 0.9 / 0.20松散悠荡15095242.00.051.2 / 0.7 / 0.6 / 0.30高压密集80045183.00.092.0 / 1.1 / 1.0 / 0.20高压密集那一组值得说一句。800 条鱼、感知半径只有 45平均邻居数大概 6 个看起来密度极高但画面并不会糊成一团因为分离权重提到了 2.0个体之间始终保持明确的间隙整体看起来像一大片流动的沙丁鱼群视觉冲击力最强。不过这组配置对性能要求最高必须上空间网格渲染也必须批量提交。我在这个项目上反复折腾之后最想分享的三条经验是这样的。第一先把平均邻居数打到 5 到 8 之间再谈别的这个区间之外的所有调参都是在白费力气。你可以写三行代码跑一帧然后统计所有个体的邻居数量取平均这个数字比任何视觉判断都准。第二所有能形成正反馈的参数组合最终都会走到极端状态聚合权重只要够大鱼群一定会塌缩对齐权重只要够大一定会变成僵硬的板块。这不是参数没调好而是动力学的必然。你要做的是把参数留在不稳定边缘的那一小片区域里那个位置的画面最好看也最脆弱稍微一动就会偏。**第三也是我最晚才意识到的一点视觉上好看的鱼群代码层面的数学往往不是最正确的。**比如严格按物理写的话转向力应该和质量、阻尼都挂钩但实际做出来最舒服的版本是砍掉了一大半物理项、只剩速度钳制和三个基础力的那一版。仿真的目标是看起来对不是算出来对这个心态转变之后调参会轻松很多。如果这套东西你已经跑顺了我会建议往两个方向扩展。一个是加捕食者——在画面里放一个移动的排斥源鱼群会立刻表现出逃逸、分流、重新聚合的复杂行为只用给原始的分离力再加一项远离捕食者代码改动不到二十行效果却像换了个项目。另一个是把平面的鱼放到三维空间里Boids 的所有公式在三维下完全不用改只需要把 Vec2 换成 Vec3、把邻域网格换成八叉树或者三维网格鱼群在体积里盘旋的画面比平面版本要震撼得多。 MiroFish：Boids群体智能鱼群模拟与可视化
第一次看到 MiroFish 这个名字我脑子里蹦出来的画面是一缸不受控制的鱼——每条鱼只看得见身边巴掌大的范围没有总指挥没有全局地图可整群鱼却能在零点几秒内同时转向像一块会呼吸的绸缎。MiroFish 就是冲着这件事来的一个用群体智能思路做的鱼群模拟与可视化项目核心是把个体只懂几条傻规则整体却能涌现出高级行为这件事从抽象概念变成屏幕上看得见、参数拧得动、代码抄得走的东西。它可以用来做游戏 NPC 的集群行为、数据可视化里的流动意象、教学演示中的涌现现象、甚至艺术装置里的实时生成画面。适合两类人一类是刚接触 Agent 仿真、想找个不到五百行就能跑通的项目练手的新手另一类是已经在做实时图形或仿真系统、需要一套稳定的邻域查询和转向力结算方案的老手。我会把 MiroFish 的设计取舍、核心算法、参数怎么算、性能怎么抠、坑怎么填全部摊开讲一遍。1. MiroFish 到底在解决什么问题1.1 从一缸真鱼说起个体简单群体复杂养过鱼的人都会注意到一件事你往缸里撒一把饲料鱼群不会像士兵一样排队冲过去而是先散、再聚、再整体平移路线上带着一点犹豫和一点随机。这种整体有序、局部混乱的状态用传统的方式去写代码非常难受。如果你尝试用一条全局路径去指挥每一条鱼立刻会遇到三个麻烦第一全局路径无法应对动态障碍一旦有新的捕食者或者突然出现的边界整条路径作废第二计算量会随着鱼的数量线性甚至更高地增长因为每条鱼都要维护自己的目标第三也是最要命的写出来的动画假——每条鱼的运动轨迹过于干净没有那种互相挤压、临时让位、转身时尾巴甩一下的自然感。MiroFish 的思路是从源头换掉这件事不给任何一条鱼全局信息每条鱼只做三件极小的事剩下的交给涌现。这三件事就是经典 Boids 模型里的分离Separation、对齐Alignment和聚合Cohesion。分离让鱼不要撞到邻居对齐让鱼和邻居保持大致相同的方向聚合让鱼往邻居的中心靠。三条规则各自都很笨但叠在一起之后鱼群会自己长出绕障、分流、收拢、绕圈这些谁也没写进代码的行为。我用一句话概括 MiroFish 的价值它把复杂行为从复杂规则里解放出来改用简单规则 大量个体 局部交互来生成。这个思路一旦掌握你再看鸟群、蚁群、车流、人群疏散、粒子特效会发现背后是同一套骨架。这是我认为它比很多效果炫酷但看完学不到东西的演示项目更值得动手的原因。1.2 适合谁上手又能落到哪些真实场景先说适合谁。如果你是刚学完面向对象、想找个能立刻看到画面的项目MiroFish 的门槛很低——一个 Agent 类、一个主循环、几十行向量运算就能跑起来。如果你已经在做 Unity、Godot、或者 Web 端的 Canvas/WebGL 项目MiroFish 更像一份可以直接移植的行为层参考转向力怎么结算、邻域怎么查、边界怎么处理这三块在任何实时集群系统里都是绕不开的。如果你是做数据可视化或者交互艺术的MiroFish 提供的是活的素材——同样的画面里光标的移动可以成为一股外力把鱼群推开或者吸引过来交互感和叙事性都很强。再说落地场景。游戏里最常见的是鱼群、鸟群、蝙蝠群、虫群这类环境生物它们不需要复杂 AI但必须看起来成群影视和广告里的预演镜头需要快速生成大量群集运动MiroFish 这套参数化的做法改几个数就能出不同风格城市交通和人群疏散仿真里行人之间的避让、跟随、聚集和 Boids 是同一个数学结构只是把鱼换成人、把速度上限换成步行速度另外像粒子系统、流体近似、噪声场驱动的抽象动画也都能借这套骨架。说白了凡是很多个体、各自只有局部视野、整体要有秩序的场景MiroFish 都是那个可以拿来铺底的模板。注意MiroFish 不是物理引擎它做的是行为近似而不是刚体精确碰撞。如果你需要的是精确到毫米的碰撞响应请把 Boids 当作上层行为层碰撞交给物理引擎去处理两者分工不要混在一起算。2. 核心思路拆解三条规则怎么撑起一整群鱼2.1 分离、对齐、聚合的直觉解释与力的叠加把三条规则翻译成人话大概是这样的。分离如果我离邻居太近我就往反方向挪一点这是保命。对齐我看周围邻居大致朝哪走就把自己的方向往那个平均方向拧一点这是随大流。聚合我看看周围邻居的重心在哪往那边靠一点这是别掉队。三条规则的输出都是转向力steering force也就是一个向量表示我希望自己的速度朝这个方向改多少。把它们按权重加权求和得到这一帧的总转向力再把它加到速度上最后用速度更新位置。这里有个很关键的认知这三条规则输出的是加速度而不是位置。新手最常犯的错误是直接改位置——x (center_x - x) * 0.1。这么写也能动但动出来的东西像被橡皮筋拴住一抽一抽的速度不连续没有惯性。正确做法是让力去改速度、让速度去改位置中间夹一层速度钳制和转向力钳制。有了这一层鱼群的运动才会带上游的感觉——有加速、有滑行、有减速。另外三条规则的权重不是随便给的。我的经验值是分离明显偏重对齐中等聚合稍轻。原因很简单分离是对不自然最敏感的规则一旦分离权重不够鱼会叠在一起变成一坨而聚合权重过大鱼群会塌成一个点然后绕着中心疯狂打转看起来像漩涡而不是鱼群。对齐权重给太高整个群会变成一块僵硬的板子所有鱼像被冻住方向一样整齐失去生命感。2.2 为什么不做全局最优而是坚持局部规则这里必须解释一个为什么因为它是 MiroFish 全部设计选择的根。假设你给每条鱼一个全局目标点让它算最短路径会发生什么在静态环境里确实能得到最优路线但鱼群是一个高动态耦合系统每条鱼都在动每条鱼的动又会改变别人的邻域整个系统的状态每一帧都在变。这时候最优这个词是失效的因为你在为上一帧算最优等算完环境已经变了。硬追最优的结果就是所有鱼抢同一条路线挤成一团然后抖动。局部规则的好处是每次决策只依赖一小块邻域计算稳定、响应快、天然分布式。它不追求最优追求的是鲁棒。这个取舍在工程上非常典型分布式系统的局部启发式往往比中心化的全局求解更适合实时场景。MiroFish 选了后者所以它能跑几千上万个体而不崩也能随便加障碍、加外力、加捕食者而不需要重算任何东西。提示别把局部理解成短视。局部规则叠加后产生的宏观行为在统计意义上是稳定的你会看到鱼群自然地绕过障碍、自然地分流、自然地重新聚合。这正是群体智能最有意思的地方。2.3 感知半径与分离半径两个参数决定群的整体气质MiroFish 里有几个半径参数很多人第一次调的时候会随手写同一个值结果就是鱼群要么散沙要么铁板。这两个半径的分工必须分清。参数作用调大的后果调小的后果我的常用值2D单位像素感知半径 perception决定了谁算我的邻居对齐和聚合都在这个范围内找鱼群更团结、更整体但转向迟钝、容易整体僵化鱼群分裂成小簇各走各的55 ~ 80分离半径 separation只在这个更小的范围内排斥负责防重叠个体之间留白过大群看起来松散空洞鱼会挤在一起出现重叠抖动20 ~ 28最大速度 maxSpeed单帧位移上限动作夸张、边界处容易穿出去像慢放的蜗牛没有群体张力2.5 ~ 4.0按 60FPS 归一化最大转向力 maxForce单帧速度改变量的上限转向过于生硬像在打方向盘的机器人追不上邻居掉队后拉不回来0.06 ~ 0.12感知半径必须明显大于分离半径常见的比例是 2.5 倍到 3 倍。这个关系的物理直觉是鱼需要一大一小两圈视野外圈用来社交对齐、聚合内圈用来保命分离。如果两个半径一样你会发现在鱼群边缘的鱼会反复横跳——因为同一批邻居既在拉它又在推它力相互抵消位置却一直抖。2.4 权重组合的调参直觉从散调到聚调权重这件事与其说是工程不如说是在找一个手感。我一般从一组保守值起步然后按症状去动特定一项先设分离 1.5、对齐 1.0、聚合 0.9作为基线这个组合在大多数情况下不会出错。鱼群分裂成几团、互相不搭理先别加聚合先加感知半径。只有当半径确实够大了还分裂再把聚合提到 1.3。鱼群缩成一坨来回打转把聚合降到 0.6同时把分离提到 1.8立刻就能散开。所有鱼像一队仪仗兵把对齐降到 0.5同时给最大转向力加一点让个体有机会偏离。整体太安静、没有生命感加一点点随机扰动每帧给转向力叠一个极小的随机向量或者加游荡行为作为第四项力权重给 0.2 左右。实测下来第 5 条是最容易被忽略但收益最大的一步。纯粹的 Boids 在参数调得很稳的时候画面会变得太完美反而假。一点点噪声能让鱼群的边缘出现薄薄的散兵整群在移动时像有一层绒毛观感提升非常明显。3. 关键技术点与实现细节3.1 向量运算把力写成一个能复用的对象MiroFish 里 90% 的数学都是向量加减、点乘和求模。为了代码干净我会先写一个极简的向量工具不引第三方库几十行就能覆盖全部需求。下面这版是我在多个项目里反复用过的接口小但够用import math class Vec2: __slots__ (x, y) def __init__(self, x0.0, y0.0): self.x float(x) self.y float(y) def __add__(self, o): return Vec2(self.x o.x, self.y o.y) def __sub__(self, o): return Vec2(self.x - o.x, self.y - o.y) def __mul__(self, k): # 标量乘也用于 -1 求反向 return Vec2(self.x * k, self.y * k) def __truediv__(self, k): # 除零保护邻域为空时返回零向量而不是崩掉 if k 0: return Vec2(0.0, 0.0) return Vec2(self.x / k, self.y / k) def length_sq(self): # 只要比较远近就用平方长度省一次开方 return self.x * self.x self.y * self.y def length(self): return math.sqrt(self.length_sq()) def normalized(self): l self.length() if l 1e-8: return Vec2(0.0, 0.0) return Vec2(self.x / l, self.y / l) def limited(self, m): l self.length() if l m and l 1e-8: return self.normalized() * m return Vec2(self.x, self.y)几个细节值得单独说。第一length_sq的存在不是为了炫技而是因为邻域筛选时你只需要比较距离是否小于半径比较平方值就够了开方是纯浪费。当个体数量上千、每帧要做几十万次距离判断时这个优化能省下相当可观的 CPU。第二normalized里必须处理零向量。这在 Boids 里出现的频率极高——比如一条鱼正好落在邻居的几何中心上聚合力方向就是零向量如果不判断你会得到 NaN然后整条鱼的坐标变成 NaN接着扩散到整群画面直接消失。这是新手最常见的鱼群集体消失事故。第三__slots__是给大量对象的场景准备的能给每个实例省下字典开销几千个 Agent 的时候内存和分配速度都有提升。提示如果项目里已经用了 numpy2D 场景下我仍然建议保留这个轻量类只在批量距离计算那一层用 numpy 做向量化。原因是单个 Agent 的逻辑用 numpy 反而更慢——每个小数组都有创建开销几百次循环下来损失很明显。3.2 邻域查询从 O(n²) 暴力扫描到网格加速邻域查询是 MiroFish 的性能命门。最直白的写法是两层循环每条鱼遍历所有鱼for a in flock: for b in flock: if a is b: continue if a.pos.sub(b.pos).length_sq() percep_sq: neighbors.append(b)这段代码在 200 条鱼时完全没问题一帧大约 4 万次比较现代 CPU 毫秒级就过了。但数量涨到 2000比较次数就是 400 万一帧几十毫秒帧率直接掉到十几帧。这时候需要上空间划分。最实用的是均匀网格uniform grid把世界切成边长等于感知半径的方格每条鱼只登记在自己所在的格子里查询时只看自己格子和周围 8 个格子。因为格子边长等于感知半径任何超出 3×3 范围的鱼距离一定大于感知半径可以直接排除。这样每个个体的候选邻居从 n 降到常数级别整体复杂度从 O(n²) 变成接近 O(n)。class Grid: def __init__(self, width, height, cell): self.cell cell self.cols int(math.ceil(width / cell)) 1 self.rows int(math.ceil(height / cell)) 1 self.buckets {} def clear(self): self.buckets.clear() def key(self, x, y): return (int(x // self.cell), int(y // self.cell)) def insert(self, agent): self.buckets.setdefault(self.key(agent.pos.x, agent.pos.y), []).append(agent) def neighbors(self, agent, radius_sq): cx, cy self.key(agent.pos.x, agent.pos.y) out [] for dx in (-1, 0, 1): for dy in (-1, 0, 1): for other in self.buckets.get((cx dx, cy dy), ()): if other is agent: continue if agent.pos.sub(other.pos).length_sq() radius_sq: out.append(other) return out这里有个不那么显然的坑格子边长必须取感知半径而不是分离半径。因为网格服务的对象是对齐 聚合这两个用大半径的规则。如果你按分离半径建格子查询范围就得扩到 5×5 甚至更大反而更慢。反过来分离规则可以用同一批候选再筛一遍小半径成本几乎为零。还有个细节网格每帧都要clear()重建。有人会想省这一步做增量更新但鱼每帧都在动跨格判断的复杂度不比重建低而且容易出幽灵邻居的 bug。重建的成本是 O(n) 的字典插入相对整帧开销可以忽略老老实实重建最稳。3.3 边界处理环绕、反弹与软边界三种方案边界是决定看起来自不自然的关键。MiroFish 里我实践过三种各有适用场景。环绕torus鱼从右边出去从左边进来。实现最简单只要对坐标取模。它的好处是完全没有边界效应鱼群永远不会被墙逼成一堆坏处是视觉上不连续鱼会在边缘突然消失又出现除非你的画面本身就是无缝平铺的。适合做无限大场景的抽象动画。硬反弹碰到边界就把速度的法向分量取反。实现也不难但它有个很明显的副作用——鱼群会沿着墙蹭形成一条压在边上的带状结构看起来像被吸在玻璃上。而且当鱼群整体冲向边界时会出现明显的挤压和抖动。软边界转向式我最推荐的做法。给每条鱼定义一个安全边距当它进入边距区域时施加一个指向画面内部的转向力力度按距离边界越近越大。它不强行改变位置只施加力所以运动是连续的、有惯性的鱼群在边界处会自然地拐弯回流像真的撞到了看不见的水墙。def boundary_force(a, width, height, margin80.0, strength1.6): f Vec2(0.0, 0.0) if a.pos.x margin: f.x strength * (margin - a.pos.x) / margin elif a.pos.x width - margin: f.x - strength * (a.pos.x - (width - margin)) / margin if a.pos.y margin: f.y strength * (margin - a.pos.y) / margin elif a.pos.y height - margin: f.y - strength * (a.pos.y - (height - margin)) / margin return f注意这个力是线性渐变的不是阶跃。用阶跃会出现进了边距突然被猛推一下的突兀感线性渐变则让鱼在靠近边界的过程中逐渐感受到阻力转身很平滑。margin一般取画面短边的 8% 到 12%太小了来不及转太大了鱼群活动范围被压缩。3.4 渲染为什么必须用批量绘制最后说渲染。MiroFish 在 2D 下最常见的实现是 pygame 或者 Web 的 Canvas 2D。这两个 API 都有一个共同特性单次绘制调用有固定开销。你画一百个三角形没事画三千个就会明显掉帧问题不在 GPU 而在 CPU 侧的调用分发。解决办法是批量绘制。pygame 里可以用pygame.draw.polygon配合一次性构造的点列表或者更彻底一点把鱼的所有三角面片顶点收集到一个大列表里用一次pygame.gdraw.polygon。Canvas 2D 里则是一条Path2D里塞进所有moveTo/lineTo最后一次性fill()。另外鱼的身体不需要画成复杂的鱼形。一个等腰三角形就足够底边垂直于速度方向顶点指向速度方向。这个箭头形状在快速移动时人眼会自动脑补成小鱼。你想更有味道可以让三角形的腰长随速度变化——速度快的时候拉长一点慢的时候缩短一点就带上了游动的形变感。def draw_flock(surface, flock, color): import pygame for a in flock: v a.vel.normalized() n Vec2(-v.y, v.x) # 垂直方向用来拉出底边 size 6.0 a.vel.length() * 1.2 p1 (a.pos.x v.x * size, a.pos.y v.y * size) p2 (a.pos.x - v.x * size * 0.6 n.x * size * 0.5, a.pos.y - v.y * size * 0.6 n.y * size * 0.5) p3 (a.pos.x - v.x * size * 0.6 - n.x * size * 0.5, a.pos.y - v.y * size * 0.6 - n.y * size * 0.5) pygame.draw.polygon(surface, color, (p1, p2, p3))这段代码在个体数上千时会成为瓶颈因为每条鱼调了一次draw.polygon。真正上量的时候改成用numpy算出所有三角形的顶点数组然后用pygame.surfarray或者gfxdraw批量提交。不过在 500 条以内的场景上面这版就够用优先保证可读性。4. 完整实操流程从零跑起一个 MiroFish4.1 环境准备与项目骨架我推荐用 Python pygame 起步因为这套组合的反馈循环最快改一行代码就能看到画面变化调参的时候极其舒服。装依赖只有一步python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install pygame项目结构我习惯分成三个文件vec2.py放向量工具boids.py放 Agent 和群体逻辑main.py放主循环和渲染。分开的理由不是为了架构好看而是因为调参的时候你会反复改 boids.py 里的常数而主循环基本不动分开之后每次改动的影响范围很清晰不会被无关代码干扰。# main.py 骨架 import pygame from boids import Flock WIDTH, HEIGHT 1280, 720 FPS 60 pygame.init() screen pygame.display.set_mode((WIDTH, HEIGHT)) clock pygame.time.Clock() flock Flock(count300, widthWIDTH, heightHEIGHT) running True while running: dt clock.tick(FPS) / (1000 / 60) # 归一化到 1.0帧率波动时行为不变 for e in pygame.event.get(): if e.type pygame.QUIT: running False flock.update(dt) screen.fill((10, 18, 30)) flock.draw(screen) pygame.display.flip() pygame.quit()这里那个dt归一化值得单独强调。很多人直接写死每帧固定步长结果在帧率波动的时候鱼群的速度会跟着变卡一下之后鱼群突然加速。把步长归一化到每秒 60 帧然后所有参数都按这个基准调行为就跟帧率解耦了。注意dt要参与速度更新和位置更新两处而且不能拿它去乘转向力上限——力的上限是每帧能改变多少速度这个限制应该是绝对的否则掉帧时鱼会突然获得超大的转向能力看起来像瞬移。4.2 Agent 的三个核心方法Flock 里每个个体我会拆成三个方法neighbors找邻居steer算三条合力update做积分。这样拆的好处是调试时可以在任意一层打日志比如直接把steer返回的三个分力分别记下来看看是哪个力把鱼群搞崩的。import math from vec2 import Vec2 class Boid: __slots__ (pos, vel, acc, wander_phase) def __init__(self, x, y): self.pos Vec2(x, y) self.vel Vec2(math.cos(a : random_angle()), math.sin(a)) * 3.0 self.acc Vec2(0.0, 0.0) self.wander_phase random.random() * math.tau # 游荡相位见 4.4 def separation(self, nbrs, radius_sq): steer Vec2(0.0, 0.0) count 0 for o in nbrs: d_sq self.pos.sub(o.pos).length_sq() if 0 d_sq radius_sq: # 距离越近排斥越强除以距离本身 diff self.pos.sub(o.pos).normalized() / math.sqrt(d_sq) steer steer diff count 1 if count 0: return Vec2(0.0, 0.0) steer steer / count return self.limit_steer(steer) def alignment(self, nbrs): if not nbrs: return Vec2(0.0, 0.0) avg Vec2(0.0, 0.0) for o in nbrs: avg avg o.vel avg avg / len(nbrs) return self.limit_steer(avg.normalized() * 3.0 - self.vel) def cohesion(self, nbrs): if not nbrs: return Vec2(0.0, 0.0) center Vec2(0.0, 0.0) for o in nbrs: center center o.pos center center / len(nbrs) return self.limit_steer((center - self.pos).normalized() * 3.0 - self.vel) def limit_steer(self, v): return v.limited(MAX_FORCE)分离力里那个diff / sqrt(d_sq)本质上是方向单位向量除以距离也就是反比衰减。距离越近排斥力越大趋近于无穷距离到了分离半径力衰减到很小。这个 1/r 的形式比线性衰减更符合直觉真正贴到一起的时候要狠推一把稍微远一点就该不管了。当然 1/r 在极近距离会爆炸所以实际代码里我会再加一个下限钳制比如距离小于 2 像素时就当作 2 像素处理避免数值溢出。这一条是我踩过坑才加的——曾经有一次因为两条鱼坐标完全重合除零之后整个鱼群坐标变成 NaN画面变成一片空白排查了半小时。4.3 主循环里的积分顺序与参数选择过程update的顺序非常关键我把它固定成感知 → 结算力 → 限力 → 改速度 → 限速 → 改位置六步顺序不能乱def update(self, dt, grid, sep_sq, percep_sq, width, height): nbrs grid.neighbors(self, percep_sq) sep self.separation(nbrs, sep_sq)* SEP_W ali self.alignment(nbrs) * ALI_W coh self.cohesion(nbrs) * COH_W bnd boundary_force(self, width, height) * BND_W wan self.wander() * WAN_W self.acc sep ali coh bnd wan self.vel (self.vel self.acc * dt).limited(MAX_SPEED) self.pos self.pos self.vel * dt为什么限力要放在加权求和之后因为三个力各自限一次、加起来还会超只有对总和限一次才能保证单帧速度改变量是有界的行为才不会突然爆冲。这和限制单条鱼速度上限的道理是一样的你需要一个全局的物理约束而不是给每个来源单独设限。参数的具体数值我是这么推出来的。先定最大速度。画面宽度 1280我希望一条鱼横穿整个画面大概用 6 到 8 秒那么每秒位移约 160 到 210 像素除以 60 帧就是每帧 2.7 到 3.5 像素取 3.2 作为MAX_SPEED。再定最大转向力。转向力决定了鱼能多快改变方向如果给 1.0那 3 帧之内速度就能反向太灵敏给 0.01要几百帧才能转过来太迟钝。我取MAX_SPEED的 2.5% 到 4%也就是 0.08 到 0.13这组值在视觉上最舒服。最后定感知半径。假设我希望每条鱼周围平均有 5 到 8 个邻居画面里 300 条鱼密度是 300 / (1280×720) ≈ 3.3e-4 每平方像素那么 5 个邻居对应的圆面积约 15000 平方像素半径约 69 像素。这就是我默认感知半径 70 的由来。密度变了这个值就要跟着变比如鱼多了到 600 条半径可以降到 50 左右维持邻居数量大致不变行为才稳定。注意感知半径和个体数量的这个反比关系是很多人忽略的一点。同一组参数在 100 条鱼的时候好看加到 1000 条就会变成一坨原因不是参数错了而是密度变了平均邻居数从 5 涨到了 50。4.4 加一点游荡与噪声让画面活过来前面提过纯 Boids 调稳了会显得太完美。我在 MiroFish 里固定加了一个游荡力做法是让每条鱼带一个自己的相位相位随时间缓慢推进输出一个方向随相位旋转的单位向量def wander(self): self.wander_phase 0.035 if self.wander_phase math.tau: self.wander_phase - math.tau return Vec2(math.cos(self.wander_phase), math.sin(self.wander_phase))相位增速 0.035 对应的周期大约是 180 帧也就是 3 秒鱼会缓慢地改变自己想去的方向形成一种有自己的小心思的感觉。这个力权重给 0.15 到 0.25太高就会让对齐和聚合失效鱼群散掉。除了游荡我还会在转向力上叠一个极小的随机量量级在 0.01 左右。它的作用不是让鱼随机乱跑而是打破对称性。Boids 系统有一个很讨厌的特性如果初始状态完全对称比如所有鱼排成一个整齐的矩阵速度完全一致整个系统会锁死在对称状态里永远不产生群体结构。一点点随机就能打破这个平衡态让结构自然长出来。这个现象在物理上叫对称性自发破缺在仿真里就是个必须手动处理的小坑。4.5 调试与观测把看不见的量画出来调 Boids 最痛苦的是看得到结果看不到原因。我一般会加一个调试模式按空格切换把三类信息叠在画面上邻居连线只画前 20 条鱼的邻域否则满屏都是线、三条分力的方向箭头、以及一个实时显示平均邻居数和平均速度的文本。有了这三个参数出问题的时候基本一眼就能定位。还有一个更狠的招是把每条鱼的三个分力的模长写进日志跑 300 帧之后统计均值。正常状态下三项应该在同一量级如果分离的均值比另外两项高一个数量级说明密度过高或者分离半径太大鱼群会显得非常紧张如果聚合的均值几乎是零说明感知半径太小鱼根本感知不到同伴这时候画面里会出现大量孤立的鱼在原地打转。5. 常见问题排查与避坑清单5.1 鱼群炸开、塌缩、成环的三大症状这三种是最典型的行为异常我整理成一张速查表按症状直接对因处理症状最可能的原因快速验证方法处理方式鱼群瞬间炸开成散沙分离力权重过大或分离半径接近感知半径临时把 SEP_W 设为 0看是否立刻聚合降 SEP_W 到 1.2 左右或缩小分离半径所有鱼塌缩成一个点来回抖聚合权重过大且分离失效打印平均邻居距离看是否持续下降提 SEP_W降 COH_W检查分离半径是否过小鱼群绕着一个圈永不停歇聚合与对齐形成了稳定的环状吸引子观察是否所有鱼速度方向与半径垂直加入游荡力打破环或降低对齐权重边缘的鱼反复横跳感知半径和分离半径太接近打印边界附近鱼的分力方向拉开两个半径的比例到 2.5 倍以上整群贴着边界走使用了硬反弹而非软边界观察是否只在墙边聚集换成 3.3 节的转向式软边界卡顿一段时间后集体瞬移用了固定步长没有做 dt 归一化打印每帧 dt 看波动按 4.1 节做步长归一化那张表里聚合与对齐形成环状吸引子是最有意思的一条。它不是 bug而是这套动力学的一个真实解——当聚合把鱼拉向中心、对齐让它们保持一致方向而速度上限又阻止它们冲向中心时物理上唯一稳定的解就是绕着中心做圆周运动。很多人第一次遇到会以为是代码错了其实这是系统在告诉你参数组合走到了一个退化状态。加个游荡力或者降低对齐权重就能出来。5.2 帧率掉下去的排查路径性能问题要按顺序排查不要一上来就想着上 GPU。第一步确认瓶颈在哪儿。最粗暴也最有效的方法是把三个环节分别关掉跑一遍只做邻域查询不画图、只画图不做查询、什么都做。哪一个关掉帧率就回来了问题就在哪儿。第二步如果瓶颈在邻域查询先看是不是没上网格。200 条以内不用管超过 500 条必须上。上了网格还慢检查格子边长是不是按感知半径建的以及每帧是不是有重复的字典分配。第三步如果瓶颈在渲染看每次绘制调用是不是逐个个体提交的。换成批量路径通常能有 3 到 5 倍的提升。第四步如果以上都排除了还慢问题多半在 Python 的对象分配上。每帧创建几万个 Vec2 实例GC 压力会起来。这时候可以把acc、临时向量这些改成复用字段或者干脆把整个核心循环用 numpy 数组重写一遍做全量向量化。numpy 版在 2000 条以上时优势很明显但代价是调试难度大幅上升所以我一般撑得住就不改。# numpy 版的关键一步一次性算出全对距离矩阵的下三角 d pos[:, None, :] - pos[None, :, :] # (n, n, 2) d_sq (d * d).sum(axis2) # (n, n) mask (d_sq percep_sq) (d_sq 0) # 布尔邻接矩阵 counts mask.sum(axis1, keepdimsTrue) counts[counts 0] 1 # 防止除零 center (pos[None, :, :] * mask[..., None]).sum(axis1) / counts这段代码的代价是内存n 2000 时d_sq是 400 万个浮点数d更是 800 万个单帧分配好几百 MBGC 直接崩。真要上量必须分块计算比如每 256 条一组算一次把峰值内存压下来。这是 numpy 向量化最容易翻车的地方——纸面上复杂度降了实际上被内存带宽卡死。我的经验是 n 在 1000 以内numpy 全量矩阵可以接受超过 1000老老实实回到空间网格。5.3 数值稳定性的几个小手段最后补几个不显眼但很关键的小处理。第一所有除法都加零保护normalized和__truediv__里都要。第二速度做上限钳制时用limited而不是乘一个缩放系数因为缩放在速度为 0 的时候会产生新的零向量行为不一致。第三如果坐标跑出了世界范围比如因为外力加了很大的推力要在 update 末尾做一次 wrap 或者 clamp否则鱼会跑到坐标十万之外的荒原上看起来像消失了。第四随机扰动必须有上限random.uniform(-0.01, 0.01)和random.uniform(-100, 100)是两个完全不同的系统后者会让整个模型失去意义。6. 参数调优表与我的实践心得调参这件事最有效的办法不是一次动一个参数然后看着画面发呆而是先定密度、再定速度、再定力、最后定权重。这个顺序不能反。密度决定了平均邻居数平均邻居数是行为的基础速度决定了时间尺度是所有力能被感知到的前提力决定了灵活性权重才是最后的微调。我见过太多人一上来就狂调权重结果发现怎么调都不对原因是他 300 条鱼用了 30 像素的感知半径平均邻居数是 0.6根本没有社交可言。下面这张表是我在 1280×720、60FPS 基准下几组不同气质的配置可以直接抄风格数量感知半径分离半径最大速度最大转向力权重分/对/聚/游温顺慢游20080262.40.061.4 / 1.0 / 1.1 / 0.15紧凑急行40060223.60.111.8 / 1.2 / 0.9 / 0.20松散悠荡15095242.00.051.2 / 0.7 / 0.6 / 0.30高压密集80045183.00.092.0 / 1.1 / 1.0 / 0.20高压密集那一组值得说一句。800 条鱼、感知半径只有 45平均邻居数大概 6 个看起来密度极高但画面并不会糊成一团因为分离权重提到了 2.0个体之间始终保持明确的间隙整体看起来像一大片流动的沙丁鱼群视觉冲击力最强。不过这组配置对性能要求最高必须上空间网格渲染也必须批量提交。我在这个项目上反复折腾之后最想分享的三条经验是这样的。第一先把平均邻居数打到 5 到 8 之间再谈别的这个区间之外的所有调参都是在白费力气。你可以写三行代码跑一帧然后统计所有个体的邻居数量取平均这个数字比任何视觉判断都准。第二所有能形成正反馈的参数组合最终都会走到极端状态聚合权重只要够大鱼群一定会塌缩对齐权重只要够大一定会变成僵硬的板块。这不是参数没调好而是动力学的必然。你要做的是把参数留在不稳定边缘的那一小片区域里那个位置的画面最好看也最脆弱稍微一动就会偏。**第三也是我最晚才意识到的一点视觉上好看的鱼群代码层面的数学往往不是最正确的。**比如严格按物理写的话转向力应该和质量、阻尼都挂钩但实际做出来最舒服的版本是砍掉了一大半物理项、只剩速度钳制和三个基础力的那一版。仿真的目标是看起来对不是算出来对这个心态转变之后调参会轻松很多。如果这套东西你已经跑顺了我会建议往两个方向扩展。一个是加捕食者——在画面里放一个移动的排斥源鱼群会立刻表现出逃逸、分流、重新聚合的复杂行为只用给原始的分离力再加一项远离捕食者代码改动不到二十行效果却像换了个项目。另一个是把平面的鱼放到三维空间里Boids 的所有公式在三维下完全不用改只需要把 Vec2 换成 Vec3、把邻域网格换成八叉树或者三维网格鱼群在体积里盘旋的画面比平面版本要震撼得多。