hellclient-scripts · jarlyyn · Dec 31, 2025 · Dec 31, 2025 · Dec 31, 2025
diff --git a/README.md b/README.md
@@ -75,9 +75,11 @@ HMM使用基于CSV变种的HMM格式文件，便于阅读，以行为单位，
 
 在执行程序时，设置 -c 标志 ，并制定要打开的hmm/hmz文件，就能以不显示界面的方式提供http服务。
 
+![无头模式](doc/images/headless.png)
+
 可以没有图形界面的系统或者需要低CPU/内存消耗的场景下使用。
 
-[控制接口介绍](doc/api/headless.md)
+[无头模式控制接口介绍](doc/api/headless.md)
 
 ## 完善文档
 

diff --git a/doc/images/headless.png b/doc/images/headless.png
diff --git a/doc/images/tutorials/manual-beimen.png b/doc/images/tutorials/manual-beimen.png
diff --git a/doc/images/tutorials/manual-dzj.png b/doc/images/tutorials/manual-dzj.png
diff --git a/doc/images/tutorials/manual-list1.png b/doc/images/tutorials/manual-list1.png
diff --git a/doc/images/tutorials/manual-list2.png b/doc/images/tutorials/manual-list2.png
diff --git a/doc/images/tutorials/manual-list3.png b/doc/images/tutorials/manual-list3.png
diff --git a/doc/images/tutorials/manual-list4.png b/doc/images/tutorials/manual-list4.png
diff --git a/doc/images/tutorials/manual-list5.png b/doc/images/tutorials/manual-list5.png
diff --git a/doc/images/tutorials/manual-map.png b/doc/images/tutorials/manual-map.png
diff --git a/doc/images/tutorials/manual-newroom.png b/doc/images/tutorials/manual-newroom.png
diff --git a/doc/images/tutorials/manual-panel.png b/doc/images/tutorials/manual-panel.png
diff --git a/doc/images/tutorials/manual-pickroom.png b/doc/images/tutorials/manual-pickroom.png
diff --git a/doc/images/tutorials/manual-rmap1.png b/doc/images/tutorials/manual-rmap1.png
diff --git a/doc/images/tutorials/manual-rmap2.png b/doc/images/tutorials/manual-rmap2.png
diff --git a/doc/images/tutorials/manual-rmap3.png b/doc/images/tutorials/manual-rmap3.png
diff --git a/doc/images/tutorials/manual-rmap4.png b/doc/images/tutorials/manual-rmap4.png
diff --git a/doc/images/tutorials/manual-rmap5.png b/doc/images/tutorials/manual-rmap5.png
diff --git a/doc/index.md b/doc/index.md
@@ -1,5 +1,12 @@
 # 文档
 
+## 教程
+
+使用HellMapManager进行地图维护的教程
+
+* [教程：使用HellMapManager手动绘制地图](tutorials/manual.md)
+* [教程：利用HellMapManager建立定位系统](tutorials/locate.md)
+
 ## 基本概念和数据结构
 
 HMM的基本数据分为房间(Room),标记(Marker),路线(Route),足迹(Trace),地区(Region),定位(Landmark),捷径(Shortcut),变量(Variable),快照(Snapshot)等9中基本数据机构和一些子结构

diff --git a/doc/tutorials/locate.md b/doc/tutorials/locate.md
@@ -0,0 +1,119 @@
+# 教程：利用HellMapManager建立定位系统
+
+在Mud机器人的编写中，定位是非常重要的一件事情。有两种经典的定位方式十分常见
+
+* 房间特征表
+* 规则匹配
+
+本教程就是给出一个利用HellMapManager(HMM)来处理这两种信息进行定位的方式。
+
+## 定位数据
+
+定位(Landmark)是HMM中用来储存定位信息的一种数据结构。
+
+他主要有4个属性组成
+
+* 主键。建议使用对应房间的主键
+* 类型。告诉脚本用什么代码去使用这个定位
+* 分组。无实际用途，建议和房间的分组设置成一样方便管理
+* 值。具体的程序要来匹配的数据。
+
+定位每一组主键和类型不可重复。
+
+这意味着，一个主键可以有多个类型的匹配值。
+
+由于定位对于通过程序遍历更新数据极为重要，建议多使用几种不同的定位类型，防止Mud更新时整个机器的数据维护功能失效。
+
+## 种子定位
+
+种子定位指在手动画地图时，经过确认独一无二的定位。
+
+种子定位对于整个定位的建立十分重要。
+
+当所有定位方式都失效时，也可能需要手动更新一批种子定位来重新建立定位系统。
+
+## 规则匹配
+
+规则匹配最常见的是对描述进行正则匹配，极端情况下可以在值中存一段代码eval判断，但处于安全原因极不建议这么做。
+
+规则匹配的特点是
+
+* 无法自动化处理，完全依赖手动判断
+* 因为手动判断，所以更为可靠
+* 效率低。很可能需要遍历所有的规则进行判断，当规则很多时可能有性能问题。
+
+HMM建议建立地图时添加少量的规则匹配内容，作为种子定位。
+
+每一种规则，在Landmark中应该对应一个独立的类型
+
+规则匹配的话，在脚本加载时，可以放在一个数组/table里，在定位时通过for循环遍历的方式依次进行匹配。
+
+整体的数据结构应该是 第一层是个字典/对象/table,第二层是数组
+
+## 特征匹配
+
+特征匹配指根据不同的规则，给房间订立多套特征体系，比如：
+
+* 房间名
+* 房间名+出口
+* 房间名+描述
+* 完整描述
+* 描述起始固定字数
+* 描述结束固定字数
+* 地图
+* 房间的区域和其他信息
+
+把相应的信息生成对应的一个字符串。
+
+很明显，特征很多时候是过的维度组合起来的。
+
+到底有几个维度，怎么组合，这是根据Mud中的实际情况进行判断的。
+
+维度越多，则定位越快，但也越脆弱。
+
+有了特征组合后，我们可以通过给所有房间取特征，然后去掉有重复的，剩下的经过判断后就可以用来具体定位了。
+
+具体使用时，每一个特征组合应该是一个独立的Landmark的类型
+
+脚本加载时，同一组特征应该放在一个对象/字典/table里。
+
+具体机构应该是一个二维表
+
+进入房间后，把房间对应的特征值都计算出来，然后两次查表，确定是否有对应的定位记录。
+
+## 通过快照计算特征
+
+快照是HMM里的另一类数据结构。核心内容为
+
+* 主键，一般对应房间主键
+* 类型，代表快照的值记录的是什么
+* 分组。无实际用途，建议和房间的分组设置成一样方便管理
+* 值。具体的程序要来匹配的数据。
+* 重复次数。具体的唯一组合出现过几次
+
+快照的值数据结构和定位十分一致。代表的是机器人遍历到某个房间时，房间某类属性(描述/地图/对象)的具体值。
+
+由于部分信息可能是动态的，比如描述随着季节变化，或者npc可能有刷新或者移动，所以快照是以主键，类型，值为唯一组合。
+
+如果再次采集遇到相同的组合，则不会创建新纪录，而是将重复次数累加一次。
+
+很明显，快照就是通过机器采集数据时，收集到的用于定位的最原始的数据。
+
+HMM提供了一些简单接口，可以方便快速的找到匹配的快照，以完成有些Mud里对需要环境信息进行检索的人物。
+
+但从设计意图来说，快照是用来准备再次树立的原始数据。
+
+体现在定位中，就是
+
+1. 通过接口取出所有快照。
+2. 为每个房间通过快照计算出所有的特征值。
+3. 将特征组合对应的房间分别以特征值存入一个表内。
+4. 遍历表，将包含多个房间的表元素删除。
+5. 遍历表中剩下的元素(只有唯一房间的特征)，生成对应的定位数据。
+6. 将所有有效的定位数据通过接口进行更细。
+
+同时通过一定的场合进行冗余。
+
+这样，在每次Mud地图发生变化时，可以通过机器人自动对脚本进行维护。
+
+更进一步话，可以通过程序对比数据，验证现有的定位，有哪些在更新后已经失效。
diff --git a/doc/tutorials/manual.md b/doc/tutorials/manual.md
@@ -0,0 +1,187 @@
+# 教程：使用HellMapManager手动绘制地图
+
+这篇教程会简单的介绍通过HellMapManager的程序界面手动绘制一个区域的地图的过程。
+
+## 准备工作
+
+* 下载并安装最新的HMM软件
+* 新建一个新的HMM文件，保存为你的脚本能使用的编码(UTF8/GB18030)。如果准备以接口形式调用地图，可以保存为UTF*格式
+* 确定你要绘制地图的区域和起始位置。在这篇教程里选择的是某个MUD的佛山作为目标，大镇街作为起点。
+  ![地图](../images/tutorials/manual-map.png)
+* 打开你的客户端，进入你的角色，前往对应位置。
+
+## 绘制起点房间
+
+首先，在客户端里看一下当前房间的信息
+
+![房间](../images/tutorials/manual-dzj.png)
+
+然后，我们在hmm里点检房间，然后点击左上角的添加房间按钮。
+
+在弹出的新建窗口里，输入如下信息
+
+* 主键: foshan-dazhenjie
+* 名称: 大镇街
+* 分组: 佛山
+* 出口:
+  * 目标:???? 指令 n
+  * 目标:???? 指令 e
+  * 目标:???? 指令 s
+  * 目标:???? 指令 e
+* 描述： Landmark 大镇街
+
+结果如图
+
+![新建窗口](../images/tutorials/manual-newroom.png)
+
+解释：
+
+* 主键设置为不带业务数据的值。为了防止编码问题，建议使用字母数字的组合。
+* 名称一般就是房间名，便于管理。
+* 分组就是房间的地区。
+* 出口 的目标由于都不知道对应房间的信息，先都设为????，便于之后查遗补缺。
+* 描述是觉得这个房间可能可以用来定位，先标记下。
+
+添加结束后，应该在房间列表中出现一个单独的房间，如下图
+
+![列表图](../images/tutorials/manual-list1.png)
+
+## 进入房间关系地图
+
+在列表里，我们点击大镇街这个房间 操作这一栏里的查看房间关系地图按钮。
+
+点击之后，会出现一个地图关系地图
+
+![关系地图](../images/tutorials/manual-rmap1.png)
+
+这时候我们会看见只有一个孤零零的房间。
+
+我们开始以这个起点进行地图绘制。
+
+我们在客户端里 n 一步，来到新房间 北门
+
+![北门](../images/tutorials/manual-beimen.png)
+
+接着，回到HMM窗口，在关系地图界面点击新建按钮，会弹出一个同样的新建界面。
+
+这时候我们输入
+
+* 主键：foshan-beimen
+* 名称：北门
+* 分组：佛山
+* 出口：
+  * 目标 ???? 指令 n
+  * 目标 foshan-dazhenjie 指令 s
+
+很明显，由于我们知道 s 对应的是之前的房间，所以，可以直接在新建出口窗口里点击 目标右侧的 选取按钮，在选取窗口里选择 房间(或者你手输/复制粘贴也可以)：
+
+![选取房间](../images/tutorials/manual-pickroom.png)
+
+保存房间后，我们会发现关系地图进入了 我们新建的房间，而且和大镇街之间也有一个单向箭头
+
+![关系地图故2](../images/tutorials/manual-rmap2.png)
+
+## 维护房间关系
+
+我们现在有了两个房间了，接下去就要维护大镇街出口的消息。
+
+这是我们可以点击地图右上方的返回按钮(或者双击出口列表里对应大镇街的那条)
+
+回到大镇街，点击 左下方的编辑按钮，编辑n那个出口，指向北门
+
+保存后，会发现关系地图里两个地图 有了双向箭头
+
+![关系地图3](../images/tutorials/manual-rmap3.png)
+
+这时候双击那个不是????到foshan-beimen的n出口，或者双击地图上的 那个北门\(foshan-beimen\)/佛山的房间，关系地图就跳到北门了。
+
+这时候我们发现，北门也变成双向连接了。
+
+![关系地图4](../images/tutorials/manual-rmap4.png)
+
+很好，干得好，下一步，就是继续把这个区域的房间都登记进去了。
+
+这时候，可不用急着把所有出口都维护正确，这是下一步的工作。
+
+## 全面检查出口关系
+
+我们不停的重复上一步，很快，这个小镇的房间我们都画齐了。
+
+![关系地图5](../images/tutorials/manual-rmap5.png)
+
+然后我们看下列表，霍，28个房间了
+
+![列表2](../images/tutorials/manual-list2.png)
+
+这时候我们开始继续了。
+
+还记得我们之前用了很多????的出口吗？
+
+然我们搜索下
+
+```
+佛山,????
+```
+
+用逗号分割2个关键字，就能找到佛山分组下所有未更新的出口了
+
+![列表](../images/tutorials/manual-list3.png)
+
+嗯，发现明显有问题，感觉把这些出口的修复正确。
+
+## 更新定位
+
+还记得我们之前加的Landmark描述么？
+
+让我们在列表搜索
+
+```
+佛山,Landmark
+```
+![列表4](../images/tutorials/manual-list4.png)
+
+然后依次去那些房间核实是否适合做定位，可以的话，建立相应的定位。
+
+![列表5](../images/tutorials/manual-list5.png)
+
+那样，只有你的机器有合适的代码，就能加载这些数据后进行相应的定位了。
+
+## 使用数据
+
+更新好数据，我们肯定想看下怎么使用。
+
+使用可以通过hellmapmanager.ts项目提供的js和lua脚本，或者直接访问http接口方式进行。
+
+让我们用最他通用的http方式调用数据看看
+
+首先，让我们点击HMM接口窗口的启动。如果接口没被占用(比如其他HMM程序)，窗口最下方的**接口服务未启动**的信息，会变成 **接口服务正在监听8466端口**的信息：
+
+![信息](../images/tutorials/manual-panel.png)
+
+这时候我们就可以调用接口了。
+
+我们可以执行这个指令
+
+```
+curl -X POST -d '{"From":["foshan-dazhenjie"],"Target":["foshan-linjiandao7"]}' http://127.0.0.1:8466/api/db/querypathany
+```
+
+正常情况下，就会得到以下结果
+
+```json
+{"From":"foshan-dazhenjie","To":"foshan-linjiandao7","Cost":9,"Steps":[{"Command":"e","Target":"foshan-dongzhenjie","Cost":1},{"Command":"e","Target":"foshan-dongzhenjie2","Cost":1},{"Command":"e","Target":"foshan-dongmen","Cost":1},{"Command":"e","Target":"foshan-linjiandao","Cost":1},{"Command":"e","Target":"foshan-linjiandao2","Cost":1},{"Command":"e","Target":"foshan-linjiandao3","Cost":1},{"Command":"ne","Target":"foshan-linjiandao5","Cost":1},{"Command":"ne","Target":"foshan-linjiandao6","Cost":1},{"Command":"ne","Target":"foshan-linjiandao7","Cost":1}],"Unvisited":[]}
+```
+
+这个数据，用json格式解析下，就能得到一个每一步带坐标，方便惯性导航的路径了。
+
+## 更多完善
+
+在确保了房间之间映射关系正常，有定位信息后，就应该通过代码对路径进行遍历更新了。
+
+对于有特殊要求的房间，可以在出口上加入限制条件。
+
+对于房间本身的信息，比如室外，安全等，可以通过SetTag设置。
+
+各种描述，地图，npc等，可以抓取快照。
+
+手动绘制的部分只是主干，通过代码同步更新的部分才是逐渐生产出来的血肉。