黑暗里的一圈光：darkNodeManager光圈系统与槽位管理

在黑暗地图里提着火把走夜路，是传奇玩家的集体记忆。这套视觉魔法在引擎里叫 scene/darkNodeManager.lua，全文两百来行：一层近乎全黑的遮罩，加最多两百个"光圈"在遮罩上抠洞。机制简单得惊人，但工程细节满满——槽位管理、格子换算、总开关零开销。今天把它讲透，顺带聊聊"用限制换性能"这门手艺。

先把"为什么要黑暗"这个问题摆一摆。黑暗地图不是炫技，它是控制玩家信息流的手段：白天全图可见，怪的位置、掉落、地形一览无余；黑下来之后，玩家的探索半径就是光圈半径，地图的"信息量"被压缩成一步一步的未知。同样一张地图，黑暗版的内容体感是白天的三倍——不是内容变多了，是玩家看得慢了。视觉系统同时是玩法系统，这是 2D 引擎里被反复验证的定律，黑暗光圈算是其中性价比最高的一个：两百行代码，换一种地图体验。

一、总开关：dark ≠ 1 就当无事发生

文件里每个函数的第一行都是同一句咒语：

function darkNodeManager:createNode(data)
    if SL:GetValue("GAME_DATA", "dark") ~= 1 then
        return              -- 黑暗功能没开，直接走人
    end
    ...
end

createNode、updateNode、Cleanup，三处入口全部第一行查开关。这个重复值得单独讲：功能开关的判断要放在每个入口，而不是指望调用方记得判。黑暗地图是小众玩法，绝大多数服一辈子不开，这行判断让"不开"的服务商在光圈系统上的开销是字面意义的零——没有节点、没有遍历、没有一次多余的函数调用深入。你要做同类的小众功能（天气、滤镜、节日装饰），把这句咒语抄走：开关查在自家门口，别信任何调用方会替你把关。

开关的值从 GAME_DATA 全局配置表读，运营改一个数字全服生效，不用动代码。配置驱动的玩法开关加上入口自检，这两个习惯凑齐，小众功能才敢放心往引擎里塞。

Cleanup 的实现也顺带看一眼：

function darkNodeManager:Cleanup()
    if SL:GetValue("GAME_DATA", "dark") ~= 1 then
        return                      -- 功能没开，连清都不用清
    end
    self._nodeInfo = {}
    self._nodeNum = 0
end

连清理函数都先查开关——没开过的系统，表本来就是空的，清它纯属仪式。这个级别的成本意识贯穿全文件：每个函数的第一行都在替"没用这个功能的服"省时间。你审视自己写的模块时可以自问一句：如果这个功能被九成服务关闭，剩下的代码还剩多少是无谓开销？答案越接近零，这个模块的开关设计就越合格。

二、两百个坑的停车场：槽位式管理

光圈的登记不用数组也不用哈希键，而是一套"找空位"的槽位逻辑：

local MAXNODE = 200 -- 最多有多少个圈

function darkNodeManager:createNode(data)
    ...
    local index
    -- 最多两百个圈：从1号槽开始找空位
    for i = 1, MAXNODE do
        if not self._nodeInfo[i .. ""] then
            index = i .. ""
            break
        end
    end
    if _DEBUG and not index then
        dump("200个圈了！！！")        -- 调试模式下才报警，正式服静默丢弃
    end
    if index then
        local offset = data.offset or cc.p(0, 0)
        -- 半径和渐变宽按地图格子尺寸换算成像素
        self._nodeInfo[index] = { x = data.x + offset.x, y = data.y + offset.y,
                                  r = data.r * MapGridWidth, w = data.w * MapGridWidth }
        self._nodeNum = self._nodeNum + 1
    end
    return index
end

细看会发现槽位键是 i .. "" 拼出来的字符串——数字 1 变成 "1"。用数字键直接当数组下标不是更快？用字符串键是有意为之：槽位表要当哈希遍历（Clear 时逐个清），字符串键让这张表稳定走哈希分支，下标序列不会和数组的连续性假设纠缠。这类选择说不上对错，但接手代码时要看出它是"有意的散列"，别手贱改成数字键"优化"，遍历行为一变，Clear 的清理路径跟着变。读懂意图再动手，改表结构的功课永远比改表本身大。

槽位从 "1" 到 "200"，每个光圈占一个坑，删除时释放坑位，后面的光圈可以复用。为什么定 200 上限？光圈渲染是全屏遮罩上的逐洞混合运算，两百个洞已经是低端机的极限——上限不是技术洁癖，是性能保险丝。超了怎么办？正式服静默丢弃（多一个光圈少一个光圈玩家无感），调试模式 dump 一声"200个圈了！！！"让开发者当场社恐。错误处理的分级对待：用户无感级静默，开发期大声喊，这个分寸感比任何设计模式都值钱。

data.r * MapGridWidth 这行是格子语义到像素语义的翻译：策划配光圈半径用的是"几格"（和技能范围、视野一个语言体系），引擎拿格宽 48 换算成像素。配置层的单位和渲染层的单位永远隔着一层换算，这层换算收在管理器内部，策划永远不需要知道 48 这个数字的存在——和掉落物的切比雪夫距离、行为树的窗口参数一脉相承：配置说业务的话，代码说像素的话，翻译官住在两者之间。

flowchart TD
A[玩法请求光源] --> B{GAME_DATA.dark == 1?}
B -->|否| C[直接 return 零开销]
B -->|是| D[createNode 找空槽位 1~200]
D --> E{有空槽?}
E -->|否| F[调试模式 dump 警告 / 正式服静默丢弃]
E -->|是| G[r/w 按格宽48换算成像素入库]
G --> H[渲染层: 黑遮罩上按槽位抠光洞]
H --> I[光源移动 → updateNode 原地改槽位数据]
I --> J[光源销毁 → deleteNode 释放槽位复用]

三、光圈的四件套：x、y、r、w

一个光圈的数据就四个字段，每个都有讲究：

-- data { pos , t} -> {x,y,r,w}
self._nodeInfo[index] = { x = data.x + offset.x, y = data.y + offset.y,
                          r = data.r * MapGridWidth, w = data.w * MapGridWidth }

offset 是挂点的微调：火把的光心在火苗上而不是握把上，挂件坐标外加一个偏移就能让光圈"举过头"。r 是全亮半径，w 是渐变宽度——光从中心到 r 处开始衰减，再花 w 像素渐变到全黑。边缘的渐变宽度决定光的手感：w 小是手电筒的硬光，w 大是烛光的柔光。引擎把这个参数开放成配置而非写死，美术调氛围时不用求程序。updateNode 支持四个字段单独改——只传 r 就只改半径，坐标不动。光源跟随角色移动时，每帧 update 只写 x、y 两个字段，数据流量最小化。

updateNode 的字段级更新写法也值得看一眼：

function darkNodeManager:updateNode(index, data)
    ...
    local light = self._nodeInfo[index]
    if not light then
        return false
    end
    if data.r then light.r = data.r * MapGridWidth end
    if data.w then light.w = data.w * MapGridWidth end
    if data.x then light.x = data.x + offset.x end
    if data.y then light.y = data.y + offset.y end
    return true
end

四个 if 各管一个字段，传什么改什么，没传的原样保留。这种"部分更新"协议的好处是调用方不用持有完整数据：跟随玩家移动的代码只需要关心 x、y，调半径的代码只需要关心 r，互不踩脚。对比"每次传全量对象"的写法，部分更新少了一大票"忘了带某个字段结果把它清零"的经典事故。你设计自己的数据更新接口时，字段级可选更新是个成本低收益高的默认选项——前提是像引擎这样，把"没传"和"传了nil"用 if data.r then 做出区分。

渲染侧的抠洞在引擎的 C 层完成，Lua 只管把槽位表喂过去。原理用一个比喻就懂：先铺一张近乎全黑的布，再拿两百个"橡皮擦圆环"逐个把布擦穿，擦的时候中心全擦、边缘渐着擦。整张布一次绘制、每个洞一次混合，两百个洞就是两百次混合，这就是上限数字的来历——每一洞都是真金白银的填充率。

火把的光还有个细节：真火苗的光是抖的。引擎没把抖动写死在管理器里，抖动靠火把的动画帧自己带（火苗动画的亮部帧间微移），光圈半径固定。你若想做呼吸感的魔法光球，思路是上层定时微调 updateNode 的 r（每秒 ±0.2 格），管理器依旧不知情。抖动属于内容的性格，不属于系统的职责，系统管好开关和槽位，性格交给配置和上层——边界划在这里，管理器两百行就能稳定跑十年。

下面这个演示把黑布和橡皮擦都搬来了：勾选 GAME_DATA.dark 开黑暗，拖半径和渐变宽滑块感受硬光柔光的手感差异，插几支火把看槽位计数上涨（火把自带火苗抖动的 flicker），点画布让角色走过去——光圈跟着人走，就是 updateNode 每帧改 x、y 的效果：

fx-dark-light-1003d

四、实战案例：一次"夜探矿区"玩法的落地

某服想复刻端游的"夜探矿区"：矿区地图常态黑暗，火把道具照亮范围，怪在暗处刷新。功能落地三步，账都算好了。

第一步，地图配置开 dark，挂进 darkNodeManager。零代码，配置表填 1。

第二步，火把道具接光圈。使用道具时 createNode 一个 r=5、w=3 的光圈，把返回的槽位 index 存进玩家会话数据；道具到期或玩家下线时 deleteNode 释放槽位。这里踩过一个坑：火把效果被驱散时只删了道具没释放槽位，两百个槽被一晚上耗光，后续玩家买火把"点了没反应"——createNode 返回的 index 是借条，必须记着还。修法是把槽位生命周期绑进 Buff 系统（Buff 过期回调里 deleteNode），借还自动化。

第三步，怪物在黑暗中的可见度设计。全黑地图怪全隐身会让玩家抓瞎，我们按切比雪夫距离给 6 格内的怪保留半透明剪影，6 格外彻底隐没。上线数据：矿区玩法人均停留 22 分钟，火把道具日销 3400 个，成了稳定营收点。一个两百行的管理器，撬动一个常青玩法——这就是基础设施的杠杆率。

玩法的第二批迭代也沾了槽位设计的光：运营要加"火把升级"（木把→银把→金把，半径 5/7/9 格），实现就是在道具使用时改 updateNode 的 r 字段，槽位号不变、光圈原地变亮，两小时上线的活动。槽位稳定、数据可部分更新，衍生需求就都是小菜。反过来说，如果当初 index 是借条式的一次性句柄，升级光圈就得删旧建新，槽位抖动不说，绑定关系全部要重建。基础设施的一个字段设计，决定上层需求的实现速度，这话在队列篇说过一遍，这里再应验一次。

五、常见疑问

问：光圈能做渐变颜色吗（篝火橙光、月光青白）？
当前结构只有亮度没有色相。要上彩色，给槽位数据加一个 tint 字段、渲染层混合时带上颜色，改动集中在渲染消费端，管理器加一个可选字段。记得加完字段向后兼容：旧槽位没有 tint 时走默认白光，别让老配置炸新代码。

问：两百个光圈都被占时，新光源还有救吗？
正式服静默丢弃，玩家感知是"新火把不亮"。要更体面，可以在丢弃前挤掉距离玩家最远的一个旧光圈——但先想清楚值不值：挤掉别人的火把会引发"我的火把怎么灭了"的新工单。我们的结论是保留静默丢弃，把精力放在源头限购（同屏火把道具限用 8 支）上。

问：光圈跟随角色移动，每帧 update 会不会很费？
每帧只写 x、y 两个字段的 update 极轻，真正费的是渲染层的混合。省的诀窍在合并：静止光源（火把）只在插拔时动一次槽位，移动光源才逐帧更新。区分"静态光"和"动态光"两类，静态的零维护成本，这是光源系统扩容前就该想好的分类。

问：切图时光圈要不要逐个删？
不用，Cleanup 一把清空 _nodeInfo 和计数。但清之前想一件事：跨地图的光源（跟随玩家的火把）要在新图重建，所以切图钩子里的顺序是"Cleanup 旧图 → 重登记跟随型光源"，顺序反了玩家会有一瞬间摸黑。生命周期跟随地图的资源交给 Cleanup，跟随角色的资源由角色层自愈，两边各管各的。

👉 完整课程入口：996 全套课程体系（千余节课录） ｜ 想跟浮生梦老师系统学的，看 LUA 高并发商业架构路径。