CHUAN2 DEV ENGINE
996 正版授权研发中心 · 360 授权合作教学中心 · 抖音传奇直播合作授权 · 快手推广运营商授权
OFFICIAL LICENSED ACADEMY 查验官方授权证书 →
// 威海旷世互娱教学基地 · 技术文章
入门夯实996引擎注释开发规范

【入门夯实】注释先行:先写注释再填实现的写法

2026-09-24 16:24 作者:996 技术组 996引擎Lua教程传奇脚本入门夯实996引擎Lua注释开发规范

学员常见误区

注释是写完代码后的"补充说明",学员写完 50 行代码再补两行注释——注释描述的是"代码做了什么"(把 A 赋给 B),而不是"为什么这么做"。好的注释在写代码之前就已存在:先写注释描述意图,再填实现,注释才不会被代码变更甩在身后。错误场景:

lua
-- 处理
local function proc(actor, n)
    local r = n * 0.85
    if r > 100 then r = 100 end
    giveitem(actor, "祝福油", math.floor(r / 10))
end

0.85 是什么?为什么上限 100?半年后无人能答。

正确姿势

注释先描述"为什么"(业务规则),再写"怎么做"(代码实现):0.85 是强化成功率系数,100 是系统上限——业务规则注释化,代码只是规则的翻译。示例代码如下:

lua
-- 烈火剑法修炼系数:基础产出 × 0.85(系统衰减),上限 10 瓶(防囤积)
-- 业务规则:每次修炼消耗 1 本技能书,产出祝福油 1/10 概率翻倍
local function procCultivation(actor, skillBooks)
    actor = getplayerbyname(actor)
    local baseYield = skillBooks * 0.85
    local finalYield = math.min(10, math.floor(baseYield))
    if finalYield > 0 then
        giveitem(actor, "祝福油", finalYield)
    end
    sendmsg(actor, 1, "修炼完成,产出祝福油 " .. finalYield .. " 瓶。")
end

本篇的新技术点是"注释三问":为什么是这个值(0.85 的来源)?边界是什么(上限 10)?变了会怎样(影响祝福油产出)?三问齐答的注释才值得写。

引擎验证

三步验证:传入 skillBooks=5,产出应为 math.floor(5 × 0.85) = 4 瓶;传入 20 本应被上限 10 截断;注释里的每个数字(0.85、10)在代码中都有对应变量——注释与代码一一对应。

举一反三

注释先行的自然延伸是 TODO/FIXME 标记规范:临时方案标 FIXME(必须限期解决),待优化标 TODO(可以长期存在),让技术债可搜索可追踪。示例代码如下:

lua
-- FIXME: 临时用固定值,待接入活动系统后改为动态获取(2026-10 前完成)
local discountRate = 0.85
作者履历与出处

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付,内容以官方知识库与真实项目为出处,按版本持续修订。

← 返回文章地图返回研学路径

幂尔框架 · 实战干货 · 接口调用

LATEST ARTICLES

全站技术干货持续更新:996 引擎 / Lua 实战帖,语法、参数与示例一篇讲透。进入文章地图 · 查看全部 →

策划架构996引擎

【策划架构】负重系统:携带上限与移速的联动设计

设计初衷 背包无限装:药水带一百瓶、材料囤到爆——负重没有成本,背包管理沦为无脑囤积。负重系统设计:每件物品带重量,总负重超…

2026-09-25 17:48 996 技术组
策划架构996引擎

【策划架构】副手装备:主副手位的定位与收益设计

设计初衷 装备栏有武器位没有副手位:副手要么没用、要么变成第二武器直接双倍攻击——副手的定位从来没人讲清。副手装备设计:主手…

2026-09-25 17:48 996 技术组
高级技巧996引擎

【高级技巧】访问者模式:异构节点的分派处理封装

底层原理 对不同类型的节点执行不同操作(战绩流水里的击杀、阵亡、助攻各有统计口径),把操作散在类型判断里,每加一种操作就要改…

2026-09-25 17:48 996 技术组
高级技巧996引擎

【高级技巧】组合模式:整体与部分的同一接口设计

底层原理 行会的战力由成员战力组成、成员战力由装备组成——"整体"与"部分"要能用同一个接口对待:问行会战力与问成员战力是同…

2026-09-25 17:48 996 技术组
策划架构996引擎

【策划架构】增伤属性:技能增伤的乘区设计

设计初衷 输出成长只有堆攻击一条路:攻击加成稀释严重(基础 2000 再加 200 体感无几),成长反馈越来越钝。增伤属性设…

2026-09-25 17:48 996 技术组
进阶实战996引擎

【进阶实战】箭塔守御:固定炮台的索敌与开火封装

业务场景 驻地守御靠玩家人肉站桩:离线时段防务真空。箭塔守御封装:驻地点位部署箭塔(帮会资金建造),箭塔自动索敌(优先最近、…

2026-09-25 17:48 996 技术组