3K传奇引擎任务脚本编写完整教程 从基础框架到杀怪收集多阶段任务泛用写法与常见错误

3K引擎的任务脚本结构在所有主流传奇引擎中属于清晰度较高的，核心逻辑就是#IF条件判断、#ACT执行动作、#SAY对话显示三块内容的排列组合。下面从脚本存放路径、基础语法、杀怪任务完整写法、多阶段任务链设计、变量与进度存储、每日任务重置、自动寻路配置、调试排查八个方面拆解。

## 脚本文件存放路径与命名规则

3K引擎的任务脚本主要放在两个位置。NPC对话脚本放在 `Mirserver\Mir200\Envir\Market_Def\` 目录下，文件名建议与NPC名称一致，例如“任务使者.txt”。任务系统的入口脚本通常命名为QMission-0.txt，同样放在Market_Def目录下。杀怪计数和任务完成判定的逻辑可以写在QFunction-0.txt中，该文件位于 `Mirserver\Mir200\Envir\` 根目录下。

所有脚本文件必须保存为ANSI编码。用记事本编辑时，另存为窗口底部的编码下拉菜单要选ANSI，选UTF-8会导致中文全部乱码，脚本无法正常解析。文件后缀统一为.txt，写完后不需要编译，保存后重启服务端即可加载。

## 核心语法格式

传奇脚本的基础格式是@标识、#IF、#ACT、#SAY四段结构的组合。@后面跟触发标识，用英文中括号包裹，比如[@main]、[@接取任务]、[@完成任务]。标识名称可以自定义，但同一个脚本文件内不能重复，否则会触发冲突。

#IF后面跟条件判断命令，常用的有CHECKLEVEL检测等级、CHECKITEM检测背包物品数量、CHECKJOB检测职业、CHECKGAMEGOLD检测元宝数量、CHECK变量检测自定义变量值。条件不满足时，脚本会跳过#ACT段落直接执行#ELSEACT段落，没有写#ELSEACT的话则直接结束当前脚本段。

#ACT后面跟执行命令，所有执行类命令必须以英文分号结尾，遗漏分号会导致脚本中断。常用执行命令包括GIVE发放物品、TAKE扣除物品、GIVEGOLD发放金币、ADDEXP增加经验、SET设置变量、MAPMOVE传送地图、SENDMSG发送提示消息、GOTO跳转到指定标识。

#SAY后面跟对话显示内容。选项按钮的写法是 `<显示文字/@跳转标识>` ，点击后跳转到@后面的标识继续执行。需要换行时用反斜杠加空格，或者直接另起一行写。

命令全部大写是一个容易忽略的点，3K引擎部分命令对大小写敏感，统一大写可以避免不必要的报错。

## 杀怪任务完整脚本写法

杀怪任务的逻辑闭环是：NPC对话接取任务→脚本设置任务状态变量→玩家击杀目标怪物→脚本自动累加计数→返回NPC交任务→校验计数并发放奖励。

先写NPC接取脚本，放在Market_Def目录下的“任务使者.txt”中：

```
[@main]
#SAY
欢迎来到任务使者处，这里有简单的杀怪任务。
<接取任务/@接取蜈蚣任务>
<离开/@exit>

[@接取蜈蚣任务]
#IF
CHECK [700] 0
#ACT
SET [700] 1
SENDMSG 6 任务接取成功！前往蜈蚣洞杀死10只蜈蚣，完成后返回找我。
#SAY
任务已接取，祝你好运。
<关闭/@exit>
#ELSEACT
#SAY
你已经接取过这个任务了。
<关闭/@exit>
```

CHECK [700] 0 检测变量700是否为0，变量0代表未接取状态。SET [700] 1 将变量设为1，标记为已接取。这里的变量700是自定义编号，可以换成700到999之间的任意数字，但不能与版本中已有的任务变量重复。

杀怪计数脚本写在QFunction-0.txt中：

```
[@KillMonster]
#IF
CHECK [700] 1
CHECK [701] < 10
EQUAL <$KILLMONNAME> 蜈蚣
#ACT
INC [701] 1
SENDMSG 6 已击杀蜈蚣：<$STR([701])>/10
#IF
CHECK [700] 1
CHECK [701] = 10
#ACT
SET [700] 2
SENDMSG 6 蜈蚣击杀完成！返回任务使者处领取奖励。
```

[@KillMonster] 是怪物死亡时的系统触发标识，每次击杀怪物都会进入这个段落。EQUAL <$KILLMONNAME> 蜈蚣 判断被杀死的怪物名称是否为蜈蚣。INC [701] 1 将变量701自增1，用于记录击杀数。当701达到10时，将700设为2，标记为可交任务状态。

交任务脚本追加到“任务使者.txt”中：

```
[@完成任务]
#IF
CHECK [700] 2
#ACT
SET [700] 3
SET [701] 0
GIVE 经验丹 5
GIVEGOLD 10000
ADDEXP 5000
SENDMSG 6 任务完成！获得经验丹5个，金币10000。
#SAY
干得不错，这是你的奖励。
<关闭/@exit>
#ELSEACT
#SAY
你还没有完成任务。
<关闭/@exit>
```

同时在[@main]段落中追加选项 `<完成任务/@完成任务>` ，让玩家可以点击交任务。

## 多阶段任务链的变量设计

任务链的核心是用一个主变量记录任务总阶段，用附属变量记录各阶段的子进度。例如一个三阶段任务链：

变量800记录总阶段，0为未接取，1为第一阶段进行中，2为第二阶段进行中，3为第三阶段进行中，4为全部完成。变量801记录第一阶段杀怪数，变量802记录第二阶段收集物品数。

第一阶段接取时 SET [800] 1，完成后 SET [800] 2 同时 RESET [801]。第二阶段的CHECK条件写 CHECK [800] 2。第三阶段同理。这样设计的好处是玩家在任何时刻的进度都能通过查看变量800的值来判断当前应该执行哪段脚本，逻辑清晰且不容易出错。

多阶段之间的跳转用GOTO命令实现。例如第一阶段完成时直接 GOTO @第二阶段接取，不需要玩家重新找NPC对话，流程更顺畅。

## 变量类型与选择

3K引擎的任务进度存储主要依靠[000]-[999]区间的数字变量。这个区间的变量只有0和1两种状态，默认值为0，保存在人物DB中，下线后不会丢失。适合用来记录任务是否接取、是否完成这类二值状态。

需要记录击杀数量、收集数量这类连续数值的，使用D变量或M变量。D变量的格式是 D0-D9，M变量格式是 M0-M9。赋值用 MOV D0 5，自增用 INC D0 1，自减用 DEC D0 1，检测用 EQUAL D0 5 或 CHECK [D0] > 5 之类的写法。

变量名不能与版本中已有的其他任务变量冲突。如果版本中已经大量使用了700到750这段变量编号，新任务从800或850开始分配比较稳妥。

## 每日任务与零点重置

每日限次的任务需要在领取时记录玩家名字到一个文本文件，然后用机器人脚本在每天零点清理该文件。

领取脚本的写法：

```
[@main]
#SAY
每天可以在我这里领取一次奖励。
<领取奖励/@领取>
<离开/@exit>

[@领取]
#IF
CHECKGUILDLIST ..\QuestDiary\每日奖励名单.txt
#SAY
你今天已经领取过了。
<关闭/@exit>
#ELSEACT
GOTO @发放奖励

[@发放奖励]
#ACT
GIVEGOLD 50000
ADDGUILDLIST ..\QuestDiary\每日奖励名单.txt
SENDMSG 0 玩家[<$USERNAME>]领取了每日奖励！
```

CHECKGUILDLIST检测玩家名字是否在指定名单文件中。GIVEGOLD和ADDGUILDLIST分别在发放奖励和记录名单。

零点清理需要在AutoRunRobot.txt中增加一行：

```
#AutoRun NPC RUNONDAY 0:00 @清理每日名单
```

然后在RobotManage.txt中增加清理段落：

```
[@清理每日名单]
#ACT
CLEARNAMELIST ..\QuestDiary\每日奖励名单.txt
```

机器人脚本每天零点自动执行清理，名单清空后玩家第二天可以重新领取。

## 自动寻路配置

3K引擎支持在任务描述中嵌入可点击的自动寻路链接。基本写法是在#SAY段落中加入：

```
<任务路线(可点击进行自动寻路)：/FCOLOR=254>
英雄特使(白日门)(183.324)/@寻找英雄特使>
```

点击后跳转到@寻找英雄特使，该段落中执行 AUTOGOTOXY 183 324，人物会自动走到目标坐标。

跨地图自动寻路需要配合MapEvent.txt中的地图触发脚本。先在QMission-0.txt中设置起点传送：

```
[@自动寻路]
#IF
CHECK 0
#ACT
SET 1
MAPMOVE 0 337 112
#IF
CHECK 1
#ACT
AUTOGOTOXY 324 34
SET 1
```

然后在MapEvent.txt中设置地图到达触发，当玩家进入目标地图的指定坐标范围时，自动执行后续寻路：

```
1 560 554 5 -1:1 4:*:0 0 1:@MapEventWalk9
```

在QFunction-0.txt中增加对应的触发段落：

```
[@MapEventWalk9]
#IF
CHECK 1
#ACT
AUTOGOTOXY 560 540
RESET 2
```

这样玩家从比奇出发，经过传送点进入沃玛森林后会自动继续走到目标坐标，中间不需要手动操作。

## 常见错误与调试方法

脚本写完后不生效，先按以下顺序排查。

变量编号冲突是最常见的问题。如果两个任务使用了相同的变量编号，后加载的脚本会覆盖前一个的进度记录。检查版本中已有的任务变量分配表，新任务使用未占用的编号段。

CHECK条件与SET状态的对应关系容易写反。CHECK [700] 0 检测的是未接取状态，如果玩家已经接取了任务（变量为1），这个条件不成立，脚本会走#ELSEACT分支。接取脚本的CHECK必须写未接取时的变量值，交任务脚本的CHECK必须写可交任务时的变量值。

变量区间选择错误也会导致脚本异常。[000]-[999]区间只支持0和1两种状态，如果用这个区间的变量做INC自增操作，超过1之后数值会回绕，计数功能直接失效。需要计数的一律用D变量或M变量。

调试时可以在关键的条件判断前后插入 SENDMSG 6 当前步骤：@接取任务 这样的临时提示，观察脚本实际执行到了哪一步。M2控制台中输入 @ReloadRobot 可以重新加载机器人脚本，不需要重启整个服务端。修改NPC对话脚本后需要重启服务端，或者使用引擎自带的热加载功能重新加载Market_Def目录。

命令结尾的分号遗漏是最低级的错误，但排查起来最费时间。写完脚本后逐行检查#ACT段落中的每一行是否以分号结尾，SENDMSG、GIVE、SET、INC这些命令都不能漏。