hellclient-scripts · jarlyyn · Apr 23, 2026 · Apr 22, 2026 · Apr 23, 2026
diff --git a/doc/api/dll.md b/doc/api/dll.md
@@ -42,7 +42,7 @@
 * 参数2为编码
 * 返回值为 json bool值是否成功(已经打开地图为false)
 
-### export 到处当前地图
+### export 导出当前地图
 
 导出地图，可以用来import
 
@@ -100,4 +100,8 @@
 * tagroom
 * setroomdata
 * tracelocation
-* getroomexits
+* getroomexits
+
+## 范例代码
+
+参考[范例代码](./example/index.md)
diff --git a/doc/api/example/blocked.md b/doc/api/example/blocked.md
@@ -0,0 +1,149 @@
+# 临时拦截处理
+
+临时拦截处理是指路线有用，但是由于某些情况，比如NPC栏目，出口不可用，需要临时禁用的情况
+
+一般来说，由于拦路都会持续一段时间，为了避免多个出口被拦路造成两头循环跑的状况，会对拦路加以记录，一段时间都禁用该出口，而非仅一次拦路生效
+
+## lua代码
+```lua
+local hmmlib=require('hmm')
+local hmm=hmmlib.new()
+hmm.DllEncoding=0 --0 for utf-8, 1 for gbk
+local json=require('json')
+local file=assert(io.open("hongchen.hmm","r"))
+local data=file:read("*a")
+file:close();
+hmm:call("import",data)
+
+-- 模拟被拦截的房间
+local blockedroom="2440"
+-- 模拟被拦截的移动
+local blockedStep={["Command"]="e",["Target"]="2544",["Cost"]=1}
+
+-- 拦截管理器
+Blocker={}
+Blocker.__index = Blocker
+function Blocker:new()
+        local self = {}
+        self.Blocked={}
+        self.blockDuration=5*60 --默认封锁5分钟
+        return setmetatable(self, {__index = Blocker})
+end
+Blocker.block=function (self, room, step)
+    local data={}
+    data["from"]=room
+    data["to"]=step["Target"]
+    data["time"]=os.time()
+    self.Blocked[room.."\n"..step["Target"]]=data
+end
+Blocker.list=function (self)
+    local now=os.time()
+    local result={}
+    for key, value in pairs(self.Blocked) do
+        if now-value["time"]>self.blockDuration then
+            self.Blocked[key]=nil
+        else
+            local link=hmmlib.Link.new()
+            link.From=value["from"]
+            link.To=value["to"]
+            table.insert(result, link)
+        end
+    end
+    return result
+end
+local blocker=Blocker:new()
+
+local query=hmmlib.QueryPathAny.new()
+query.From={"2522"}
+query.Target={"3431"}
+
+local result=json.decode(hmm:call("querypathany", json.encode(query)))
+if (result==nil) then
+    print("No path found")
+else
+    print("Path found:")
+    print(json.encode(result))
+end
+
+blocker:block(blockedroom, blockedStep)
+query=hmmlib.QueryPathAny.new()
+query.From={"2522"}
+query.Target={"3431"}
+query.Environment=hmmlib.Environment.new()
+query.Environment.BlockedLinks=blocker:list()
+result=json.decode(hmm:call("querypathany", json.encode(query)))
+if (result==nil) then
+    print("No blocked path found")
+else
+    print("Blocked path found:")
+    print(json.encode(result))
+end
+```
+
+## python代码
+
+```python
+import json
+import hmmpy
+import datetime
+# 模拟被拦截的房间
+blockedroom="2440"
+# 模拟被拦截的移动
+blockedStep={"Command":"e","Target":"2544","Cost":1}
+# 拦截管理器
+class Blocker:
+    def __init__(self):
+        self.Blocked={}
+        self.blockDuration=datetime.timedelta(minutes=5)
+    def block(self,room,step):
+        self.Blocked[room+"\n"+step["Target"]]={"time":datetime.datetime.now(),"from":room,"to":step["Target"]}
+    def list(self):
+        now=datetime.datetime.now()
+        result=[]
+        for key in list(self.Blocked.keys()):
+            if now-self.Blocked[key]["time"]>self.blockDuration:
+                del self.Blocked[key]
+            else:
+                link=hmmpy.Link()
+                link.From=self.Blocked[key]["from"]
+                link.To=self.Blocked[key]["to"]
+                result.append(link)
+        return result
+blocker=Blocker()
+
+hmm = hmmpy.HMMDll("./HellMapManager.so")
+with open('hongchen.hmm', 'r', encoding='utf-8') as f:
+    hmm.call("import",f.read())
+
+query=hmmpy.QueryPathAny()
+query.From=["2522"]
+query.Target=["3431"]
+
+result=json.loads(hmm.call("querypathany", hmm.encode(query)))
+if (result==None):
+    print("No path found")
+else:
+    print("Path found:")
+    print(result)
+
+blocker.block(blockedroom, blockedStep)
+query=hmmpy.QueryPathAny()
+query.From=["2522"]
+query.Target=["3431"]
+query.Environment=hmmpy.Environment()
+query.Environment.BlockedLinks=blocker.list()
+result=json.loads(hmm.call("querypathany", hmm.encode(query)))
+if (result==None):
+    print("No blocked path found")
+else:
+    print("Blocked path found:")
+    print(result)
+```
+
+## 输出
+```
+Path found:
+{'From': '2522', 'To': '3431', 'Cost': 29, 'Steps': [{'Command': 'e', 'Target': '2440', 'Cost': 1}, {'Command': 'e', 'Target': '2544', 'Cost': 1}, {'Command': 'e', 'Target': '2494', 'Cost': 1}, {'Command': 'goto beijing', 'Target': '3432', 'Cost': 20}, {'Command': 'e', 'Target': '3436', 'Cost': 1}, {'Command': 'e', 'Target': '3500', 'Cost': 1}, {'Command': 'e', 'Target': '3501', 'Cost': 1}, {'Command': 'e', 'Target': '3404', 'Cost': 1}, {'Command': 'e', 'Target': '3430', 'Cost': 1}, {'Command': 'n', 'Target': '3431', 'Cost': 1}], 'Unvisited': []}
+Blocked path found:
+{'From': '2522', 'To': '3431', 'Cost': 51, 'Steps': [{'Command': 'e', 'Target': '2440', 'Cost': 1}, {'Command': 's', 'Target': '2439', 'Cost': 1}, {'Command': 's', 'Target': '2460', 'Cost': 1}, {'Command': 's', 'Target': '2504', 'Cost': 1}, {'Command': 's', 'Target': '2505', 'Cost': 1}, {'Command': 's', 'Target': '2506', 'Cost': 1}, {'Command': 's', 'Target': '1600', 'Cost': 1}, {'Command': 's', 'Target': '1602', 'Cost': 1}, {'Command': 's', 'Target': '1603', 'Cost': 1}, {'Command': 's', 'Target': '1604', 'Cost': 1}, {'Command': 'w', 'Target': '1605', 'Cost': 1}, {'Command': 'n', 'Target': '2560', 'Cost': 1}, {'Command': 'n', 'Target': '2616', 'Cost': 1}, {'Command': 'n', 'Target': '2615', 'Cost': 1}, {'Command': 'n', 'Target': '2619', 'Cost': 1}, {'Command': 'n', 'Target': '2618', 'Cost': 1}, {'Command': 'n', 'Target': '2617', 'Cost': 1}, {'Command': 'n', 'Target': '2575', 'Cost': 1}, {'Command': 'e', 'Target': '2568', 'Cost': 1}, {'Command': 'e', 'Target': '2569', 'Cost': 1}, {'Command': 'n', 'Target': '2571', 'Cost': 1}, {'Command': 'n', 'Target': '2572', 'Cost': 1}, {'Command': 'n', 'Target': '2590', 'Cost': 1}, {'Command': 'w', 'Target': '2610', 'Cost': 1}, {'Command': 'n', 'Target': '2601', 'Cost': 1}, {'Command': 'goto beijing', 'Target': '3432', 'Cost': 20}, {'Command': 'e', 'Target': '3436', 'Cost': 1}, {'Command': 'e', 'Target': '3500', 'Cost': 1}, {'Command': 'e', 'Target': '3501', 'Cost': 1}, {'Command': 'e', 'Target': '3404', 'Cost': 1}, {'Command': 'e', 'Target': '3430', 'Cost': 1}, {'Command': 'n', 'Target': '3431', 'Cost': 1}], 'Unvisited': []}
+```
diff --git a/doc/api/example/convert.md b/doc/api/example/convert.md
@@ -0,0 +1,123 @@
+# 数据转转
+
+数据转换指将其他地图格式的文件转换为hmm格式的地图信息。
+
+具体来说，分为几步
+
+* 使用create 接口 新建地图库
+* 建立所有的房间Room，至少保证有 Key(主键) Name(房间名),如果有区域的话设置为Group
+* 其他数据，比如小地图，特殊描述等,作为房间的Data，添加进房间的对应信息
+* 将房间以Key为主键放在一个字典/对象/表内
+* 将房间关系(出口)建立Exit，以 出发点，指令，目标 的形式设置为为 Exit的From,Command,To,如果可能的话，根据对Command进行判断，确定下具体的Exit Cost
+* 将Exit添加到对应的Room内
+* 将Room table转换为Room list
+* 使用 insertrooms接口将所有room添加到 地图库
+* 将所有房间的别名，创建Marker,Key为别名名称，Value为房间号。如果有附加信息，放在Marker的Message里
+* 使用insertmarkers接口将所有marked添加到 地图库
+* 如果一个房间的属性可能会变化，比如描述，则创建一个TakeSnapshot,Key为房间ID,Type为同一的类型(比如Desc),Value为具体描述，通过takesnapshot接口添加到地图库内
+* 通过export导出数据库文件，保存到本地，使用HMM程序打开观察细调
+
+## lua 代码
+```lua
+local hmmlib=require('hmm')
+local hmm=hmmlib.new()
+hmm.DllEncoding=0 --0 for utf-8, 1 for gbk
+local json=require('json')
+local roomsdata=readroomsdata()
+local roomlinks=readroomlinks()
+rooms={}
+for key,value in ipairs(roomsdata)
+    local key=value[1]
+    local takesnapshot=hmmlib.TakeSnapshot.new()
+    takesnapshot.Key=key
+    takesnapshot.Type="desc"
+    takesnapshot.Value=value[5]
+    hmm.call("takesnapshot",json.encode(takesnapshot))
+    if rooms[key]==nil then
+        room=hmmlib.Room.new()
+        room.Key=row[1]
+        room.Group=row[2]
+        room.Name=row[3]
+        relation=hmmlib.Data.new()
+        relation.Key="relation"
+        relation.Value=row[4]
+        table.insert(room.Data,relation)
+        chukou=hmmlib.Data()
+        chukou.Key="chukou"
+        chukou.Value=row[6]
+        table.insert(room.Data,chukou)
+        rooms[key]=room
+    end
+end
+for key,value in ipairs(roomlinks)
+    from_room=value[1]
+    command=value[2]
+    to_room=value[3]
+    exit=hmmlib.Exit.new()
+    exit.Command=command
+    exit.To=to_room
+    exit.From=from_room
+    exit.Cost=1
+    table.insert(rooms[from_room].Exits,exit)
+end
+inputrooms=hmmpy.Rooms.new()
+for key,value in rooms()
+    table.insert(inputrooms.Rooms,room)
+end
+hmm.call("insertrooms", json.encode(inputrooms))
+output=hmm.call("export")
+print(output)
+local file = assert(io.open("my.hmm", "w"))
+file:write(output)
+file:close()
+```
+## python 代码
+
+```python
+import hmmpy
+hmm=hmmpy.HMMDll("./HellMapManager.so")
+hmm.call("create")
+roomsdata=readroomsdata()
+roomlinks=readroomlinks()
+rooms={}
+for row in roomsdata:
+    key=row[0]
+    takesnapshot=hmmpy.TakeSnapshot()
+    takesnapshot.Key=key
+    takesnapshot.Type="desc"
+    takesnapshot.Value=row[4]
+    hmm.call("takesnapshot",hmm.encode(takesnapshot))
+    if rooms.get(key) is not None:
+        continue
+    room=hmmpy.Room()
+    room.Key=row[0]
+    room.Group=row[1]
+    room.Name=row[2]
+    relation=hmmpy.Data()
+    relation.Key="relation"
+    relation.Value=row[3]
+    room.Data.append(relation)
+    chukou=hmmpy.Data()
+    chukou.Key="chukou"
+    chukou.Value=row[5]
+    room.Data.append(chukou)
+    rooms[key]=room
+for row in roomlinks:
+    from_room=row[0]
+    command=row[1]
+    to_room=row[2]
+    exit=hmmpy.Exit()
+    exit.Command=command
+    exit.To=to_room
+    exit.From=from_room
+    exit.Cost=1
+    rooms[from_room].Exits.append(exit)
+inputrooms=hmmpy.Rooms()
+for room in rooms():
+    inputrooms.Rooms.append(room)
+hmm.call("insertrooms", hmm.encode(inputrooms))
+output=hmm.call("export")
+print(output)
+with open("my.hmm","w") as f:
+    f.write(output)
+```