feat(debug): 支持网易 Minecraft 调试启动

新增 debug 子命令，自动准备开发世界、注册内置调试 MOD，并将项目行为包和资源包链接到网易运行目录，方便启动游戏后直接进入调试世界。

调试 MOD 资源随仓库一起嵌入，避免依赖本机绝对路径；Windows junction 写入剥离 verbatim 前缀后的 DOS 路径，保证 Minecraft 能正确读取链接包。

.gitignore

@@ -2,3 +2,4 @@
 .idea/
 .claude/
 .qoder/
+.mcdev.json

Cargo.lock

@@ -309,12 +309,14 @@ name = "emod-cli"
 version = "0.1.0-dev"
 dependencies = [
  "clap",
+ "rand",
  "regex",
  "serde",
  "serde_json",
  "toml",
  "uuid",
  "walkdir",
+ "windows-sys",
  "zip",
 ]
 

Cargo.toml

@@ -16,3 +16,17 @@ toml = "0.8"
 zip = "2.2.2"
 walkdir = "2"
 regex = "1.10"
+rand = "0.8"
+windows-sys = { version = "0.59", features = [
+    "Win32_Foundation",
+    "Win32_Networking_WinSock",
+    "Win32_Security",
+    "Win32_Storage_FileSystem",
+    "Win32_System_Console",
+    "Win32_System_Environment",
+    "Win32_System_IO",
+    "Win32_System_Pipes",
+    "Win32_System_SystemServices",
+    "Win32_System_Threading",
+    "Win32_UI_WindowsAndMessaging",
+] }

build.rs

@@ -6,10 +6,21 @@ use std::{
 
 const EMPTY_DIRS_FILE: &str = ".empty-dirs";
 
+const DEBUG_MOD_ROOT: &str = "debug_mod";
+
 fn main() {
     println!("cargo:rerun-if-changed=examples");
+    println!("cargo:rerun-if-changed={}", DEBUG_MOD_ROOT);
 
     let examples_root = PathBuf::from("examples");
+    let debug_mod_root = PathBuf::from(DEBUG_MOD_ROOT);
+    if !debug_mod_root.is_dir() {
+        panic!(
+            "required debug MOD resource directory was not found: {}",
+            DEBUG_MOD_ROOT
+        );
+    }
+
     let out_dir = PathBuf::from(env::var("OUT_DIR").expect("OUT_DIR is not set"));
     let out_file = out_dir.join("embedded_examples.rs");
 
@@ -17,6 +28,8 @@ fn main() {
     let mut files = Vec::new();
     let mut empty_dirs_by_example = BTreeMap::new();
 
+    let mut debug_mod_files = Vec::new();
+
     if examples_root.is_dir() {
         collect_examples(
             &examples_root,
@@ -27,6 +40,8 @@ fn main() {
         )
         .expect("failed to collect example templates");
     }
+    collect_files(&debug_mod_root, &debug_mod_root, &mut debug_mod_files)
+        .expect("failed to collect debug MOD resources");
 
     dirs.sort();
     dirs.dedup();
@@ -35,6 +50,7 @@ fn main() {
         empty_dirs.sort();
         empty_dirs.dedup();
     }
+    debug_mod_files.sort_by(|a, b| a.0.cmp(&b.0));
 
     let mut generated = String::new();
     generated.push_str(
@@ -45,7 +61,8 @@ fn main() {
         generated.push_str(&format!("    {:?},\n", dir));
     }
     generated.push_str("];\n\n");
-    generated.push_str("#[allow(dead_code)]\nstatic EMBEDDED_EXAMPLE_FILES: &[EmbeddedFile] = &[\n");
+    generated
+        .push_str("#[allow(dead_code)]\nstatic EMBEDDED_EXAMPLE_FILES: &[EmbeddedFile] = &[\n");
     for (relative_path, absolute_path) in &files {
         generated.push_str(&format!(
             "    EmbeddedFile {{ path: {:?}, contents: include_bytes!(r#\"{}\"#) }},\n",
@@ -70,9 +87,39 @@ fn main() {
         }
         generated.push_str("    ] },\n");
     }
+    generated.push_str("];\n\n");
+
+    generated
+        .push_str("#[allow(dead_code)]\nstatic EMBEDDED_DEBUG_MOD_FILES: &[EmbeddedFile] = &[\n");
+    for (relative_path, absolute_path) in &debug_mod_files {
+        generated.push_str(&format!(
+            "    EmbeddedFile {{ path: {:?}, contents: include_bytes!(r#\"{}\"#) }},\n",
+            relative_path,
+            absolute_path.display()
+        ));
+    }
     generated.push_str("];\n");
 
-    fs::write(out_file, generated).expect("failed to write embedded example list");
+    fs::write(out_file, generated).expect("failed to write embedded resource list");
+}
+
+fn collect_files(root: &Path, dir: &Path, files: &mut Vec<(String, PathBuf)>) -> io::Result<()> {
+    for entry in fs::read_dir(dir)? {
+        let entry = entry?;
+        let path = entry.path();
+        if path.is_dir() {
+            collect_files(root, &path, files)?;
+        } else if path.is_file() {
+            let relative_path = path
+                .strip_prefix(root)
+                .expect("embedded resource path is outside root")
+                .to_string_lossy()
+                .replace('\\', "/");
+            files.push((relative_path, path.canonicalize()?));
+        }
+    }
+
+    Ok(())
 }
 
 fn collect_examples(

debug_mod/DEBUG_ENV_SCRIPT/Config.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+from json import loads
+_DEBUG_INFO = "{#debug_options}"
+_TARGET_MOD_DIRS = "{#target_mod_dirs}"
+
+try:
+    DEBUG_CONFIG = loads(_DEBUG_INFO) if not isinstance(_DEBUG_INFO, dict) else _DEBUG_INFO
+except:
+    DEBUG_CONFIG = {}
+
+try:
+    TARGET_MOD_DIRS = loads(_TARGET_MOD_DIRS) if not isinstance(_TARGET_MOD_DIRS, list) else _TARGET_MOD_DIRS
+except:
+    TARGET_MOD_DIRS = []
+
+def GET_DEBUG_IPC_PORT():
+    import os
+    port = os.getenv("MCDEV_DEBUG_IPC_PORT")
+    if port is None:
+        return None
+    return int(port)

debug_mod/DEBUG_ENV_SCRIPT/Game.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+from common.utils import xupdate
+import mod.client.extraClientApi as clientApi
+from .Config import TARGET_MOD_DIRS
+
+def _RELOAD_MOD():
+    state = False
+    for rootModDir in TARGET_MOD_DIRS:
+        try:
+            if xupdate.updata_all(rootModDir):
+                state = True
+        except Exception:
+            import traceback
+            traceback.print_exc()
+    return state
+
+def INIT_RELOAD_TIME():
+    return xupdate.set_load_time()
+
+def SEND_CLIENT_MSG(msg):
+    import gui
+    print(msg)
+    gui.set_left_corner_notify_msg(msg)
+
+def RELOAD_MOD():
+    import gui
+    msg = "[Dev] Scripts reloaded successfully."
+    if not _RELOAD_MOD():
+        msg = "[Dev] No script updates found."
+    SEND_CLIENT_MSG(msg)
+
+def RELOAD_ONCE_MODULE(moduleName):
+    return xupdate.update(moduleName)
+
+def RELOAD_ADDON():
+    import gui
+    import clientlevel
+    clientlevel.refresh_addons()
+    SEND_CLIENT_MSG("[Dev] Add-ons reloaded successfully.")
+
+def RELOAD_WORLD():
+    import clientlevel
+    clientlevel.restart_local_game()
+
+def RELOAD_SHADERS():
+    import gui
+    if clientApi.ReloadAllShaders():
+        SEND_CLIENT_MSG("[Dev] Shaders reloaded successfully.")
+        return
+    SEND_CLIENT_MSG("[Dev] No shader updates found.")

debug_mod/DEBUG_ENV_SCRIPT/IPCSystem.py

@@ -0,0 +1,181 @@
+# -*- coding: utf-8 -*-
+import mod.server.extraServerApi as serverApi
+import mod.client.extraClientApi as clientApi
+from .Config import GET_DEBUG_IPC_PORT
+import socket
+import threading
+import json
+
+def U16_BE(b):
+    # type: (bytearray | str) -> int
+    if isinstance(b, bytearray):
+        return (b[0] << 8) | b[1]
+    return (ord(b[0]) << 8) | ord(b[1])
+
+def U32_BE(b):
+    # type: (bytearray | str) -> int
+    if isinstance(b, bytearray):
+        return (b[0] << 24) | (b[1] << 16) | (b[2] << 8) | b[3]
+    return (ord(b[0]) << 24) | (ord(b[1]) << 16) | (ord(b[2]) << 8) | ord(b[3])
+
+class IPCSystem:
+    def __init__(self, port=None):
+        # type: (int | None) -> None
+        self.port = port
+        self.sock = None
+        self.mLock = threading.Lock()
+        self.handers = {}
+
+    def registerHandler(self, typeID, handler):
+        # type: (int, callable) -> None
+        self.handers[typeID] = handler
+
+    def updateHandlers(self, handlers):
+        # type: (dict[int, callable]) -> None
+        self.handers.update(handlers)
+
+    def start(self):
+        if self.sock or not self.port:
+            return
+        threading.Thread(target=self._threadListenLoop).start()
+
+    def close(self):
+        sock = None
+        with self.mLock:
+            sock = self.sock
+            self.sock = None
+        if sock:
+            sock.shutdown(socket.SHUT_RDWR)
+            sock.close()
+
+    def _threadListenLoop(self):
+        with self.mLock:
+            self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock = self.sock
+        sock.connect(("localhost", self.port))
+        sock.settimeout(0.05)
+        print("[IPCSystem] 已连接到调试服务器，端口：" + str(self.port))
+        # [2B TypeID][4B DataLength][Data]
+        def _recvAll(sock, length):
+            # type: (socket.socket, int) -> bytearray
+            buf = bytearray()
+            while len(buf) < length:
+                more = sock.recv(length - len(buf))
+                if not more:
+                    raise EOFError("Socket closed before receiving all data")
+                buf.extend(more)
+            return buf
+        while 1:
+            try:
+                header = _recvAll(sock, 6)
+                typeID = U16_BE(header[0:2])
+                dataLength = U32_BE(header[2:6])
+                data = _recvAll(sock, dataLength)
+            except socket.timeout:
+                continue
+            except EOFError:
+                break
+            except socket.error:
+                break
+            except Exception:
+                import traceback
+                traceback.print_exc()
+                break
+            if typeID in self.handers:
+                try:
+                    self.handers[typeID](data)
+                except Exception:
+                    import traceback
+                    traceback.print_exc()
+            else:
+                print("[IPCSystem] 未知的TypeID数据包：" + str(typeID))
+        with self.mLock:
+            self.sock = None
+        print("[IPCSystem] 连接已关闭")
+
+_CL_GAME_COMP = None
+_SR_GAME_COMP = None
+
+def AUTO_RELOAD(_=None):
+    from .Game import RELOAD_MOD
+    if _CL_GAME_COMP:
+        _CL_GAME_COMP.AddTimer(0, lambda: RELOAD_MOD())
+        return
+
+def FAST_RELOAD(data):
+    from .Game import RELOAD_ONCE_MODULE
+    pathList = json.loads(str(data))
+    def _FAST_RELOAD():
+        for path in pathList:
+            if RELOAD_ONCE_MODULE(path):
+                print("[FAST_RELOAD] Reloaded module successfully: \"" + path + "\"")
+    if _CL_GAME_COMP:
+        _CL_GAME_COMP.AddTimer(0, _FAST_RELOAD)
+        return
+
+def EXEC_CLIENT_CODE(data):
+    code = compile(str(data), "<string>", "exec")
+    def _EXEC_CODE():
+        print("[CLIENT_CODE] Executed successfully: " + str(eval(code)))
+    _CL_GAME_COMP.AddTimer(0, _EXEC_CODE)
+
+def EXEC_SERVER_CODE(data):
+    code = compile(str(data), "<string>", "exec")
+    def _EXEC_CODE():
+        print("[SERVER_CODE] Executed successfully: " + str(eval(code)))
+    _SR_GAME_COMP.AddTimer(0, _EXEC_CODE)
+
+def RELOAD_GAME(_=None):
+    def _RELOAD_GAME():
+        from .Game import RELOAD_WORLD
+        print("[RELOAD_GAME] Reloading the game...")
+        RELOAD_WORLD()
+    _CL_GAME_COMP.AddTimer(0, _RELOAD_GAME)
+
+def RELOAD_SHADERS(_=None):
+    def _RELOAD_SHADERS():
+        from .Game import RELOAD_SHADERS
+        RELOAD_SHADERS()
+    _CL_GAME_COMP.AddTimer(0, _RELOAD_SHADERS)
+
+def RELOAD_ONCE_SHADERS(fileName):
+    def _RELOAD_ONCE_SHADERS():
+        if clientApi.ReloadOneShader(str(fileName)):
+            print("[RELOAD_ONCE_SHADERS] Reloaded shaders successfully.")
+            return
+        print("[RELOAD_ONCE_SHADERS] Failed to reload shaders.")
+    _CL_GAME_COMP.AddTimer(0, _RELOAD_ONCE_SHADERS)
+
+def RELOAD_ADDON_AND_GAME(_=None):
+    def _RELOAD_ADDON_AND_GAME():
+        from .Game import RELOAD_WORLD, RELOAD_ADDON
+        print("[RELOAD_ADDON_AND_GAME] Reloading the addon and the game...")
+        RELOAD_ADDON()
+        RELOAD_WORLD()
+    _CL_GAME_COMP.AddTimer(0, _RELOAD_ADDON_AND_GAME)
+
+_IPCSYSTEM = IPCSystem(GET_DEBUG_IPC_PORT())
+_IPCSYSTEM.updateHandlers(
+    {
+        1: AUTO_RELOAD,
+        2: FAST_RELOAD,
+        3: EXEC_CLIENT_CODE,
+        4: EXEC_SERVER_CODE,
+        5: RELOAD_GAME,
+        6: RELOAD_SHADERS,
+        7: RELOAD_ONCE_SHADERS,
+        8: RELOAD_ADDON_AND_GAME,
+    }
+)
+
+def ON_CLIENT_INIT():
+    global _CL_GAME_COMP
+    _CL_GAME_COMP = clientApi.GetEngineCompFactory().CreateGame(clientApi.GetLevelId())
+    _IPCSYSTEM.start()
+
+def ON_CLIENT_EXIT():
+    _IPCSYSTEM.close()
+
+def ON_SERVER_INIT():
+    global _SR_GAME_COMP
+    _SR_GAME_COMP = serverApi.GetEngineCompFactory().CreateGame(serverApi.GetLevelId())

debug_mod/DEBUG_ENV_SCRIPT/QuModLibs/IN.py

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+from .Util import SystemSide
+lambda: "By Zero123"
+
+IsServerUser = False
+ModDirName = SystemSide.__module__.split(".")[0]
+QuModLibsPath = SystemSide.__module__[:SystemSide.__module__.rfind(".")]
+
+class RuntimeService:
+    _serverSystemList = []
+    _clientSystemList = []
+    _serverStarting = False
+    _clientStarting = False
+    # LOADER SYSTEM
+    _serverLoadBefore = []      # type: list[function]
+    _clientLoadBefore = []      # type: list[function]
+    _serverLoadFinish = []      # type: list[function]
+    _clientLoadFinish = []      # type: list[function]
+    # THREAD ID
+    _serverThreadID = None
+    _clientThreadID = None
+    _envPlayerId = None
+
+def getUnderlineModDirName():
+    # type: () -> str
+    """ 获取下划线MOD目录名称 返回结果与preset内置变量__LQuModName__一致 (仅支持ascii字符串) """
+    newStr = []     # type: list[int]
+    for i, _charStr in enumerate(ModDirName):
+        _char = ord(_charStr)
+        if (_char >= 65 and _char <= 90):
+            # 大写内容 进行处理
+            if i > 0:
+                newStr.append(ord("_"))
+            newStr.append(_char + (97 - 65))
+            continue
+        # 常规小写内容 直接追加
+        newStr.append(_char)
+    return "".join((chr(x) for x in newStr))
+
+def GET_THREAD_ID():
+    """ 获取当前线程ID """
+    from threading import current_thread
+    return current_thread().ident
+
+def IS_SERVER_THREAD():
+    """ 检查是不是服务端线程 """
+    return RuntimeService._serverThreadID != None and GET_THREAD_ID() == RuntimeService._serverThreadID
+
+def IS_CLIENT_THREAD():
+    """ 检查是不是客户端线程 """
+    return RuntimeService._clientThreadID != None and GET_THREAD_ID() == RuntimeService._clientThreadID
+
+def GET_THREAD_TYPE():
+    """ 获取线程类型 -1.主线程 0.服务端线程 1.客户端线程 """
+    tid = GET_THREAD_ID()
+    if tid == RuntimeService._serverThreadID:
+        return 0
+    elif tid == RuntimeService._clientThreadID:
+        return 1
+    return -1

debug_mod/DEBUG_ENV_SCRIPT/QuModLibs/Information.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+Version = "1.4.1"                                               # 版本信息
+ApiVersion = 4                                                  # API版本
+Author = "Zero123"                                              # 创作者
+ContactInformation = "QQ:913702423"                             # 联系方式
+Other = """
+    # QuModLibs By Zero123(网易:游趣开发组) 别名:一灵 | h2v-wither123... BilBil-UID:456549011
+    # 开源协议: BSD(3)
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+"""

debug_mod/DEBUG_ENV_SCRIPT/QuModLibs/QuMod.py

@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+from mod.common.mod import Mod
+import mod.server.extraServerApi as serverApi
+import mod.client.extraClientApi as clientApi
+from .Util import TRY_EXEC_FUN
+from . import IN
+
+class _TempData:
+    """ modMain临时数据储存 包含了初始化注册的一些信息 """
+    _nativePyServer = []
+    _nativePyClient = []
+    _serverInitCall = []
+    _clientInitCall = []
+    _threadAnalysis = False
+
+@Mod.Binding(name = "QuMod_"+IN.ModDirName, version = "1.0.0")
+class QMain(object):
+    """ QuMod MAIN入口逻辑  """
+    def __init__(self):
+        pass
+
+    @Mod.InitServer()
+    def serverInit(self):
+        # 服务端初始化
+        IN.IsServerUser = True
+        self._regNativePyServer()
+        self._loadServerInitFuncs()
+        if _TempData._threadAnalysis:
+            from threading import current_thread
+            IN.RuntimeService._serverThreadID = current_thread().ident
+        if IN.RuntimeService._serverSystemList or IN.RuntimeService._serverLoadBefore:
+            from .Systems.Loader.Server import LoaderSystem
+            LoaderSystem.getSystem()    # 初始化服务端加载器
+
+    @Mod.InitClient()
+    def clientInit(self):
+        IN.RuntimeService._envPlayerId = clientApi.GetLocalPlayerId()
+        self._regNativePyClient()
+        self._loadClientInitFuncs()
+        if _TempData._threadAnalysis:
+            from threading import current_thread
+            IN.RuntimeService._clientThreadID = current_thread().ident
+        if IN.RuntimeService._clientSystemList or IN.RuntimeService._clientLoadBefore:
+            from .Systems.Loader.Client import LoaderSystem
+            LoaderSystem.getSystem()    # 初始化客户端加载器
+
+    def _regNativePyClient(self):
+        """ 加载原版Python客户端系统注册 """
+        for args in _TempData._nativePyClient:
+            clientApi.RegisterSystem(*args)
+        _TempData._nativePyClient = []
+
+    def _regNativePyServer(self):
+        """ 加载原版Python服务端系统注册 """
+        for args in _TempData._nativePyServer:
+            serverApi.RegisterSystem(*args)
+        _TempData._nativePyServer = []
+
+    def _loadServerInitFuncs(self):
+        """ 加载服务端初始化函数 """
+        for funObj in _TempData._serverInitCall:
+            TRY_EXEC_FUN(funObj)
+        _TempData._serverInitCall = []
+
+    def _loadClientInitFuncs(self):
+        """ 加载客户端初始化函数 """
+        for funObj in _TempData._clientInitCall:
+            TRY_EXEC_FUN(funObj)
+        _TempData._clientInitCall = []
+
+    @Mod.DestroyServer()
+    def serverDestroy(self):
+        pass
+
+    @Mod.DestroyClient()
+    def clientDestroy(self):
+        pass
+
+class EasyMod:
+    """ 简易Mod构造器 """
+    def __init__(self, modDirName=None):
+        # type: (str | None) -> None
+        self._modDirName = modDirName if modDirName else IN.ModDirName
+        """ Mod目录名 """
+
+    def regServer(self, relPath="", systemName=None):
+        # type: (str, str | None) -> EasyMod
+        """ 注册服务端(相对目录) """
+        REG_SERVER_MODULE("{}.{}".format(self._modDirName, relPath), systemName)
+        return self
+
+    def Server(self, relPath="", systemName=None):
+        # type: (str, str | None) -> EasyMod
+        """ 便捷式服务端注册 """
+        return self.regServer(relPath, systemName)
+
+    def Client(self, relPath="", systemName=None):
+        # type: (str, str | None) -> EasyMod
+        """ 便捷式客户端注册 """
+        return self.regClient(relPath, systemName)
+
+    def regClient(self, relPath="", systemName=None):
+        # type: (str, str | None) -> EasyMod
+        """ 注册客户端(相对目录) """
+        REG_CLIENT_MODULE("{}.{}".format(self._modDirName, relPath), systemName)
+        return self
+
+    def addServerInitCallFunc(self, callFunc=lambda: None):
+        # type: (object) -> EasyMod
+        """ 添加服务端初始化调用方法 """
+        REG_SERVER_INIT_CALL(callFunc)
+        return self
+
+    def addClientInitCallFunc(self, callFunc=lambda: None):
+        # type: (object) -> EasyMod
+        """ 添加客户端初始化调用方法 """
+        REG_CLIENT_INIT_CALL(callFunc)
+        return self
+
+def START_THREAD_ANALYSIS():
+    """ 启用线程分析 """
+    _TempData._threadAnalysis = True
+
+def STOP_THREAD_ANALYSIS():
+    """ 禁用线程分析 """
+    _TempData._threadAnalysis = False
+
+def REG_SERVER_MODULE(absPath, systemName=None, _index=-1):
+    # type: (str, str | None, int) -> None
+    """ 注册服务端模块 (绝对路径) """
+    if _index < 0:
+        return IN.RuntimeService._serverSystemList.append((absPath, systemName))
+    return IN.RuntimeService._serverSystemList.insert(_index, (absPath, systemName))
+
+def REG_CLIENT_MODULE(absPath, systemName=None, _index=-1):
+    # type: (str, str | None, int) -> None
+    """ 注册客户端模块 (绝对路径) """
+    if _index < 0:
+        return IN.RuntimeService._clientSystemList.append((absPath, systemName))
+    return IN.RuntimeService._clientSystemList.insert(_index, (absPath, systemName))
+
+def REG_SERVER_INIT_CALL(func=lambda: None):
+    # type: (function) -> function
+    """ 注册服务端初始化调用函数 """
+    _TempData._serverInitCall.append(func)
+    return func
+
+def REG_CLIENT_INIT_CALL(func=lambda: None):
+    # type: (function) -> function
+    """ 注册客户端初始化调用函数 """
+    _TempData._clientInitCall.append(func)
+    return func
+
+def PRE_SERVER_LOADER_HOOK(func=lambda: None):
+    # type: (function) -> function
+    """ 注册服务端加载器处理前的前置逻辑 (此时依然可以注册文件 该功能用于前置关联的校验处理) """
+    IN.RuntimeService._serverLoadBefore.append(func)
+    return func
+
+def PRE_CLIENT_LOADER_HOOK(func=lambda: None):
+    # type: (function) -> function
+    """ 注册客户端加载器处理前的前置逻辑 (此时依然可以注册文件 该功能用于前置关联的校验处理) """
+    IN.RuntimeService._clientLoadBefore.append(func)
+    return func

debug_mod/DEBUG_ENV_SCRIPT/QuModLibs/Systems/Loader/Client.py

@@ -0,0 +1,185 @@
+# -*- coding: utf-8 -*-
+import mod.client.extraClientApi as clientApi
+from ...Util import errorPrint, TRY_EXEC_FUN, getObjectPathName
+from ...IN import RuntimeService
+from .SharedRes import (
+    CallObjData,
+    EasyListener,
+    SERVER_CALL_EVENT,
+    CLIENT_CALL_EVENT,
+    NAMESPACE,
+    SYSTEMNAME
+)
+lambda: "By Zero123"
+ClientSystem = clientApi.GetClientSystemCls()
+engineSpaceName, engineSystemName = clientApi.GetEngineNamespace(), clientApi.GetEngineSystemName()
+
+def clientImportModule(filePath):
+    """ 客户端文件导入 """
+    return clientApi.ImportModule(filePath)
+
+class LoaderSystem(ClientSystem, EasyListener):
+    """ QuMod加载器系统
+        加载器承担了系统文件的加载以及事件监听 系统通信
+    """
+    @staticmethod
+    def getSystem():
+        # type: () -> LoaderSystem
+        """ 获取加载器系统 如果未注册将会自动注册并返回 """
+        system = clientApi.GetSystem(NAMESPACE, SYSTEMNAME)
+        if system:
+            return system
+        return clientApi.RegisterSystem(NAMESPACE, SYSTEMNAME, LoaderSystem.__module__ + "." + LoaderSystem.__name__)
+
+    _REG_CALL_FUNCS = {}
+    _REG_STATIC_LISTEN_FUNCS = {}
+    _DY_IMP_CACHE = {}
+
+    @staticmethod
+    def dyImportModule(modulePath):
+        if not modulePath in LoaderSystem._DY_IMP_CACHE:
+            LoaderSystem._DY_IMP_CACHE[modulePath] = clientImportModule(modulePath)
+        return LoaderSystem._DY_IMP_CACHE[modulePath]
+
+    @staticmethod
+    def REG_DESTROY_CALL_FUNC(func=lambda: None):
+        """ 适用于静态函数的注册销毁时回调 """
+        keyName = getObjectPathName(func)
+        if not keyName in LoaderSystem._REG_CALL_FUNCS:
+            # callFunc = lambda: LoaderSystem._REG_CALL_FUNCS[keyName]()
+            LoaderSystem.getSystem().addDestroyCall(func)
+        LoaderSystem._REG_CALL_FUNCS[keyName] = func
+
+    @staticmethod
+    def REG_STATIC_LISTEN_FUNC(eventName="", funcObj=lambda: None):
+        """ 注册静态监听函数 """
+        keyName = getObjectPathName(funcObj)
+        if not keyName in LoaderSystem._REG_STATIC_LISTEN_FUNCS:
+            # callFunc = lambda *args: LoaderSystem._REG_STATIC_LISTEN_FUNCS[keyName](*args)
+            LoaderSystem.getSystem().nativeStaticListen(eventName, funcObj)
+        LoaderSystem._REG_STATIC_LISTEN_FUNCS[keyName] = funcObj
+
+    def __init__(self, namespace, systemName):
+        ClientSystem.__init__(self, namespace, systemName)
+        EasyListener.__init__(self)
+        RuntimeService._clientStarting = True
+        self.namespace = namespace
+        self.systemName = systemName
+        self._systemList = RuntimeService._clientSystemList
+        self._initState = False
+        self._regInitState = False
+        self._waitTime = 0.0
+        self._callQueue = []    # type: list[CallObjData]
+        self._onDestroyCall = []
+        self._onDestroyCall_LAST = []
+        """ 后置销毁触发 通常是内部使用确保在用户业务之后执行 """
+        self._initSystemListen()
+        self.systemInit()
+
+    def _initSystemListen(self):
+        self.ListenForEvent(NAMESPACE, SYSTEMNAME, SERVER_CALL_EVENT, self, self._systemCallListener)
+
+    def _easyListenForEvent(self, eventName="", parent=None, func=lambda: None):
+        return self.ListenForEvent(engineSpaceName, engineSystemName, eventName, parent, func)
+
+    def _easyUnListenForEvent(self, eventName="", parent=None, func=lambda: None):
+        return self.UnListenForEvent(engineSpaceName, engineSystemName, eventName, parent, func)
+
+    def sendCall(self, apiName="", args=tuple(), kwargs=dict()):
+        """ 向服务器端请求调用 """
+        sendData = self._packageCallArgs(apiName, args, kwargs)
+        self.NotifyToServer(CLIENT_CALL_EVENT, sendData)
+
+    def addDestroyCall(self, funObj, doubleCheck=True):
+        """ 添加销毁触发 """
+        if doubleCheck and funObj in self._onDestroyCall:
+            return
+        self._onDestroyCall.append(funObj)
+
+    def removeDestroyCall(self, funObj):
+        """ 移除销毁触发 """
+        if funObj in self._onDestroyCall:
+            self._onDestroyCall.remove(funObj)
+
+    def Destroy(self):
+        # 用户级destroy执行
+        for obj in self._onDestroyCall:
+            TRY_EXEC_FUN(obj)
+        self._onDestroyCall = []
+        # 高权限destroy执行
+        for obj in self._onDestroyCall_LAST:
+            TRY_EXEC_FUN(obj)
+        self._onDestroyCall_LAST = []
+        RuntimeService._clientStarting = False
+
+    def getSystemList(self):
+        # type: () -> list[tuple[str, str | None]]
+        return self._systemList
+
+    def removeCallObjByUid(self, _uid = ""):
+        """ 尝试移除特定uid的callObj 如果存在 """
+        for i, obj in enumerate(self._callQueue):
+            if obj._uid == _uid:
+                del self._callQueue[i]
+                break
+
+    def proxyRegister(self, funcObj):
+        """ 代理注册 """
+        from functools import wraps
+        @wraps(funcObj)
+        def newFun(*args, **kwargs):
+            callObj = CallObjData(funcObj, args, kwargs)
+            self._callQueue.append(callObj)
+            return callObj
+        return newFun
+
+    def unsafeUpdate(self, callObjData):
+        # type: (CallObjData) -> bool
+        """ 不安全的强制刷新 """
+        if callObjData in self._callQueue:
+            self._callQueue.remove(callObjData)
+            callObjData.callObj(*callObjData.args, **callObjData.kwargs)
+            return True
+        return False
+
+    def Update(self):
+        self.regSystemInit()
+        if self._callQueue:
+            for obj in self._callQueue:
+                try:
+                    obj.callObj(*obj.args, **obj.kwargs)
+                except Exception as e:
+                    errorPrint("{} call执行异常 {}".format(obj.callObj, e))
+                    import traceback
+                    traceback.print_exc()
+            self._callQueue = []
+        return ClientSystem.Update(self)
+
+    def systemInit(self):
+        self._initState = True
+
+    def regSystemInit(self):
+        """ 系统信息注册初始化 """
+        if self._regInitState:
+            return
+        # 加载Before事件
+        for funcObj in RuntimeService._clientLoadBefore:
+            TRY_EXEC_FUN(funcObj)
+        # 因历史原因systemName已废弃 此处仅兼容旧版项目
+        for path, _ in self._systemList:
+            sysObj = None
+            try:
+                sysObj = clientImportModule(path)
+                if sysObj == None:
+                    errorPrint("[客户端] 系统文件加载失败(API异常): {}".format(path))
+                    continue
+            except Exception as e:
+                errorPrint("[客户端] 系统文件错误: {} ({})".format(path, e))
+                import traceback
+                traceback.print_exc()
+                continue
+            # if not systemName: systemName = uuid4().hex
+        self._regInitState = True
+        # 加载Finish事件
+        for funcObj in RuntimeService._clientLoadFinish:
+            TRY_EXEC_FUN(funcObj)

debug_mod/DEBUG_ENV_SCRIPT/QuModLibs/Systems/Loader/Server.py

@@ -0,0 +1,200 @@
+# -*- coding: utf-8 -*-
+import mod.server.extraServerApi as serverApi
+from ...Util import errorPrint, TRY_EXEC_FUN, getObjectPathName
+from ...IN import RuntimeService
+from .SharedRes import (
+    CallObjData,
+    EasyListener,
+    SERVER_CALL_EVENT,
+    CLIENT_CALL_EVENT,
+    NAMESPACE,
+    SYSTEMNAME
+)
+lambda: "By Zero123"
+ServerSystem = serverApi.GetServerSystemCls()
+engineSpaceName, engineSystemName = serverApi.GetEngineNamespace(), serverApi.GetEngineSystemName()
+
+def serverImportModule(filePath):
+    """ 服务端文件导入 """
+    return serverApi.ImportModule(filePath)
+
+class LoaderSystem(ServerSystem, EasyListener):
+    """ QuMod加载器系统
+        加载器承担了系统文件的加载以及事件监听 系统通信
+    """
+    @staticmethod
+    def getSystem():
+        # type: () -> LoaderSystem
+        """ 获取加载器系统 如果未注册将会自动注册并返回 """
+        system = serverApi.GetSystem(NAMESPACE, SYSTEMNAME)
+        if system:
+            return system
+        return serverApi.RegisterSystem(NAMESPACE, SYSTEMNAME, LoaderSystem.__module__ + "." + LoaderSystem.__name__)
+
+    _REG_CALL_FUNCS = {}
+    _REG_STATIC_LISTEN_FUNCS = {}
+    _DY_IMP_CACHE = {}
+
+    @staticmethod
+    def dyImportModule(modulePath):
+        if not modulePath in LoaderSystem._DY_IMP_CACHE:
+            LoaderSystem._DY_IMP_CACHE[modulePath] = serverImportModule(modulePath)
+        return LoaderSystem._DY_IMP_CACHE[modulePath]
+
+    @staticmethod
+    def REG_DESTROY_CALL_FUNC(func=lambda: None):
+        """ 适用于静态函数的注册销毁时回调 """
+        keyName = getObjectPathName(func)
+        if not keyName in LoaderSystem._REG_CALL_FUNCS:
+            # callFunc = lambda: LoaderSystem._REG_CALL_FUNCS[keyName]()
+            LoaderSystem.getSystem().addDestroyCall(func)
+        LoaderSystem._REG_CALL_FUNCS[keyName] = func
+
+    @staticmethod
+    def REG_STATIC_LISTEN_FUNC(eventName="", funcObj=lambda: None):
+        """ 注册静态监听函数 """
+        keyName = getObjectPathName(funcObj)
+        if not keyName in LoaderSystem._REG_STATIC_LISTEN_FUNCS:
+            # callFunc = lambda *args: LoaderSystem._REG_STATIC_LISTEN_FUNCS[keyName](*args)
+            LoaderSystem.getSystem().nativeStaticListen(eventName, funcObj)
+        LoaderSystem._REG_STATIC_LISTEN_FUNCS[keyName] = funcObj
+
+    def __init__(self, namespace, systemName):
+        ServerSystem.__init__(self, namespace, systemName)
+        EasyListener.__init__(self)
+        RuntimeService._serverStarting = True
+        self.namespace = namespace
+        self.systemName = systemName
+        self.rpcPlayerId = None
+        self._systemList = RuntimeService._serverSystemList
+        self._initState = False
+        self._regInitState = False
+        self._waitTime = 0.0
+        self._onDestroyCall = []
+        self._onDestroyCall_LAST = []
+        """ 后置销毁触发 通常是内部使用确保在用户业务之后执行 """
+        self._initSystemListen()
+        self.systemInit()
+
+    def _systemCallListenerHook(self, args={}):
+        target = "__id__"
+        if target in args:
+            self.rpcPlayerId = args[target]
+            return
+        self.rpcPlayerId = None
+
+    def _initSystemListen(self):
+        self.ListenForEvent(NAMESPACE, SYSTEMNAME, CLIENT_CALL_EVENT, self, self._systemCallListener)
+
+    def _easyListenForEvent(self, eventName="", parent=None, func=lambda: None):
+        return self.ListenForEvent(engineSpaceName, engineSystemName, eventName, parent, func)
+
+    def _easyUnListenForEvent(self, eventName="", parent=None, func=lambda: None):
+        return self.UnListenForEvent(engineSpaceName, engineSystemName, eventName, parent, func)
+
+    def sendCall(self, playerId="", apiName="", args=tuple(), kwargs=dict()):
+        """ 向指定玩家客户端请求调用 当playerId声明为*时代表全体玩家 """
+        sendData = self._packageCallArgs(apiName, args, kwargs)
+        if playerId == "*":
+            self.BroadcastToAllClient(SERVER_CALL_EVENT, sendData)
+            return
+        self.NotifyToClient(playerId, SERVER_CALL_EVENT, sendData)
+
+    def sendMultiClientsCall(self, playerListId=[], apiName="", args=tuple(), kwargs=dict()):
+        """ 批量向多个玩家客户端发包相同的调用数据 """
+        sendData = self._packageCallArgs(apiName, args, kwargs)
+        self.NotifyToMultiClients(playerListId, SERVER_CALL_EVENT, sendData)
+
+    def addDestroyCall(self, funObj, doubleCheck=True):
+        """ 添加销毁触发 """
+        if doubleCheck and funObj in self._onDestroyCall:
+            return
+        self._onDestroyCall.append(funObj)
+
+    def removeDestroyCall(self, funObj):
+        """ 移除销毁触发 """
+        if funObj in self._onDestroyCall:
+            self._onDestroyCall.remove(funObj)
+
+    def Destroy(self):
+        # 用户级destroy执行
+        for obj in self._onDestroyCall:
+            TRY_EXEC_FUN(obj)
+        self._onDestroyCall = []
+        # 高权限destroy执行
+        for obj in self._onDestroyCall_LAST:
+            TRY_EXEC_FUN(obj)
+        self._onDestroyCall_LAST = []
+        RuntimeService._serverStarting = False
+
+    def getSystemList(self):
+        # type: () -> list[tuple[str, str | None]]
+        return self._systemList
+
+    def removeCallObjByUid(self, _uid = ""):
+        """ 尝试移除特定uid的callObj 如果存在 """
+        for i, obj in enumerate(self._callQueue):
+            if obj._uid == _uid:
+                del self._callQueue[i]
+                break
+
+    def proxyRegister(self, funcObj):
+        """ 代理注册 """
+        from functools import wraps
+        @wraps(funcObj)
+        def newFun(*args, **kwargs):
+            callObj = CallObjData(funcObj, args, kwargs)
+            self._callQueue.append(callObj)
+            return callObj
+        return newFun
+
+    def unsafeUpdate(self, callObjData):
+        # type: (CallObjData) -> bool
+        """ 不安全的强制刷新 """
+        if callObjData in self._callQueue:
+            self._callQueue.remove(callObjData)
+            callObjData.callObj(*callObjData.args, **callObjData.kwargs)
+            return True
+        return False
+
+    def Update(self):
+        self.regSystemInit()
+        if self._callQueue:
+            for obj in self._callQueue:
+                try:
+                    obj.callObj(*obj.args, **obj.kwargs)
+                except Exception as e:
+                    errorPrint("{} call执行异常 {}".format(obj.callObj, e))
+                    import traceback
+                    traceback.print_exc()
+            self._callQueue = []
+        return ServerSystem.Update(self)
+
+    def systemInit(self):
+        self._initState = True
+
+    def regSystemInit(self):
+        """ 系统信息注册初始化 """
+        if self._regInitState:
+            return
+        # 加载Before事件
+        for funcObj in RuntimeService._serverLoadBefore:
+            TRY_EXEC_FUN(funcObj)
+        # 因历史原因systemName已废弃 此处仅兼容旧版项目
+        for path, _ in self._systemList:
+            sysObj = None
+            try:
+                sysObj = serverImportModule(path)
+                if sysObj == None:
+                    errorPrint("[服务端] 系统文件加载失败(API异常): {}".format(path))
+                    continue
+            except Exception as e:
+                errorPrint("[服务端] 系统文件错误: {} ({})".format(path, e))
+                import traceback
+                traceback.print_exc()
+                continue
+            # if not systemName: systemName = uuid4().hex
+        self._regInitState = True
+        # 加载Finish事件
+        for funcObj in RuntimeService._serverLoadFinish:
+            TRY_EXEC_FUN(funcObj)

debug_mod/DEBUG_ENV_SCRIPT/QuModLibs/Systems/Loader/SharedRes.py

@@ -0,0 +1,175 @@
+# -*- coding: utf-8 -*-
+from uuid import uuid4
+from ...IN import ModDirName
+from ...Util import QStruct
+
+class CallObjData:
+    def __init__(self, callObj, args = tuple(), kwargs = {}):
+        self.callObj = callObj
+        self.args = args
+        self.kwargs = kwargs
+        self._uid = None
+
+class EmptyContext:
+    pass
+
+NAMESPACE = "Qu_" + ModDirName
+SYSTEMNAME = "{}_QLoader_system".format(ModDirName)
+SERVER_CALL_EVENT = "{}_QServer".format(ModDirName)
+CLIENT_CALL_EVENT = "{}_QClient".format(ModDirName)
+
+class EasyListener:
+    def __init__(self):
+        self._callQueue = []    # type: list[CallObjData]
+        self._emptyContext = EmptyContext()
+        self._QCustomAPI = {}   # type: dict[str, function]
+
+    def regCustomApi(self, apiName="", func=lambda: None):
+        """ 注册自定义API """
+        self._QCustomAPI[apiName] = func
+
+    def removeCustomApi(self, apiName=""):
+        """ 删除指定API如果存在 """
+        if apiName in self._QCustomAPI:
+            del self._QCustomAPI[apiName]
+
+    def getCustomApi(self, apiName=""):
+        """ 获取自定义API如果存在 """
+        return self._QCustomAPI.get(apiName)
+
+    def localCall(self, apiName="", *args, **kwargs):
+        """ 本地调用 请确保API函数存在注册 否则抛出异常 """
+        return self._QCustomAPI[apiName](*args, **kwargs)
+
+    def _systemCallListener(self, args={}):
+        """ 系统call机制监听器(接收消息处理) """
+        api = args["api"]
+        ag = EasyListener._unPackRefArgs(args["args"])
+        kwargs = EasyListener._unPackRefDictArgs(args["kw"])
+        self._systemCallListenerHook(args)
+        return self.localCall(api, *ag, **kwargs)
+
+    def _systemCallListenerHook(self, _={}):
+        pass
+
+    @staticmethod
+    def _unPackRefArgs(data):
+        # type: (list) -> list
+        """ Ref解包Args数据 """
+        for i, v in enumerate(data):
+            if QStruct.isSignData(v):
+                data[i] = QStruct.loadSignData(v).onNetUnPack()
+        return data
+
+    @staticmethod
+    def _unPackRefDictArgs(data):
+        # type: (dict) -> dict
+        """ Ref解包Dict Args数据 """
+        for k, v in data.items():
+            if QStruct.isSignData(v):
+                data[k] = QStruct.loadSignData(v).onNetUnPack()
+        return data
+
+    @staticmethod
+    def _packArgs(data):
+        # type: (tuple | list) -> list
+        """ 打包Args数据 """
+        newDataList = []
+        for v in data:
+            if isinstance(v, QStruct):
+                newDataList.append(v.signDumps())
+                continue
+            newDataList.append(v)
+        return newDataList
+
+    @staticmethod
+    def _packDictArgs(data):
+        # type: (dict) -> dict
+        """ 打包Dict数据 keyName=xxx """
+        newDict = {}
+        for k, v in data.items():
+            if isinstance(v, QStruct):
+                newDict[k] = v.signDumps()
+                continue
+            newDict[k] = v
+        return newDict
+
+    def _packageCallArgs(self, apiName="", args=tuple(), kwargs=dict()):
+        """ 打包API参数(发送消息处理) """
+        return {"api":apiName,"args":EasyListener._packArgs(args),"kw":EasyListener._packDictArgs(kwargs)}
+
+    def mallocRandomMetName(self):
+        """ 动态分配随机方法名 """
+        randomName = ""
+        while not randomName or hasattr(self, randomName):
+            randomName = "Q_{}".format(uuid4().hex)
+        return randomName
+
+    def _allocMethodWithOUTFunction(self, callFunc=lambda *_: None):
+        """ 基于外部函数分配一个映射的内部方法(介于网易Listen必须依赖内部方法 故有了该方法) """
+        newFuncName = self.mallocRandomMetName()
+        newFunc = lambda *args, **kwargs: callFunc(*args, **kwargs)
+        newFunc.__name__ = newFuncName
+        setattr(self, newFuncName, newFunc)
+        return newFunc
+
+    def _delMethod(self, methodFunc=lambda *_: None):
+        """ 对照与_allocMethodWithOUTFunction的反向删除 """
+        try:
+            delattr(self, methodFunc.__name__)
+        except Exception:
+            pass
+
+    def nativeStaticListen(self, eventName="", callFunc=lambda *_: None):
+        """ 原生静态监听注册 不支持运行时注销 """
+        def _reg():
+            self._easyListenForEvent(eventName, self, self._allocMethodWithOUTFunction(callFunc))
+        self._callQueue.append(CallObjData(_reg))
+
+    def nativeListen(self, eventName="", parent=None, callFunc=lambda *_: None, updateNow=False):
+        # type: (str, object, object, bool) -> CallObjData | None
+        """ 原生动态监听 当updateNow声明为False时将会添加到系统队列安全的等待注册 """
+        if not parent:
+            parent = self._emptyContext
+        newFuncName = "QListen{}_{}".format(id(parent), callFunc.__name__)
+        newFunc = lambda *args: callFunc(*args)
+        newFunc.__name__ = newFuncName
+        if hasattr(self, newFuncName):
+            print("[Error] 请勿在单个可执行对象上监听重复的事件")
+            return None
+        def _reg():
+            setattr(self, newFuncName, newFunc)
+            self._easyListenForEvent(eventName, self, newFunc)
+        waitCallObj = CallObjData(_reg)
+        waitCallObj._uid = newFuncName
+        self._callQueue.append(waitCallObj)
+        if updateNow:
+            self.unsafeUpdate(waitCallObj)
+        return waitCallObj
+
+    def unNativeListen(self, eventName="", parent=None, callFunc=lambda *_: None):
+        # type: (str, object, object) -> None
+        """ 取消特定方法的原生动态监听 """
+        if not parent:
+            parent = self._emptyContext
+        newFuncName = "QListen{}_{}".format(id(parent), callFunc.__name__)
+        if hasattr(self, newFuncName):
+            # 已注册完毕的监听处理
+            self._easyUnListenForEvent(eventName, self, getattr(self, newFuncName))
+            delattr(self, newFuncName)
+            return
+        # 在队列中等待注册的监听处理
+        self.removeCallObjByUid(newFuncName)
+
+    def unsafeUpdate(self, callObjData):
+        # type: (CallObjData) -> bool
+        pass
+
+    def _easyListenForEvent(self, eventName="", parent=None, func=lambda: None):
+        pass
+
+    def _easyUnListenForEvent(self, eventName="", parent=None, func=lambda: None):
+        pass
+
+    def removeCallObjByUid(self, _uid = ""):
+        pass

debug_mod/DEBUG_ENV_SCRIPT/QuModLibs/Util.py

@@ -0,0 +1,89 @@
+# -*- coding: utf-8 -*-
+from functools import wraps
+from time import time
+import pickle as _pickle
+
+class SystemSide(object):
+    def __init__(self, Path, SystemName = None):
+        self.SystemName = SystemName # 绑定系统
+        self.Path = Path
+
+ModDirName = SystemSide.__module__.split(".")[0]
+
+def errorPrint(charPtr):
+    """ 异常输出 """
+    print("[Error] "+str(charPtr))
+
+def TRY_EXEC_FUN(funObj, *args, **kwargs):
+    try:
+        return funObj(*args, **kwargs)
+    except Exception as e:
+        import traceback
+        print("TRY_EXEC发生异常: {}".format(e))
+        traceback.print_exc()
+
+def getObjectPathName(_callObj = lambda: None):
+    # type: (object) -> str
+    """ 获取可执行对象的目录名 """
+    return ".".join((_callObj.__module__, _callObj.__name__))
+
+class QStruct:
+    """ 结构体 用于通用数据模型约定(即不涉及任何API) 应定义在Server/Client以外的通用文件 同理Struct也不应该持有任何涉及端侧API的内容 """
+    _SIGN_FORMAT = "_QSTRUCT[{}]"
+    def dumps(self):
+        """ 序列化对象 """
+        return _pickle.dumps(self)
+
+    def signDumps(self):
+        """ 带有特征签名的序列化 """
+        data = self.dumps()
+        return [QStruct._SIGN_FORMAT.format(hex(hash(data))), data]
+
+    @staticmethod
+    def isSignData(data):
+        """ 校验数据 """
+        if not isinstance(data, list) or len(data) != 2:
+            return False
+        signKey = data[0]
+        if isinstance(signKey, str):
+            dataObj = data[1]
+            return signKey == QStruct._SIGN_FORMAT.format(hex(hash(dataObj)))
+        return False
+
+    @staticmethod
+    def loads(data):
+        # type: (str) -> QStruct
+        """ 反序列化加载对象 """
+        return _pickle.loads(data)
+
+    @staticmethod
+    def loadSignData(data):
+        # type: (list) -> QStruct
+        """ 反序列化加载Sign对象表(不会校验) """
+        return _pickle.loads(data[1])
+
+    def onNetUnPack(self):
+        return self
+
+class QRefStruct(QStruct):
+    """ 万能引用 """
+    def __init__(self, refObject):
+        self.ref = refObject
+
+    def onNetUnPack(self):
+        return self.ref
+
+class QListStruct(QStruct, list):
+    """ List容器结构 """
+    def onNetUnPack(self):
+        return list(self)
+
+class QDictStruct(QStruct, dict):
+    """ Dict容器结构 """
+    def onNetUnPack(self):
+        return dict(self)
+
+class QTupleStruct(QStruct, tuple):
+    """ Tuple容器结构 """
+    def onNetUnPack(self):
+        return tuple(self)

debug_mod/DEBUG_ENV_SCRIPT/modMain.py

@@ -0,0 +1,128 @@
+# -*- coding: utf-8 -*-
+from .QuModLibs.QuMod import *
+from .Game import (
+    RELOAD_MOD,
+    INIT_RELOAD_TIME,
+    RELOAD_ADDON,
+    RELOAD_WORLD,
+    RELOAD_SHADERS,
+)
+from .Config import DEBUG_CONFIG
+import threading
+import sys
+
+lambda: "By Zero123"
+
+REF = 0
+
+
+class STD_OUT_WRAPPER(object):
+    def __init__(self, baseIO):
+        self.baseIO = baseIO
+        self.writeLock = threading.Lock()
+        self._buffer = []
+
+    def __getattr__(self, name):
+        return getattr(self.baseIO, name)
+
+    def write(self, data):
+        with self.writeLock:
+            parts = data.splitlines(True)
+            for part in parts:
+                if part.endswith("\n"):
+                    if self._buffer:
+                        line = "".join(self._buffer) + part
+                        self._buffer = []
+                    else:
+                        line = part
+                    self.baseIO.write("[Python] " + line)
+                else:
+                    self._buffer.append(part)
+
+    def close(self):
+        return self.baseIO.close()
+
+    def writelines(self, lines):
+        for line in lines:
+            self.write(line)
+
+    def fileno(self):
+        return self.baseIO.fileno()
+
+
+stdout = sys.stdout
+stderr = sys.stderr
+
+
+def REST_STDOUT():
+    sys.stdout = stdout
+    sys.stderr = stderr
+
+
+sys.stdout = STD_OUT_WRAPPER(sys.stdout)
+sys.stderr = STD_OUT_WRAPPER(sys.stderr)
+
+
+@PRE_SERVER_LOADER_HOOK
+def SERVER_INIT():
+    global REF
+    REF += 1
+
+    def _DESTROY():
+        global REF
+        REF -= 1
+        if REF != 0:
+            return
+        REST_STDOUT()
+
+    from .QuModLibs.Systems.Loader.Server import LoaderSystem
+
+    LoaderSystem.REG_DESTROY_CALL_FUNC(_DESTROY)
+    from . import IPCSystem
+    IPCSystem.ON_SERVER_INIT()
+
+
+def CLOnKeyPressInGame(args={}):
+    if args["isDown"] != "0":
+        return
+    if args["screenName"] != "hud_screen" and not DEBUG_CONFIG.get(
+        "reload_key_global", False
+    ):
+        return
+    key = args["key"]
+    if key == str(DEBUG_CONFIG.get("reload_key", "82")):
+        RELOAD_MOD()
+    elif key == str(DEBUG_CONFIG.get("reload_world_key", "")):
+        RELOAD_WORLD()
+    elif key == str(DEBUG_CONFIG.get("reload_addon_key", "")):
+        RELOAD_ADDON()
+    elif key == str(DEBUG_CONFIG.get("reload_shaders_key", "")):
+        RELOAD_SHADERS()
+
+
+@PRE_CLIENT_LOADER_HOOK
+def CLIENT_INIT():
+    global REF
+    REF += 1
+    from . import IPCSystem
+
+    def _DESTROY():
+        global REF
+        REF -= 1
+        IPCSystem.ON_CLIENT_EXIT()
+        if REF != 0:
+            return
+        REST_STDOUT()
+
+    from .QuModLibs.Systems.Loader.Client import LoaderSystem
+
+    LoaderSystem.REG_DESTROY_CALL_FUNC(_DESTROY)
+
+    LoaderSystem.getSystem().nativeStaticListen("OnKeyPressInGame", CLOnKeyPressInGame)
+    IPCSystem.ON_CLIENT_INIT()
+
+
+try:
+    INIT_RELOAD_TIME()
+except:
+    pass

debug_mod/manifest.json

@@ -0,0 +1 @@
+{"format_version":1,"header":{"description":"","name":"","uuid":"c329b06f-7492-4457-9af3-b19ff29999f9","version":[1,0,0],"min_engine_version":[1,18,0]},"modules":[{"description":"","type":"data","uuid":"96b5e924-153e-460d-8e57-10463173510b","version":[1,0,0]}],"dependencies":[{"uuid":"48199e63-9544-494a-90ab-2864e8f37f39","version":[1,0,0]}]}

src/commands/debug.rs

@@ -0,0 +1,15 @@
+use std::path::PathBuf;
+
+use crate::{commands::DebugArgs, debug};
+
+pub fn execute(args: &DebugArgs) {
+    let project_dir = args
+        .path
+        .as_deref()
+        .map(PathBuf::from)
+        .unwrap_or_else(|| PathBuf::from("."));
+
+    if let Err(err) = debug::run(&project_dir) {
+        eprintln!("Error: {}", err);
+    }
+}

src/commands/mod.rs

@@ -2,6 +2,7 @@ use clap::{Args, Parser, Subcommand, arg};
 
 pub mod components;
 pub mod create;
+pub mod debug;
 pub mod init;
 pub mod release;
 
@@ -29,6 +30,8 @@ pub enum Commands {
     Init(InitArgs),
     /// Create a new component
     Components(ComponentsArgs),
+    /// Launch NetEase Minecraft with debug MOD, IPC logging, and hot reload
+    Debug(DebugArgs),
 }
 
 #[derive(Args)]
@@ -83,3 +86,10 @@ pub struct ComponentsArgs {
     #[arg(short, long)]
     pub identifier: Option<String>,
 }
+
+#[derive(Args)]
+pub struct DebugArgs {
+    /// The path of the project (default: current directory)
+    #[arg(short, long)]
+    pub path: Option<String>,
+}

src/debug/addon.rs

@@ -0,0 +1,247 @@
+use std::{
+    fs,
+    path::{Path, PathBuf},
+};
+
+use serde_json::Value;
+
+use crate::error::{CliError, Result};
+
+use super::{
+    config::{DebugConfig, ResolvedModDir},
+    env, win,
+};
+
+include!(concat!(env!("OUT_DIR"), "/embedded_examples.rs"));
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum PackType {
+    Behavior,
+    Resource,
+}
+
+#[derive(Clone, Debug)]
+pub struct PackInfo {
+    pub name: String,
+    pub uuid: String,
+    pub version: Value,
+    pub pack_type: PackType,
+    pub path: PathBuf,
+}
+
+impl PackInfo {
+    fn runtime_dir_name(&self) -> String {
+        self.uuid.chars().filter(|ch| *ch != '-').collect()
+    }
+}
+
+pub fn register_debug_mod(config: &DebugConfig, mod_dirs: &[ResolvedModDir]) -> Result<PackInfo> {
+    let manifest = EMBEDDED_DEBUG_MOD_FILES
+        .iter()
+        .find(|file| file.path == "manifest.json")
+        .ok_or_else(|| CliError::NotFound("embedded debug MOD manifest.json".to_string()))?;
+    let mut info = parse_manifest_bytes(manifest.contents)?;
+    let out_root = runtime_root(info.pack_type);
+    let target = out_root.join(info.runtime_dir_name());
+    if target.exists() {
+        fs::remove_dir_all(&target)?;
+    }
+
+    let debug_options = python_literal_json(&config.debug_options)?;
+    let target_mod_dirs = hot_reload_dirs_json(mod_dirs)?;
+
+    for file in EMBEDDED_DEBUG_MOD_FILES {
+        let output_path = target.join(file.path.replace('/', "\\"));
+        if let Some(parent) = output_path.parent() {
+            fs::create_dir_all(parent)?;
+        }
+        if file.path.ends_with("Config.py") {
+            let source = std::str::from_utf8(file.contents).map_err(|err| {
+                CliError::InvalidData(format!("debug MOD Config.py is not UTF-8: {err}"))
+            })?;
+            let content = source
+                .replace("\"{#debug_options}\"", &debug_options)
+                .replace("\"{#target_mod_dirs}\"", &target_mod_dirs);
+            fs::write(output_path, content.as_bytes())?;
+        } else {
+            fs::write(output_path, file.contents)?;
+        }
+    }
+
+    info.path = target;
+    Ok(info)
+}
+
+pub fn link_user_mod_dirs(
+    mod_dirs: &[ResolvedModDir],
+    linked_packs: &mut Vec<PackInfo>,
+) -> Result<()> {
+    for mod_dir in mod_dirs {
+        for pack in link_source_addon_to_runtime_packs(&mod_dir.path)? {
+            match pack.pack_type {
+                PackType::Behavior => {
+                    println!("[MCDK] LINK行为包: \"{}\", UUID: {}", pack.name, pack.uuid);
+                    if mod_dir.hot_reload {
+                        println!("  └── 热更新标记追踪");
+                    }
+                }
+                PackType::Resource => {
+                    println!("[MCDK] LINK资源包: \"{}\", UUID: {}", pack.name, pack.uuid);
+                }
+            }
+            linked_packs.push(pack);
+        }
+    }
+    Ok(())
+}
+
+pub fn parse_pack_info(pack_path: &Path) -> Result<Option<PackInfo>> {
+    if !pack_path.is_dir() {
+        return Ok(None);
+    }
+    let manifest_path = manifest_path(pack_path);
+    let Some(manifest_path) = manifest_path else {
+        return Ok(None);
+    };
+    let content = fs::read(&manifest_path)?;
+    let mut info = parse_manifest_bytes(&content)?;
+    info.path = pack_path.to_path_buf();
+    Ok(Some(info))
+}
+
+fn link_source_addon_to_runtime_packs(source_dir: &Path) -> Result<Vec<PackInfo>> {
+    if let Some(pack) = link_source_pack_to_runtime_pack(source_dir)? {
+        return Ok(vec![pack]);
+    }
+
+    let mut packs = Vec::new();
+    if !source_dir.is_dir() {
+        return Ok(packs);
+    }
+    for entry in fs::read_dir(source_dir)? {
+        let entry = entry?;
+        let path = entry.path();
+        if path.is_dir() {
+            if let Some(pack) = link_source_pack_to_runtime_pack(&path)? {
+                packs.push(pack);
+            }
+        }
+    }
+    Ok(packs)
+}
+
+fn link_source_pack_to_runtime_pack(source_dir: &Path) -> Result<Option<PackInfo>> {
+    let Some(mut info) = parse_pack_info(source_dir)? else {
+        return Ok(None);
+    };
+    let destination = runtime_root(info.pack_type).join(info.runtime_dir_name());
+    win::create_junction(source_dir, &destination).map_err(|err| {
+        CliError::Io(std::io::Error::new(
+            err.kind(),
+            format!(
+                "failed to create junction {} -> {}: {err}",
+                destination.display(),
+                source_dir.display()
+            ),
+        ))
+    })?;
+    info.path = destination;
+    Ok(Some(info))
+}
+
+fn runtime_root(pack_type: PackType) -> PathBuf {
+    match pack_type {
+        PackType::Behavior => env::behavior_packs_path(),
+        PackType::Resource => env::resource_packs_path(),
+    }
+}
+
+fn parse_manifest_bytes(bytes: &[u8]) -> Result<PackInfo> {
+    let manifest: Value = serde_json::from_slice(bytes)?;
+    let header = manifest
+        .get("header")
+        .and_then(Value::as_object)
+        .ok_or_else(|| CliError::InvalidData("manifest header is missing".to_string()))?;
+    let name = header
+        .get("name")
+        .and_then(Value::as_str)
+        .unwrap_or_default()
+        .to_string();
+    let uuid = header
+        .get("uuid")
+        .and_then(Value::as_str)
+        .ok_or_else(|| CliError::InvalidData("manifest header uuid is missing".to_string()))?
+        .to_string();
+    let version = header
+        .get("version")
+        .cloned()
+        .unwrap_or_else(|| Value::Array(Vec::new()));
+    let modules = manifest
+        .get("modules")
+        .and_then(Value::as_array)
+        .ok_or_else(|| CliError::InvalidData("manifest modules is missing".to_string()))?;
+    let pack_type = modules
+        .iter()
+        .filter_map(|module| module.get("type").and_then(Value::as_str))
+        .find_map(|ty| match ty {
+            "data" => Some(PackType::Behavior),
+            "resources" => Some(PackType::Resource),
+            _ => None,
+        })
+        .ok_or_else(|| {
+            CliError::InvalidData("manifest module type is neither data nor resources".to_string())
+        })?;
+
+    Ok(PackInfo {
+        name,
+        uuid,
+        version,
+        pack_type,
+        path: PathBuf::new(),
+    })
+}
+
+fn manifest_path(pack_path: &Path) -> Option<PathBuf> {
+    let manifest = pack_path.join("manifest.json");
+    if manifest.is_file() {
+        return Some(manifest);
+    }
+    let netease_manifest = pack_path.join("pack_manifest.json");
+    if netease_manifest.is_file() {
+        Some(netease_manifest)
+    } else {
+        None
+    }
+}
+
+fn hot_reload_dirs_json(mod_dirs: &[ResolvedModDir]) -> Result<String> {
+    let dirs: Vec<String> = mod_dirs
+        .iter()
+        .filter(|dir| dir.hot_reload)
+        .map(|dir| dir.path.to_string_lossy().replace('\\', "/"))
+        .collect();
+    Ok(serde_json::to_string(&dirs)?)
+}
+
+fn python_literal_json(value: &Value) -> Result<String> {
+    let mut text = serde_json::to_string(value)?;
+    text = text.replace("true", "True");
+    text = text.replace("false", "False");
+    text = text.replace("null", "None");
+    Ok(text)
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::python_literal_json;
+
+    #[test]
+    fn converts_json_literals_to_python_literals() {
+        assert_eq!(
+            python_literal_json(&json!({"a": true, "b": null})).unwrap(),
+            "{\"a\":True,\"b\":None}"
+        );
+    }
+}

src/debug/config.rs

@@ -0,0 +1,356 @@
+use std::{
+    env, fs,
+    path::{Path, PathBuf},
+};
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+
+use crate::error::{CliError, Result};
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct DebugConfig {
+    #[serde(default = "default_included_mod_dirs")]
+    pub included_mod_dirs: Vec<IncludedModDir>,
+    #[serde(default)]
+    pub world_seed: Option<i64>,
+    #[serde(default)]
+    pub reset_world: bool,
+    #[serde(default = "default_world_name")]
+    pub world_name: String,
+    #[serde(default = "default_world_name")]
+    pub world_folder_name: String,
+    #[serde(default = "default_true")]
+    pub auto_join_game: bool,
+    #[serde(default = "default_true")]
+    pub include_debug_mod: bool,
+    #[serde(default = "default_true")]
+    pub auto_hot_reload_mods: bool,
+    #[serde(default = "default_world_type")]
+    pub world_type: i32,
+    #[serde(default = "default_game_mode")]
+    pub game_mode: i32,
+    #[serde(default = "default_true")]
+    pub enable_cheats: bool,
+    #[serde(default = "default_true")]
+    pub keep_inventory: bool,
+    #[serde(default = "default_true")]
+    pub do_weather_cycle: bool,
+    #[serde(default = "default_true")]
+    pub do_daylight_cycle: bool,
+    #[serde(default)]
+    pub game_executable_path: String,
+    #[serde(default)]
+    pub debug_options: Value,
+    #[serde(default)]
+    pub netease_config: NeteaseConfig,
+    #[serde(default = "default_user_name")]
+    pub user_name: String,
+    #[serde(default)]
+    pub skin_info: Option<Value>,
+    #[serde(default)]
+    pub experiment_options: Option<ExperimentOptions>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(untagged)]
+pub enum IncludedModDir {
+    Path(String),
+    Object {
+        path: String,
+        #[serde(default = "default_true", rename = "hot_reload")]
+        hot_reload: bool,
+        #[serde(default = "default_true")]
+        enabled: bool,
+    },
+}
+
+#[derive(Clone, Debug)]
+pub struct ResolvedModDir {
+    pub path: PathBuf,
+    pub hot_reload: bool,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct NeteaseConfig {
+    #[serde(default)]
+    pub chat_extension: bool,
+}
+
+impl Default for NeteaseConfig {
+    fn default() -> Self {
+        Self {
+            chat_extension: false,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct ExperimentOptions {
+    #[serde(default)]
+    pub data_driven_biomes: bool,
+    #[serde(default)]
+    pub data_driven_items: bool,
+    #[serde(default)]
+    pub experimental_molang_features: bool,
+}
+
+impl DebugConfig {
+    pub fn included_mod_dirs(&self, project_dir: &Path) -> Result<Vec<ResolvedModDir>> {
+        let mut dirs = Vec::new();
+        for item in &self.included_mod_dirs {
+            match item {
+                IncludedModDir::Path(path) => {
+                    dirs.push(resolve_mod_dir(project_dir, path, true, true)?)
+                }
+                IncludedModDir::Object {
+                    path,
+                    hot_reload,
+                    enabled,
+                } => {
+                    if *enabled {
+                        dirs.push(resolve_mod_dir(project_dir, path, *hot_reload, true)?);
+                    }
+                }
+            }
+        }
+        Ok(dirs)
+    }
+
+    pub fn auto_join_game_effective(&self) -> bool {
+        match env::var("MCDEV_AUTO_JOIN_GAME") {
+            Ok(value) if value == "0" => false,
+            Ok(value) if value == "1" => true,
+            _ => self.auto_join_game,
+        }
+    }
+}
+
+pub fn env_is_subprocess_mode() -> bool {
+    matches!(env::var("MCDEV_IS_SUBPROCESS_MODE"), Ok(value) if value == "1" || value.eq_ignore_ascii_case("true"))
+}
+
+pub fn load_or_create(project_dir: &Path) -> Result<DebugConfig> {
+    let config_path = project_dir.join(".mcdev.json");
+    if config_path.is_file() {
+        let content = fs::read_to_string(&config_path)?;
+        let stripped = strip_json_comments(&content);
+        let config = serde_json::from_str(&stripped)?;
+        return Ok(config);
+    }
+
+    let config = create_default_config();
+    write_config(project_dir, &config)?;
+    if config.game_executable_path.is_empty() {
+        return Err(CliError::NotFound(
+            "未找到 Minecraft.Windows.exe；已创建 .mcdev.json，请填写 game_executable_path"
+                .to_string(),
+        ));
+    }
+    Ok(config)
+}
+
+pub fn ensure_game_executable(project_dir: &Path, config: &mut DebugConfig) -> Result<()> {
+    let configured = PathBuf::from(&config.game_executable_path);
+    if !config.game_executable_path.is_empty() && configured.is_file() {
+        return Ok(());
+    }
+
+    if let Some(path) = crate::debug::env::auto_match_latest_game_exe_path() {
+        config.game_executable_path = path.to_string_lossy().replace('\\', "/");
+        write_config(project_dir, config)?;
+        println!(
+            "游戏路径无效，已重新搜索并更新：{}",
+            config.game_executable_path
+        );
+        return Ok(());
+    }
+
+    Err(CliError::NotFound(
+        "未找到有效的 Minecraft.Windows.exe，请在 .mcdev.json 中设置 game_executable_path"
+            .to_string(),
+    ))
+}
+
+pub fn write_config(project_dir: &Path, config: &DebugConfig) -> Result<()> {
+    let path = project_dir.join(".mcdev.json");
+    let text = serde_json::to_string_pretty(config)?;
+    fs::write(path, text)?;
+    Ok(())
+}
+
+fn create_default_config() -> DebugConfig {
+    DebugConfig {
+        included_mod_dirs: default_included_mod_dirs(),
+        world_seed: None,
+        reset_world: false,
+        world_name: default_world_name(),
+        world_folder_name: default_world_name(),
+        auto_join_game: true,
+        include_debug_mod: true,
+        auto_hot_reload_mods: true,
+        world_type: default_world_type(),
+        game_mode: default_game_mode(),
+        enable_cheats: true,
+        keep_inventory: true,
+        do_weather_cycle: true,
+        do_daylight_cycle: true,
+        game_executable_path: crate::debug::env::auto_match_latest_game_exe_path()
+            .map(|path| path.to_string_lossy().replace('\\', "/"))
+            .unwrap_or_default(),
+        debug_options: Value::Object(Map::new()),
+        netease_config: NeteaseConfig::default(),
+        user_name: default_user_name(),
+        skin_info: None,
+        experiment_options: None,
+    }
+}
+
+fn resolve_mod_dir(
+    project_dir: &Path,
+    path: &str,
+    hot_reload: bool,
+    enabled: bool,
+) -> Result<ResolvedModDir> {
+    if !enabled {
+        return Err(CliError::InvalidInput(
+            "disabled mod dir should not be resolved".to_string(),
+        ));
+    }
+    let raw = PathBuf::from(path);
+    let path = if raw.is_absolute() {
+        raw
+    } else {
+        let base = if project_dir.is_absolute() {
+            project_dir.to_path_buf()
+        } else {
+            env::current_dir()?.join(project_dir)
+        };
+        base.join(raw)
+    };
+    Ok(ResolvedModDir {
+        path: normalize_path(path),
+        hot_reload,
+    })
+}
+
+fn normalize_path(path: PathBuf) -> PathBuf {
+    let mut out = PathBuf::new();
+    for component in path.components() {
+        match component {
+            std::path::Component::CurDir => {}
+            std::path::Component::ParentDir => {
+                out.pop();
+            }
+            other => out.push(other.as_os_str()),
+        }
+    }
+    if out.as_os_str().is_empty() {
+        PathBuf::from(".")
+    } else {
+        out
+    }
+}
+
+fn default_included_mod_dirs() -> Vec<IncludedModDir> {
+    vec![IncludedModDir::Path("./".to_string())]
+}
+
+fn default_world_name() -> String {
+    "MC_DEV_WORLD".to_string()
+}
+fn default_user_name() -> String {
+    "developer".to_string()
+}
+fn default_true() -> bool {
+    true
+}
+fn default_world_type() -> i32 {
+    1
+}
+fn default_game_mode() -> i32 {
+    1
+}
+
+pub fn strip_json_comments(input: &str) -> String {
+    let mut out = String::with_capacity(input.len());
+    let mut chars = input.chars().peekable();
+    let mut in_string = false;
+    let mut escaped = false;
+
+    while let Some(ch) = chars.next() {
+        if in_string {
+            out.push(ch);
+            if escaped {
+                escaped = false;
+            } else if ch == '\\' {
+                escaped = true;
+            } else if ch == '"' {
+                in_string = false;
+            }
+            continue;
+        }
+
+        if ch == '"' {
+            in_string = true;
+            out.push(ch);
+            continue;
+        }
+
+        if ch == '/' {
+            match chars.peek().copied() {
+                Some('/') => {
+                    chars.next();
+                    for next in chars.by_ref() {
+                        if next == '\n' {
+                            out.push('\n');
+                            break;
+                        }
+                    }
+                }
+                Some('*') => {
+                    chars.next();
+                    let mut prev = '\0';
+                    for next in chars.by_ref() {
+                        if next == '\n' {
+                            out.push('\n');
+                        }
+                        if prev == '*' && next == '/' {
+                            break;
+                        }
+                        prev = next;
+                    }
+                }
+                _ => out.push(ch),
+            }
+        } else {
+            out.push(ch);
+        }
+    }
+
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{resolve_mod_dir, strip_json_comments};
+
+    #[test]
+    fn strips_jsonc_comments_without_touching_strings() {
+        let input = r#"{"url":"http://x",/*a*/"n":1//b
+}"#;
+        assert_eq!(
+            strip_json_comments(input),
+            "{\"url\":\"http://x\",\"n\":1\n}"
+        );
+    }
+
+    #[test]
+    fn default_current_project_resolves_to_absolute_cwd() {
+        let resolved = resolve_mod_dir(std::path::Path::new("."), "./", true, true).unwrap();
+        let cwd = super::normalize_path(std::env::current_dir().unwrap());
+
+        assert_eq!(resolved.path, cwd);
+        assert!(resolved.hot_reload);
+    }
+}

src/debug/env.rs

@@ -0,0 +1,99 @@
+use std::{env, fs, path::PathBuf};
+
+use crate::error::Result;
+
+pub fn app_data_path() -> PathBuf {
+    env::var_os("APPDATA")
+        .map(PathBuf::from)
+        .unwrap_or_default()
+}
+
+pub fn minecraft_data_path() -> PathBuf {
+    app_data_path().join("MinecraftPE_Netease")
+}
+
+pub fn games_com_netease_path() -> PathBuf {
+    minecraft_data_path().join("games/com.netease")
+}
+
+pub fn worlds_path() -> PathBuf {
+    minecraft_data_path().join("minecraftWorlds")
+}
+
+pub fn behavior_packs_path() -> PathBuf {
+    games_com_netease_path().join("behavior_packs")
+}
+
+pub fn resource_packs_path() -> PathBuf {
+    games_com_netease_path().join("resource_packs")
+}
+
+pub fn clean_runtime_packs() -> Result<()> {
+    for path in [behavior_packs_path(), resource_packs_path()] {
+        if path.is_dir() {
+            fs::remove_dir_all(&path)?;
+        }
+    }
+    Ok(())
+}
+
+pub fn auto_match_latest_game_exe_path() -> Option<PathBuf> {
+    let mut best: Option<(Vec<u32>, PathBuf)> = None;
+
+    for drive in b'A'..=b'Z' {
+        let root = format!(
+            "{}:/MCStudioDownload/game/MinecraftPE_Netease",
+            drive as char
+        );
+        let root = PathBuf::from(root);
+        if !root.is_dir() {
+            continue;
+        }
+
+        let entries = fs::read_dir(&root).ok()?;
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if !path.is_dir() {
+                continue;
+            }
+            let exe = path.join("Minecraft.Windows.exe");
+            if !exe.is_file() {
+                continue;
+            }
+            let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
+                continue;
+            };
+            let Some(version) = parse_version(name) else {
+                continue;
+            };
+            match &best {
+                Some((best_version, _)) if best_version >= &version => {}
+                _ => best = Some((version, exe)),
+            }
+        }
+    }
+
+    best.map(|(_, path)| path)
+}
+
+fn parse_version(value: &str) -> Option<Vec<u32>> {
+    let mut out = Vec::new();
+    for part in value.split('.') {
+        if part.is_empty() || !part.bytes().all(|b| b.is_ascii_digit()) {
+            return None;
+        }
+        out.push(part.parse().ok()?);
+    }
+    if out.is_empty() { None } else { Some(out) }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::parse_version;
+
+    #[test]
+    fn parses_numeric_versions_only() {
+        assert_eq!(parse_version("1.21.3"), Some(vec![1, 21, 3]));
+        assert_eq!(parse_version("1.x"), None);
+    }
+}

src/debug/hotreload.rs

@@ -0,0 +1,513 @@
+use std::{
+    collections::{HashMap, HashSet},
+    path::{Path, PathBuf},
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicBool, Ordering},
+    },
+    thread::{self, JoinHandle},
+    time::Duration,
+};
+
+#[cfg(not(windows))]
+use std::{fs, time::SystemTime};
+
+use serde_json::json;
+#[cfg(not(windows))]
+use walkdir::WalkDir;
+
+use super::{
+    config::ResolvedModDir,
+    ipc::DebugIpcServer,
+    log::{self, ConsoleColor},
+};
+
+const DEBOUNCE_MS: u64 = 100;
+
+pub struct HotReloadTask {
+    stop: Arc<AtomicBool>,
+
+    file_thread: Option<JoinHandle<()>>,
+    foreground_thread: Option<JoinHandle<()>>,
+}
+
+impl HotReloadTask {
+    pub fn start(
+        process_id: u32,
+        mod_dirs: &[ResolvedModDir],
+        ipc: DebugIpcServer,
+    ) -> Option<Self> {
+        let roots: Vec<PathBuf> = mod_dirs
+            .iter()
+            .filter(|dir| dir.hot_reload)
+            .map(|dir| dir.path.clone())
+            .collect();
+        if roots.is_empty() {
+            return None;
+        }
+
+        println!("[HotReload] 追踪目录列表：");
+        for root in &roots {
+            println!("  └── {}", root.display());
+        }
+
+        let stop = Arc::new(AtomicBool::new(false));
+        let need_update = Arc::new(AtomicBool::new(false));
+        let is_foreground = Arc::new(AtomicBool::new(false));
+        let cached_paths = Arc::new(Mutex::new(HashSet::new()));
+
+        let file_thread = {
+            let stop = Arc::clone(&stop);
+            let need_update = Arc::clone(&need_update);
+            let is_foreground = Arc::clone(&is_foreground);
+            let cached_paths = Arc::clone(&cached_paths);
+            let ipc = ipc.clone();
+            let roots = roots.clone();
+            thread::spawn(move || {
+                watch_py_files(roots, stop, need_update, is_foreground, cached_paths, ipc)
+            })
+        };
+
+        let foreground_thread = {
+            let stop = Arc::clone(&stop);
+            let need_update = Arc::clone(&need_update);
+            let is_foreground = Arc::clone(&is_foreground);
+            let cached_paths = Arc::clone(&cached_paths);
+            let ipc = ipc.clone();
+            let roots = roots.clone();
+            thread::spawn(move || {
+                watch_foreground(
+                    process_id,
+                    roots,
+                    stop,
+                    need_update,
+                    is_foreground,
+                    cached_paths,
+                    ipc,
+                )
+            })
+        };
+
+        Some(Self {
+            stop,
+
+            file_thread: Some(file_thread),
+            foreground_thread: Some(foreground_thread),
+        })
+    }
+
+    pub fn safe_exit(&mut self) {
+        self.stop.store(true, Ordering::Relaxed);
+        if let Some(handle) = self.file_thread.take() {
+            let _ = handle.join();
+        }
+        if let Some(handle) = self.foreground_thread.take() {
+            let _ = handle.join();
+        }
+    }
+}
+
+impl Drop for HotReloadTask {
+    fn drop(&mut self) {
+        self.safe_exit();
+    }
+}
+
+fn watch_py_files(
+    roots: Vec<PathBuf>,
+    stop: Arc<AtomicBool>,
+    need_update: Arc<AtomicBool>,
+    is_foreground: Arc<AtomicBool>,
+    cached_paths: Arc<Mutex<HashSet<PathBuf>>>,
+    ipc: DebugIpcServer,
+) {
+    watch_py_files_native(roots, stop, need_update, is_foreground, cached_paths, ipc);
+}
+
+#[cfg(windows)]
+fn watch_py_files_native(
+    roots: Vec<PathBuf>,
+    stop: Arc<AtomicBool>,
+    need_update: Arc<AtomicBool>,
+    is_foreground: Arc<AtomicBool>,
+    cached_paths: Arc<Mutex<HashSet<PathBuf>>>,
+    ipc: DebugIpcServer,
+) {
+    use std::{mem, os::windows::ffi::OsStrExt, ptr, time::Instant};
+    use windows_sys::Win32::{
+        Foundation::{HANDLE, INVALID_HANDLE_VALUE, WAIT_FAILED, WAIT_OBJECT_0, WAIT_TIMEOUT},
+        Storage::FileSystem::{
+            CreateFileW, FILE_ACTION_MODIFIED, FILE_FLAG_BACKUP_SEMANTICS, FILE_FLAG_OVERLAPPED,
+            FILE_LIST_DIRECTORY, FILE_NOTIFY_CHANGE_LAST_WRITE, FILE_NOTIFY_INFORMATION,
+            FILE_SHARE_DELETE, FILE_SHARE_READ, FILE_SHARE_WRITE, OPEN_EXISTING,
+            ReadDirectoryChangesW,
+        },
+        System::{
+            IO::{GetOverlappedResult, OVERLAPPED},
+            Threading::{CreateEventW, WaitForMultipleObjects},
+        },
+    };
+
+    struct WatchItem {
+        dir: PathBuf,
+        h_dir: HANDLE,
+        event: HANDLE,
+        overlapped: OVERLAPPED,
+        buffer: Vec<u8>,
+    }
+
+    impl Drop for WatchItem {
+        fn drop(&mut self) {
+            unsafe {
+                if self.h_dir != INVALID_HANDLE_VALUE && !self.h_dir.is_null() {
+                    windows_sys::Win32::Foundation::CloseHandle(self.h_dir);
+                }
+                if !self.event.is_null() {
+                    windows_sys::Win32::Foundation::CloseHandle(self.event);
+                }
+            }
+        }
+    }
+
+    fn start_watch(item: &mut WatchItem) -> bool {
+        item.overlapped = unsafe { mem::zeroed() };
+        item.overlapped.hEvent = item.event;
+        let mut bytes_returned = 0u32;
+        unsafe {
+            ReadDirectoryChangesW(
+                item.h_dir,
+                item.buffer.as_mut_ptr().cast(),
+                item.buffer.len() as u32,
+                1,
+                FILE_NOTIFY_CHANGE_LAST_WRITE,
+                &mut bytes_returned,
+                &mut item.overlapped,
+                None,
+            ) != 0
+        }
+    }
+
+    let mut items = Vec::new();
+    for root in &roots {
+        if !root.is_dir() {
+            continue;
+        }
+        let mut wide: Vec<u16> = root.as_os_str().encode_wide().collect();
+        wide.push(0);
+        let event = unsafe { CreateEventW(ptr::null(), 0, 0, ptr::null()) };
+        if event.is_null() {
+            continue;
+        }
+        let h_dir = unsafe {
+            CreateFileW(
+                wide.as_ptr(),
+                FILE_LIST_DIRECTORY,
+                FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
+                ptr::null(),
+                OPEN_EXISTING,
+                FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OVERLAPPED,
+                ptr::null_mut(),
+            )
+        };
+        if h_dir == INVALID_HANDLE_VALUE {
+            unsafe {
+                windows_sys::Win32::Foundation::CloseHandle(event);
+            }
+            continue;
+        }
+        items.push(WatchItem {
+            dir: root.clone(),
+            h_dir,
+            event,
+            overlapped: unsafe { mem::zeroed() },
+            buffer: vec![0u8; 64 * 1024],
+        });
+    }
+
+    if items.is_empty() {
+        return;
+    }
+    if items.len() > 64 {
+        log::print_colored(
+            "[HotReload] 追踪目录超过 Windows WaitForMultipleObjects 限制，已忽略超出部分。",
+            ConsoleColor::Yellow,
+        );
+        items.truncate(64);
+    }
+
+    for item in &mut items {
+        start_watch(item);
+    }
+
+    let mut debounce = HashMap::<PathBuf, Instant>::new();
+    while !stop.load(Ordering::Relaxed) {
+        let handles: Vec<HANDLE> = items.iter().map(|item| item.event).collect();
+        let result =
+            unsafe { WaitForMultipleObjects(handles.len() as u32, handles.as_ptr(), 0, 100) };
+        if result == WAIT_TIMEOUT {
+            continue;
+        }
+        if result == WAIT_FAILED {
+            break;
+        }
+        let index = (result - WAIT_OBJECT_0) as usize;
+        if index >= items.len() {
+            continue;
+        }
+        let item = &mut items[index];
+        let mut bytes = 0u32;
+        let ok = unsafe { GetOverlappedResult(item.h_dir, &mut item.overlapped, &mut bytes, 0) };
+        if ok == 0 || bytes == 0 {
+            start_watch(item);
+            continue;
+        }
+
+        let mut offset = 0usize;
+        while offset < bytes as usize {
+            let info =
+                unsafe { &*(item.buffer.as_ptr().add(offset) as *const FILE_NOTIFY_INFORMATION) };
+            let name_len = (info.FileNameLength / 2) as usize;
+            let name = unsafe { std::slice::from_raw_parts(info.FileName.as_ptr(), name_len) };
+            let path = item.dir.join(String::from_utf16_lossy(name));
+            if info.Action == FILE_ACTION_MODIFIED
+                && path.extension().and_then(|ext| ext.to_str()) == Some("py")
+            {
+                let now = Instant::now();
+                let should_trigger = debounce
+                    .get(&path)
+                    .map(|last| now.duration_since(*last) >= Duration::from_millis(DEBOUNCE_MS))
+                    .unwrap_or(true);
+                if should_trigger {
+                    debounce.insert(path.clone(), now);
+                    record_changed_path(
+                        &roots,
+                        &path,
+                        &cached_paths,
+                        &need_update,
+                        &is_foreground,
+                        &ipc,
+                    );
+                }
+            }
+            if info.NextEntryOffset == 0 {
+                break;
+            }
+            offset += info.NextEntryOffset as usize;
+        }
+        start_watch(item);
+    }
+}
+
+#[cfg(not(windows))]
+fn watch_py_files_native(
+    roots: Vec<PathBuf>,
+    stop: Arc<AtomicBool>,
+    need_update: Arc<AtomicBool>,
+    is_foreground: Arc<AtomicBool>,
+    cached_paths: Arc<Mutex<HashSet<PathBuf>>>,
+    ipc: DebugIpcServer,
+) {
+    let mut last_seen = snapshot_py_files(&roots);
+    let mut debounce = HashMap::<PathBuf, SystemTime>::new();
+
+    while !stop.load(Ordering::Relaxed) {
+        thread::sleep(Duration::from_millis(DEBOUNCE_MS));
+        let now = SystemTime::now();
+        let current = snapshot_py_files(&roots);
+        for (path, modified) in &current {
+            let changed = match last_seen.get(path) {
+                Some(previous) => modified > previous,
+                None => false,
+            };
+            if !changed {
+                continue;
+            }
+            if let Some(last) = debounce.get(path) {
+                if now.duration_since(*last).unwrap_or_default()
+                    < Duration::from_millis(DEBOUNCE_MS)
+                {
+                    continue;
+                }
+            }
+            debounce.insert(path.clone(), now);
+            record_changed_path(
+                &roots,
+                path,
+                &cached_paths,
+                &need_update,
+                &is_foreground,
+                &ipc,
+            );
+        }
+        last_seen = current;
+    }
+}
+
+fn record_changed_path(
+    roots: &[PathBuf],
+    path: &Path,
+    cached_paths: &Arc<Mutex<HashSet<PathBuf>>>,
+    need_update: &Arc<AtomicBool>,
+    is_foreground: &Arc<AtomicBool>,
+    ipc: &DebugIpcServer,
+) {
+    log::print_colored(
+        &format!("[HotReload] Detected change in: {}", path.display()),
+        ConsoleColor::Yellow,
+    );
+    cached_paths.lock().unwrap().insert(path.to_path_buf());
+    need_update.store(true, Ordering::Relaxed);
+    if is_foreground.load(Ordering::Relaxed) {
+        trigger_reload(roots, cached_paths, need_update, ipc);
+    }
+}
+
+fn watch_foreground(
+    process_id: u32,
+    roots: Vec<PathBuf>,
+    stop: Arc<AtomicBool>,
+    need_update: Arc<AtomicBool>,
+    is_foreground: Arc<AtomicBool>,
+    cached_paths: Arc<Mutex<HashSet<PathBuf>>>,
+    ipc: DebugIpcServer,
+) {
+    let mut last_state = false;
+    while !stop.load(Ordering::Relaxed) {
+        let current = foreground_process_id() == Some(process_id);
+        is_foreground.store(current, Ordering::Relaxed);
+        if current && !last_state && need_update.load(Ordering::Relaxed) {
+            trigger_reload(&roots, &cached_paths, &need_update, &ipc);
+        }
+        last_state = current;
+        thread::sleep(Duration::from_millis(80));
+    }
+}
+
+fn trigger_reload(
+    roots: &[PathBuf],
+    cached_paths: &Arc<Mutex<HashSet<PathBuf>>>,
+    need_update: &Arc<AtomicBool>,
+    ipc: &DebugIpcServer,
+) {
+    let paths: Vec<PathBuf> = {
+        let mut guard = cached_paths.lock().unwrap();
+        guard.drain().collect()
+    };
+    let modules: Vec<String> = paths
+        .iter()
+        .filter_map(|path| py_path_to_module_name(path, roots))
+        .collect();
+    need_update.store(false, Ordering::Relaxed);
+    if modules.is_empty() {
+        return;
+    }
+    log::print_colored(
+        "[HotReload] 检测到修改，已触发热更新。",
+        ConsoleColor::Yellow,
+    );
+    let payload = json!(modules).to_string();
+    let _ = ipc.send_message(2, payload.as_bytes());
+}
+
+#[cfg(not(windows))]
+fn snapshot_py_files(roots: &[PathBuf]) -> HashMap<PathBuf, SystemTime> {
+    let mut files = HashMap::new();
+    for root in roots {
+        if !root.is_dir() {
+            continue;
+        }
+        for entry in WalkDir::new(root).into_iter().filter_map(Result::ok) {
+            let path = entry.path();
+            if !path.is_file() || path.extension().and_then(|ext| ext.to_str()) != Some("py") {
+                continue;
+            }
+            if let Ok(metadata) = fs::metadata(path) {
+                if let Ok(modified) = metadata.modified() {
+                    files.insert(path.to_path_buf(), modified);
+                }
+            }
+        }
+    }
+    files
+}
+
+pub fn py_path_to_module_name(file_path: &Path, mod_roots: &[PathBuf]) -> Option<String> {
+    if file_path.extension().and_then(|ext| ext.to_str()) != Some("py") {
+        return None;
+    }
+    let mut cur = file_path.parent()?;
+    loop {
+        if cur.join("manifest.json").is_file() || cur.join("pack_manifest.json").is_file() {
+            let rel = file_path.strip_prefix(cur).ok()?;
+            let mut parts: Vec<String> = rel
+                .iter()
+                .map(|part| part.to_string_lossy().into_owned())
+                .collect();
+            let last = parts.last_mut()?;
+            if !last.ends_with(".py") {
+                return None;
+            }
+            last.truncate(last.len() - 3);
+            return Some(parts.join("."));
+        }
+        if mod_roots.iter().any(|root| same_path(root, cur)) {
+            return None;
+        }
+        cur = cur.parent()?;
+    }
+}
+
+fn same_path(left: &Path, right: &Path) -> bool {
+    left == right || (left.canonicalize().ok().as_deref() == right.canonicalize().ok().as_deref())
+}
+
+#[cfg(windows)]
+fn foreground_process_id() -> Option<u32> {
+    use windows_sys::Win32::UI::WindowsAndMessaging::{
+        GetForegroundWindow, GetWindowThreadProcessId,
+    };
+    unsafe {
+        let hwnd = GetForegroundWindow();
+        if hwnd.is_null() {
+            return None;
+        }
+        let mut pid = 0u32;
+        GetWindowThreadProcessId(hwnd, &mut pid);
+        if pid == 0 { None } else { Some(pid) }
+    }
+}
+
+#[cfg(not(windows))]
+fn foreground_process_id() -> Option<u32> {
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use std::fs;
+
+    use super::py_path_to_module_name;
+
+    #[test]
+    fn maps_py_file_to_module_name_under_manifest() {
+        let root = std::env::temp_dir().join(format!("emod-hot-{}", std::process::id()));
+        let pack = root.join("behavior_pack");
+        let module = pack.join("foo/bar.py");
+        fs::create_dir_all(module.parent().unwrap()).unwrap();
+        fs::write(pack.join("manifest.json"), "{}").unwrap();
+        fs::write(&module, "").unwrap();
+
+        assert_eq!(
+            py_path_to_module_name(&module, std::slice::from_ref(&root)),
+            Some("foo.bar".to_string())
+        );
+        let outside = root.join("x.py");
+        fs::write(&outside, "").unwrap();
+        assert_eq!(
+            py_path_to_module_name(&outside, std::slice::from_ref(&root)),
+            None
+        );
+
+        let _ = fs::remove_dir_all(root);
+    }
+}

src/debug/ipc.rs

@@ -0,0 +1,123 @@
+use std::{
+    io::{self, Write},
+    net::{TcpListener, TcpStream},
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicBool, Ordering},
+    },
+    thread::{self, JoinHandle},
+    time::Duration,
+};
+
+use crate::error::{CliError, Result};
+
+#[derive(Clone)]
+pub struct DebugIpcServer {
+    inner: Arc<Inner>,
+}
+
+struct Inner {
+    port: Mutex<u16>,
+    clients: Mutex<Vec<TcpStream>>,
+    stop: AtomicBool,
+    thread: Mutex<Option<JoinHandle<()>>>,
+}
+
+impl DebugIpcServer {
+    pub fn start() -> Result<Self> {
+        let listener = TcpListener::bind(("127.0.0.1", 0))?;
+        listener.set_nonblocking(true)?;
+        let port = listener.local_addr()?.port();
+        let inner = Arc::new(Inner {
+            port: Mutex::new(port),
+            clients: Mutex::new(Vec::new()),
+            stop: AtomicBool::new(false),
+            thread: Mutex::new(None),
+        });
+
+        let thread_inner = Arc::clone(&inner);
+        let handle = thread::spawn(move || accept_loop(listener, thread_inner));
+        *inner.thread.lock().unwrap() = Some(handle);
+
+        Ok(Self { inner })
+    }
+
+    pub fn port(&self) -> u16 {
+        *self.inner.port.lock().unwrap()
+    }
+
+    pub fn send_message(&self, message_type: u16, payload: &[u8]) -> Result<bool> {
+        let frame = encode_frame(message_type, payload)?;
+        let mut clients = self.inner.clients.lock().unwrap();
+        let mut any = false;
+        clients.retain_mut(|stream| match stream.write(&frame) {
+            Ok(_) => {
+                any = true;
+                true
+            }
+            Err(err) if err.kind() == io::ErrorKind::WouldBlock => true,
+            Err(_) => false,
+        });
+        Ok(any)
+    }
+
+    pub fn stop(&self) {
+        self.inner.stop.store(true, Ordering::Relaxed);
+        *self.inner.port.lock().unwrap() = 0;
+        self.inner.clients.lock().unwrap().clear();
+    }
+
+    pub fn join(&self) {
+        if let Some(handle) = self.inner.thread.lock().unwrap().take() {
+            let _ = handle.join();
+        }
+    }
+
+    pub fn safe_exit(&self) {
+        self.stop();
+        self.join();
+    }
+}
+
+impl Drop for DebugIpcServer {
+    fn drop(&mut self) {
+        self.stop();
+    }
+}
+
+pub fn encode_frame(message_type: u16, payload: &[u8]) -> Result<Vec<u8>> {
+    let len = u32::try_from(payload.len())
+        .map_err(|_| CliError::InvalidInput("IPC payload is larger than u32::MAX".to_string()))?;
+    let mut frame = Vec::with_capacity(6 + payload.len());
+    frame.extend_from_slice(&message_type.to_be_bytes());
+    frame.extend_from_slice(&len.to_be_bytes());
+    frame.extend_from_slice(payload);
+    Ok(frame)
+}
+
+fn accept_loop(listener: TcpListener, inner: Arc<Inner>) {
+    while !inner.stop.load(Ordering::Relaxed) {
+        match listener.accept() {
+            Ok((stream, _)) => {
+                let _ = stream.set_nonblocking(true);
+                inner.clients.lock().unwrap().push(stream);
+            }
+            Err(err) if err.kind() == io::ErrorKind::WouldBlock => {
+                thread::sleep(Duration::from_millis(50));
+            }
+            Err(_) => break,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::encode_frame;
+
+    #[test]
+    fn encodes_big_endian_ipc_frame() {
+        let frame = encode_frame(2, b"[\"a.b\"]").unwrap();
+        assert_eq!(&frame[..6], &[0, 2, 0, 0, 0, 7]);
+        assert_eq!(&frame[6..], b"[\"a.b\"]");
+    }
+}

src/debug/level.rs

@@ -0,0 +1,125 @@
+use std::{fs, path::PathBuf};
+
+use serde_json::{Value, json};
+
+use crate::error::Result;
+
+use super::{
+    addon::{PackInfo, PackType},
+    config::DebugConfig,
+    env, nbt,
+};
+
+pub fn world_dir(config: &DebugConfig) -> PathBuf {
+    env::worlds_path().join(&config.world_folder_name)
+}
+
+pub fn prepare_world(config: &DebugConfig, linked_packs: &[PackInfo]) -> Result<()> {
+    let world_dir = world_dir(config);
+    let level_path = world_dir.join("level.dat");
+
+    if !world_dir.is_dir() || config.reset_world {
+        if world_dir.exists() {
+            fs::remove_dir_all(&world_dir)?;
+        }
+        fs::create_dir_all(&world_dir)?;
+        let data = nbt::create_level_dat(config)?;
+        fs::write(&level_path, data)?;
+    } else if level_path.is_file() {
+        let data = fs::read(&level_path)?;
+        let updated = if plugin_env_enabled() {
+            nbt::update_level_dat_world_data(&data, config, false)?
+        } else {
+            nbt::update_level_dat_last_played(&data)?
+        };
+        fs::write(&level_path, updated)?;
+    } else {
+        let data = nbt::create_level_dat(config)?;
+        fs::write(&level_path, data)?;
+    }
+
+    write_world_pack_manifests(config, linked_packs)
+}
+
+pub fn write_dev_config(config: &DebugConfig) -> Result<PathBuf> {
+    let world_dir = world_dir(config);
+    fs::create_dir_all(&world_dir)?;
+
+    let game_exe = PathBuf::from(&config.game_executable_path);
+    let default_skin = game_exe
+        .parent()
+        .unwrap_or_else(|| game_exe.as_path())
+        .join("data/skin_packs/vanilla/steve.png")
+        .to_string_lossy()
+        .replace('\\', "/");
+
+    let mut dev_config = json!({
+        "world_info": { "level_id": config.world_folder_name },
+        "room_info": {},
+        "player_info": {
+            "urs": "",
+            "user_id": 0,
+            "user_name": config.user_name,
+        }
+    });
+
+    if let Some(skin_info) = &config.skin_info {
+        let mut skin_info = skin_info.clone();
+        if let Value::Object(map) = &mut skin_info {
+            map.entry("slim".to_string()).or_insert(Value::Bool(false));
+            match map.get("skin").and_then(Value::as_str) {
+                Some(path) if !path.is_empty() => {}
+                _ => {
+                    map.insert("skin".to_string(), Value::String(default_skin));
+                }
+            }
+        }
+        dev_config["skin_info"] = skin_info;
+    } else {
+        dev_config["skin_info"] = json!({ "slim": false, "skin": default_skin });
+    }
+
+    let path = world_dir.join("dev_config.cppconfig");
+    fs::write(&path, serde_json::to_vec_pretty(&dev_config)?)?;
+    Ok(path)
+}
+
+fn write_world_pack_manifests(config: &DebugConfig, linked_packs: &[PackInfo]) -> Result<()> {
+    let mut behavior = Vec::new();
+    let mut resource = Vec::new();
+
+    for pack in linked_packs {
+        let entry = json!({
+            "pack_id": pack.uuid,
+            "version": pack.version,
+        });
+        match pack.pack_type {
+            PackType::Behavior => behavior.push(entry),
+            PackType::Resource => resource.push(entry),
+        }
+    }
+
+    let world_dir = world_dir(config);
+    let (behavior_file, resource_file) = if config.auto_join_game_effective() {
+        ("world_behavior_packs.json", "world_resource_packs.json")
+    } else {
+        (
+            "netease_world_behavior_packs.json",
+            "netease_world_resource_packs.json",
+        )
+    };
+
+    fs::write(
+        world_dir.join(behavior_file),
+        serde_json::to_vec_pretty(&behavior)?,
+    )?;
+    fs::write(
+        world_dir.join(resource_file),
+        serde_json::to_vec_pretty(&resource)?,
+    )?;
+    Ok(())
+}
+
+fn plugin_env_enabled() -> bool {
+    matches!(std::env::var("MCDEV_PLUGIN_ENV"), Ok(value) if value == "1" || value.eq_ignore_ascii_case("true"))
+}

src/debug/level_template.rs

@@ -0,0 +1,187 @@
+pub const LEVEL_DAT_TEMPLATE: &[u8] = &[
+    0x0a, 0x00, 0x00, 0x00, 0x83, 0x0b, 0x00, 0x00, 0x0a, 0x00, 0x00, 0x08, 0x0d, 0x00, 0x42, 0x69,
+    0x6f, 0x6d, 0x65, 0x4f, 0x76, 0x65, 0x72, 0x72, 0x69, 0x64, 0x65, 0x00, 0x00, 0x01, 0x12, 0x00,
+    0x43, 0x65, 0x6e, 0x74, 0x65, 0x72, 0x4d, 0x61, 0x70, 0x73, 0x54, 0x6f, 0x4f, 0x72, 0x69, 0x67,
+    0x69, 0x6e, 0x00, 0x01, 0x1e, 0x00, 0x43, 0x6f, 0x6e, 0x66, 0x69, 0x72, 0x6d, 0x65, 0x64, 0x50,
+    0x6c, 0x61, 0x74, 0x66, 0x6f, 0x72, 0x6d, 0x4c, 0x6f, 0x63, 0x6b, 0x65, 0x64, 0x43, 0x6f, 0x6e,
+    0x74, 0x65, 0x6e, 0x74, 0x00, 0x03, 0x0a, 0x00, 0x44, 0x69, 0x66, 0x66, 0x69, 0x63, 0x75, 0x6c,
+    0x74, 0x79, 0x02, 0x00, 0x00, 0x00, 0x08, 0x0f, 0x00, 0x46, 0x6c, 0x61, 0x74, 0x57, 0x6f, 0x72,
+    0x6c, 0x64, 0x4c, 0x61, 0x79, 0x65, 0x72, 0x73, 0xfa, 0x00, 0x7b, 0x22, 0x62, 0x69, 0x6f, 0x6d,
+    0x65, 0x5f, 0x69, 0x64, 0x22, 0x3a, 0x31, 0x2c, 0x22, 0x62, 0x6c, 0x6f, 0x63, 0x6b, 0x5f, 0x6c,
+    0x61, 0x79, 0x65, 0x72, 0x73, 0x22, 0x3a, 0x5b, 0x7b, 0x22, 0x62, 0x6c, 0x6f, 0x63, 0x6b, 0x5f,
+    0x6e, 0x61, 0x6d, 0x65, 0x22, 0x3a, 0x22, 0x6d, 0x69, 0x6e, 0x65, 0x63, 0x72, 0x61, 0x66, 0x74,
+    0x3a, 0x62, 0x65, 0x64, 0x72, 0x6f, 0x63, 0x6b, 0x22, 0x2c, 0x22, 0x63, 0x6f, 0x75, 0x6e, 0x74,
+    0x22, 0x3a, 0x31, 0x7d, 0x2c, 0x7b, 0x22, 0x62, 0x6c, 0x6f, 0x63, 0x6b, 0x5f, 0x6e, 0x61, 0x6d,
+    0x65, 0x22, 0x3a, 0x22, 0x6d, 0x69, 0x6e, 0x65, 0x63, 0x72, 0x61, 0x66, 0x74, 0x3a, 0x64, 0x69,
+    0x72, 0x74, 0x22, 0x2c, 0x22, 0x63, 0x6f, 0x75, 0x6e, 0x74, 0x22, 0x3a, 0x32, 0x7d, 0x2c, 0x7b,
+    0x22, 0x62, 0x6c, 0x6f, 0x63, 0x6b, 0x5f, 0x6e, 0x61, 0x6d, 0x65, 0x22, 0x3a, 0x22, 0x6d, 0x69,
+    0x6e, 0x65, 0x63, 0x72, 0x61, 0x66, 0x74, 0x3a, 0x67, 0x72, 0x61, 0x73, 0x73, 0x5f, 0x62, 0x6c,
+    0x6f, 0x63, 0x6b, 0x22, 0x2c, 0x22, 0x63, 0x6f, 0x75, 0x6e, 0x74, 0x22, 0x3a, 0x31, 0x7d, 0x5d,
+    0x2c, 0x22, 0x65, 0x6e, 0x63, 0x6f, 0x64, 0x69, 0x6e, 0x67, 0x5f, 0x76, 0x65, 0x72, 0x73, 0x69,
+    0x6f, 0x6e, 0x22, 0x3a, 0x36, 0x2c, 0x22, 0x73, 0x74, 0x72, 0x75, 0x63, 0x74, 0x75, 0x72, 0x65,
+    0x5f, 0x6f, 0x70, 0x74, 0x69, 0x6f, 0x6e, 0x73, 0x22, 0x3a, 0x6e, 0x75, 0x6c, 0x6c, 0x2c, 0x22,
+    0x77, 0x6f, 0x72, 0x6c, 0x64, 0x5f, 0x76, 0x65, 0x72, 0x73, 0x69, 0x6f, 0x6e, 0x22, 0x3a, 0x22,
+    0x76, 0x65, 0x72, 0x73, 0x69, 0x6f, 0x6e, 0x2e, 0x70, 0x6f, 0x73, 0x74, 0x5f, 0x31, 0x5f, 0x31,
+    0x38, 0x22, 0x7d, 0x0a, 0x01, 0x0d, 0x00, 0x46, 0x6f, 0x72, 0x63, 0x65, 0x47, 0x61, 0x6d, 0x65,
+    0x54, 0x79, 0x70, 0x65, 0x00, 0x03, 0x08, 0x00, 0x47, 0x61, 0x6d, 0x65, 0x54, 0x79, 0x70, 0x65,
+    0x01, 0x00, 0x00, 0x00, 0x03, 0x09, 0x00, 0x47, 0x65, 0x6e, 0x65, 0x72, 0x61, 0x74, 0x6f, 0x72,
+    0x01, 0x00, 0x00, 0x00, 0x08, 0x10, 0x00, 0x49, 0x6e, 0x76, 0x65, 0x6e, 0x74, 0x6f, 0x72, 0x79,
+    0x56, 0x65, 0x72, 0x73, 0x69, 0x6f, 0x6e, 0x06, 0x00, 0x31, 0x2e, 0x32, 0x31, 0x2e, 0x32, 0x01,
+    0x0a, 0x00, 0x49, 0x73, 0x48, 0x61, 0x72, 0x64, 0x63, 0x6f, 0x72, 0x65, 0x00, 0x01, 0x0c, 0x00,
+    0x4c, 0x41, 0x4e, 0x42, 0x72, 0x6f, 0x61, 0x64, 0x63, 0x61, 0x73, 0x74, 0x01, 0x01, 0x12, 0x00,
+    0x4c, 0x41, 0x4e, 0x42, 0x72, 0x6f, 0x61, 0x64, 0x63, 0x61, 0x73, 0x74, 0x49, 0x6e, 0x74, 0x65,
+    0x6e, 0x74, 0x01, 0x04, 0x0a, 0x00, 0x4c, 0x61, 0x73, 0x74, 0x50, 0x6c, 0x61, 0x79, 0x65, 0x64,
+    0x93, 0xcc, 0x04, 0x69, 0x00, 0x00, 0x00, 0x00, 0x08, 0x09, 0x00, 0x4c, 0x65, 0x76, 0x65, 0x6c,
+    0x4e, 0x61, 0x6d, 0x65, 0x22, 0x00, 0x4b, 0x49, 0x44, 0xe5, 0x8a, 0xa8, 0xe4, 0xbd, 0x9c, 0xe4,
+    0xbc, 0x98, 0xe5, 0x8c, 0x96, 0x55, 0x4c, 0x54, 0x52, 0x41, 0x5f, 0x58, 0xe5, 0xbc, 0x80, 0xe5,
+    0x8f, 0x91, 0xe6, 0xb5, 0x8b, 0xe8, 0xaf, 0x95, 0x03, 0x13, 0x00, 0x4c, 0x69, 0x6d, 0x69, 0x74,
+    0x65, 0x64, 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x4f, 0x72, 0x69, 0x67, 0x69, 0x6e, 0x58, 0x00, 0x00,
+    0x00, 0x80, 0x03, 0x13, 0x00, 0x4c, 0x69, 0x6d, 0x69, 0x74, 0x65, 0x64, 0x57, 0x6f, 0x72, 0x6c,
+    0x64, 0x4f, 0x72, 0x69, 0x67, 0x69, 0x6e, 0x59, 0x00, 0x00, 0x00, 0x80, 0x03, 0x13, 0x00, 0x4c,
+    0x69, 0x6d, 0x69, 0x74, 0x65, 0x64, 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x4f, 0x72, 0x69, 0x67, 0x69,
+    0x6e, 0x5a, 0x00, 0x00, 0x00, 0x80, 0x09, 0x1e, 0x00, 0x4d, 0x69, 0x6e, 0x69, 0x6d, 0x75, 0x6d,
+    0x43, 0x6f, 0x6d, 0x70, 0x61, 0x74, 0x69, 0x62, 0x6c, 0x65, 0x43, 0x6c, 0x69, 0x65, 0x6e, 0x74,
+    0x56, 0x65, 0x72, 0x73, 0x69, 0x6f, 0x6e, 0x03, 0x05, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00,
+    0x15, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x01, 0x0f, 0x00, 0x4d, 0x75, 0x6c, 0x74, 0x69, 0x70, 0x6c, 0x61, 0x79, 0x65, 0x72, 0x47, 0x61,
+    0x6d, 0x65, 0x01, 0x01, 0x15, 0x00, 0x4d, 0x75, 0x6c, 0x74, 0x69, 0x70, 0x6c, 0x61, 0x79, 0x65,
+    0x72, 0x47, 0x61, 0x6d, 0x65, 0x49, 0x6e, 0x74, 0x65, 0x6e, 0x74, 0x01, 0x03, 0x0b, 0x00, 0x4e,
+    0x65, 0x74, 0x68, 0x65, 0x72, 0x53, 0x63, 0x61, 0x6c, 0x65, 0x08, 0x00, 0x00, 0x00, 0x03, 0x0e,
+    0x00, 0x4e, 0x65, 0x74, 0x77, 0x6f, 0x72, 0x6b, 0x56, 0x65, 0x72, 0x73, 0x69, 0x6f, 0x6e, 0xae,
+    0x02, 0x00, 0x00, 0x03, 0x08, 0x00, 0x50, 0x6c, 0x61, 0x74, 0x66, 0x6f, 0x72, 0x6d, 0x02, 0x00,
+    0x00, 0x00, 0x03, 0x17, 0x00, 0x50, 0x6c, 0x61, 0x74, 0x66, 0x6f, 0x72, 0x6d, 0x42, 0x72, 0x6f,
+    0x61, 0x64, 0x63, 0x61, 0x73, 0x74, 0x49, 0x6e, 0x74, 0x65, 0x6e, 0x74, 0x03, 0x00, 0x00, 0x00,
+    0x04, 0x0a, 0x00, 0x52, 0x61, 0x6e, 0x64, 0x6f, 0x6d, 0x53, 0x65, 0x65, 0x64, 0xda, 0x83, 0xfb,
+    0x6a, 0x72, 0x36, 0x25, 0xd5, 0x01, 0x10, 0x00, 0x53, 0x70, 0x61, 0x77, 0x6e, 0x56, 0x31, 0x56,
+    0x69, 0x6c, 0x6c, 0x61, 0x67, 0x65, 0x72, 0x73, 0x00, 0x03, 0x06, 0x00, 0x53, 0x70, 0x61, 0x77,
+    0x6e, 0x58, 0x00, 0x00, 0x00, 0x80, 0x03, 0x06, 0x00, 0x53, 0x70, 0x61, 0x77, 0x6e, 0x59, 0x00,
+    0x00, 0x00, 0x80, 0x03, 0x06, 0x00, 0x53, 0x70, 0x61, 0x77, 0x6e, 0x5a, 0x00, 0x00, 0x00, 0x80,
+    0x03, 0x0e, 0x00, 0x53, 0x74, 0x6f, 0x72, 0x61, 0x67, 0x65, 0x56, 0x65, 0x72, 0x73, 0x69, 0x6f,
+    0x6e, 0x0a, 0x00, 0x00, 0x00, 0x04, 0x04, 0x00, 0x54, 0x69, 0x6d, 0x65, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x03, 0x0c, 0x00, 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x56, 0x65, 0x72, 0x73,
+    0x69, 0x6f, 0x6e, 0x01, 0x00, 0x00, 0x00, 0x03, 0x12, 0x00, 0x58, 0x42, 0x4c, 0x42, 0x72, 0x6f,
+    0x61, 0x64, 0x63, 0x61, 0x73, 0x74, 0x49, 0x6e, 0x74, 0x65, 0x6e, 0x74, 0x03, 0x00, 0x00, 0x00,
+    0x0a, 0x09, 0x00, 0x61, 0x62, 0x69, 0x6c, 0x69, 0x74, 0x69, 0x65, 0x73, 0x01, 0x0a, 0x00, 0x61,
+    0x74, 0x74, 0x61, 0x63, 0x6b, 0x6d, 0x6f, 0x62, 0x73, 0x00, 0x01, 0x0d, 0x00, 0x61, 0x74, 0x74,
+    0x61, 0x63, 0x6b, 0x70, 0x6c, 0x61, 0x79, 0x65, 0x72, 0x73, 0x00, 0x01, 0x05, 0x00, 0x62, 0x75,
+    0x69, 0x6c, 0x64, 0x01, 0x01, 0x10, 0x00, 0x64, 0x6f, 0x6f, 0x72, 0x73, 0x61, 0x6e, 0x64, 0x73,
+    0x77, 0x69, 0x74, 0x63, 0x68, 0x65, 0x73, 0x00, 0x05, 0x08, 0x00, 0x66, 0x6c, 0x79, 0x53, 0x70,
+    0x65, 0x65, 0x64, 0xcd, 0xcc, 0x4c, 0x3d, 0x01, 0x06, 0x00, 0x66, 0x6c, 0x79, 0x69, 0x6e, 0x67,
+    0x00, 0x01, 0x0a, 0x00, 0x69, 0x6e, 0x73, 0x74, 0x61, 0x62, 0x75, 0x69, 0x6c, 0x64, 0x00, 0x01,
+    0x0c, 0x00, 0x69, 0x6e, 0x76, 0x75, 0x6c, 0x6e, 0x65, 0x72, 0x61, 0x62, 0x6c, 0x65, 0x00, 0x01,
+    0x09, 0x00, 0x6c, 0x69, 0x67, 0x68, 0x74, 0x6e, 0x69, 0x6e, 0x67, 0x00, 0x01, 0x06, 0x00, 0x6d,
+    0x61, 0x79, 0x66, 0x6c, 0x79, 0x00, 0x01, 0x04, 0x00, 0x6d, 0x69, 0x6e, 0x65, 0x01, 0x01, 0x02,
+    0x00, 0x6f, 0x70, 0x00, 0x01, 0x0e, 0x00, 0x6f, 0x70, 0x65, 0x6e, 0x63, 0x6f, 0x6e, 0x74, 0x61,
+    0x69, 0x6e, 0x65, 0x72, 0x73, 0x00, 0x01, 0x08, 0x00, 0x74, 0x65, 0x6c, 0x65, 0x70, 0x6f, 0x72,
+    0x74, 0x00, 0x05, 0x09, 0x00, 0x77, 0x61, 0x6c, 0x6b, 0x53, 0x70, 0x65, 0x65, 0x64, 0xcd, 0xcc,
+    0xcc, 0x3d, 0x00, 0x01, 0x11, 0x00, 0x62, 0x6f, 0x6e, 0x75, 0x73, 0x43, 0x68, 0x65, 0x73, 0x74,
+    0x45, 0x6e, 0x61, 0x62, 0x6c, 0x65, 0x64, 0x01, 0x01, 0x11, 0x00, 0x62, 0x6f, 0x6e, 0x75, 0x73,
+    0x43, 0x68, 0x65, 0x73, 0x74, 0x53, 0x70, 0x61, 0x77, 0x6e, 0x65, 0x64, 0x00, 0x01, 0x0d, 0x00,
+    0x63, 0x68, 0x65, 0x61, 0x74, 0x73, 0x45, 0x6e, 0x61, 0x62, 0x6c, 0x65, 0x64, 0x00, 0x01, 0x12,
+    0x00, 0x63, 0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x62, 0x6c, 0x6f, 0x63, 0x6b, 0x6f, 0x75, 0x74,
+    0x70, 0x75, 0x74, 0x01, 0x01, 0x14, 0x00, 0x63, 0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x62, 0x6c,
+    0x6f, 0x63, 0x6b, 0x73, 0x65, 0x6e, 0x61, 0x62, 0x6c, 0x65, 0x64, 0x01, 0x01, 0x0f, 0x00, 0x63,
+    0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x73, 0x45, 0x6e, 0x61, 0x62, 0x6c, 0x65, 0x64, 0x01, 0x04,
+    0x0b, 0x00, 0x63, 0x75, 0x72, 0x72, 0x65, 0x6e, 0x74, 0x54, 0x69, 0x63, 0x6b, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0x0d, 0x00, 0x64, 0x61, 0x79, 0x6c, 0x69, 0x67, 0x68, 0x74,
+    0x43, 0x79, 0x63, 0x6c, 0x65, 0x00, 0x00, 0x00, 0x00, 0x01, 0x0f, 0x00, 0x64, 0x6f, 0x64, 0x61,
+    0x79, 0x6c, 0x69, 0x67, 0x68, 0x74, 0x63, 0x79, 0x63, 0x6c, 0x65, 0x01, 0x01, 0x0d, 0x00, 0x64,
+    0x6f, 0x65, 0x6e, 0x74, 0x69, 0x74, 0x79, 0x64, 0x72, 0x6f, 0x70, 0x73, 0x01, 0x01, 0x0a, 0x00,
+    0x64, 0x6f, 0x66, 0x69, 0x72, 0x65, 0x74, 0x69, 0x63, 0x6b, 0x01, 0x01, 0x12, 0x00, 0x64, 0x6f,
+    0x69, 0x6d, 0x6d, 0x65, 0x64, 0x69, 0x61, 0x74, 0x65, 0x72, 0x65, 0x73, 0x70, 0x61, 0x77, 0x6e,
+    0x00, 0x01, 0x0a, 0x00, 0x64, 0x6f, 0x69, 0x6e, 0x73, 0x6f, 0x6d, 0x6e, 0x69, 0x61, 0x01, 0x01,
+    0x11, 0x00, 0x64, 0x6f, 0x6c, 0x69, 0x6d, 0x69, 0x74, 0x65, 0x64, 0x63, 0x72, 0x61, 0x66, 0x74,
+    0x69, 0x6e, 0x67, 0x00, 0x01, 0x09, 0x00, 0x64, 0x6f, 0x6d, 0x6f, 0x62, 0x6c, 0x6f, 0x6f, 0x74,
+    0x01, 0x01, 0x0d, 0x00, 0x64, 0x6f, 0x6d, 0x6f, 0x62, 0x73, 0x70, 0x61, 0x77, 0x6e, 0x69, 0x6e,
+    0x67, 0x01, 0x01, 0x0b, 0x00, 0x64, 0x6f, 0x74, 0x69, 0x6c, 0x65, 0x64, 0x72, 0x6f, 0x70, 0x73,
+    0x01, 0x01, 0x0e, 0x00, 0x64, 0x6f, 0x77, 0x65, 0x61, 0x74, 0x68, 0x65, 0x72, 0x63, 0x79, 0x63,
+    0x6c, 0x65, 0x01, 0x01, 0x0e, 0x00, 0x64, 0x72, 0x6f, 0x77, 0x6e, 0x69, 0x6e, 0x67, 0x64, 0x61,
+    0x6d, 0x61, 0x67, 0x65, 0x01, 0x03, 0x0f, 0x00, 0x65, 0x64, 0x69, 0x74, 0x6f, 0x72, 0x57, 0x6f,
+    0x72, 0x6c, 0x64, 0x54, 0x79, 0x70, 0x65, 0x00, 0x00, 0x00, 0x00, 0x03, 0x08, 0x00, 0x65, 0x64,
+    0x75, 0x4f, 0x66, 0x66, 0x65, 0x72, 0x00, 0x00, 0x00, 0x00, 0x01, 0x18, 0x00, 0x65, 0x64, 0x75,
+    0x63, 0x61, 0x74, 0x69, 0x6f, 0x6e, 0x46, 0x65, 0x61, 0x74, 0x75, 0x72, 0x65, 0x73, 0x45, 0x6e,
+    0x61, 0x62, 0x6c, 0x65, 0x64, 0x00, 0x0a, 0x0b, 0x00, 0x65, 0x78, 0x70, 0x65, 0x72, 0x69, 0x6d,
+    0x65, 0x6e, 0x74, 0x73, 0x01, 0x24, 0x00, 0x64, 0x61, 0x74, 0x61, 0x5f, 0x64, 0x72, 0x69, 0x76,
+    0x65, 0x6e, 0x5f, 0x76, 0x61, 0x6e, 0x69, 0x6c, 0x6c, 0x61, 0x5f, 0x62, 0x6c, 0x6f, 0x63, 0x6b,
+    0x73, 0x5f, 0x61, 0x6e, 0x64, 0x5f, 0x69, 0x74, 0x65, 0x6d, 0x73, 0x01, 0x01, 0x15, 0x00, 0x65,
+    0x78, 0x70, 0x65, 0x72, 0x69, 0x6d, 0x65, 0x6e, 0x74, 0x73, 0x5f, 0x65, 0x76, 0x65, 0x72, 0x5f,
+    0x75, 0x73, 0x65, 0x64, 0x00, 0x01, 0x1e, 0x00, 0x73, 0x61, 0x76, 0x65, 0x64, 0x5f, 0x77, 0x69,
+    0x74, 0x68, 0x5f, 0x74, 0x6f, 0x67, 0x67, 0x6c, 0x65, 0x64, 0x5f, 0x65, 0x78, 0x70, 0x65, 0x72,
+    0x69, 0x6d, 0x65, 0x6e, 0x74, 0x73, 0x00, 0x00, 0x01, 0x0a, 0x00, 0x66, 0x61, 0x6c, 0x6c, 0x64,
+    0x61, 0x6d, 0x61, 0x67, 0x65, 0x01, 0x01, 0x0a, 0x00, 0x66, 0x69, 0x72, 0x65, 0x64, 0x61, 0x6d,
+    0x61, 0x67, 0x65, 0x01, 0x01, 0x0c, 0x00, 0x66, 0x72, 0x65, 0x65, 0x7a, 0x65, 0x64, 0x61, 0x6d,
+    0x61, 0x67, 0x65, 0x01, 0x03, 0x14, 0x00, 0x66, 0x75, 0x6e, 0x63, 0x74, 0x69, 0x6f, 0x6e, 0x63,
+    0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x6c, 0x69, 0x6d, 0x69, 0x74, 0x10, 0x27, 0x00, 0x00, 0x01,
+    0x17, 0x00, 0x68, 0x61, 0x73, 0x42, 0x65, 0x65, 0x6e, 0x4c, 0x6f, 0x61, 0x64, 0x65, 0x64, 0x49,
+    0x6e, 0x43, 0x72, 0x65, 0x61, 0x74, 0x69, 0x76, 0x65, 0x01, 0x01, 0x15, 0x00, 0x68, 0x61, 0x73,
+    0x4c, 0x6f, 0x63, 0x6b, 0x65, 0x64, 0x42, 0x65, 0x68, 0x61, 0x76, 0x69, 0x6f, 0x72, 0x50, 0x61,
+    0x63, 0x6b, 0x00, 0x01, 0x15, 0x00, 0x68, 0x61, 0x73, 0x4c, 0x6f, 0x63, 0x6b, 0x65, 0x64, 0x52,
+    0x65, 0x73, 0x6f, 0x75, 0x72, 0x63, 0x65, 0x50, 0x61, 0x63, 0x6b, 0x00, 0x01, 0x0e, 0x00, 0x69,
+    0x6d, 0x6d, 0x75, 0x74, 0x61, 0x62, 0x6c, 0x65, 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x00, 0x01, 0x11,
+    0x00, 0x69, 0x73, 0x43, 0x72, 0x65, 0x61, 0x74, 0x65, 0x64, 0x49, 0x6e, 0x45, 0x64, 0x69, 0x74,
+    0x6f, 0x72, 0x00, 0x01, 0x14, 0x00, 0x69, 0x73, 0x45, 0x78, 0x70, 0x6f, 0x72, 0x74, 0x65, 0x64,
+    0x46, 0x72, 0x6f, 0x6d, 0x45, 0x64, 0x69, 0x74, 0x6f, 0x72, 0x00, 0x01, 0x14, 0x00, 0x69, 0x73,
+    0x46, 0x72, 0x6f, 0x6d, 0x4c, 0x6f, 0x63, 0x6b, 0x65, 0x64, 0x54, 0x65, 0x6d, 0x70, 0x6c, 0x61,
+    0x74, 0x65, 0x00, 0x01, 0x13, 0x00, 0x69, 0x73, 0x46, 0x72, 0x6f, 0x6d, 0x57, 0x6f, 0x72, 0x6c,
+    0x64, 0x54, 0x65, 0x6d, 0x70, 0x6c, 0x61, 0x74, 0x65, 0x00, 0x01, 0x13, 0x00, 0x69, 0x73, 0x52,
+    0x61, 0x6e, 0x64, 0x6f, 0x6d, 0x53, 0x65, 0x65, 0x64, 0x41, 0x6c, 0x6c, 0x6f, 0x77, 0x65, 0x64,
+    0x00, 0x01, 0x10, 0x00, 0x69, 0x73, 0x53, 0x69, 0x6e, 0x67, 0x6c, 0x65, 0x55, 0x73, 0x65, 0x57,
+    0x6f, 0x72, 0x6c, 0x64, 0x00, 0x01, 0x1b, 0x00, 0x69, 0x73, 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x54,
+    0x65, 0x6d, 0x70, 0x6c, 0x61, 0x74, 0x65, 0x4f, 0x70, 0x74, 0x69, 0x6f, 0x6e, 0x4c, 0x6f, 0x63,
+    0x6b, 0x65, 0x64, 0x00, 0x01, 0x0d, 0x00, 0x6b, 0x65, 0x65, 0x70, 0x69, 0x6e, 0x76, 0x65, 0x6e,
+    0x74, 0x6f, 0x72, 0x79, 0x01, 0x09, 0x15, 0x00, 0x6c, 0x61, 0x73, 0x74, 0x4f, 0x70, 0x65, 0x6e,
+    0x65, 0x64, 0x57, 0x69, 0x74, 0x68, 0x56, 0x65, 0x72, 0x73, 0x69, 0x6f, 0x6e, 0x03, 0x05, 0x00,
+    0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x15, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x05, 0x0e, 0x00, 0x6c, 0x69, 0x67, 0x68, 0x74, 0x6e, 0x69,
+    0x6e, 0x67, 0x4c, 0x65, 0x76, 0x65, 0x6c, 0x00, 0x00, 0x00, 0x00, 0x03, 0x0d, 0x00, 0x6c, 0x69,
+    0x67, 0x68, 0x74, 0x6e, 0x69, 0x6e, 0x67, 0x54, 0x69, 0x6d, 0x65, 0x00, 0x77, 0x01, 0x00, 0x03,
+    0x11, 0x00, 0x6c, 0x69, 0x6d, 0x69, 0x74, 0x65, 0x64, 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x44, 0x65,
+    0x70, 0x74, 0x68, 0x10, 0x00, 0x00, 0x00, 0x03, 0x11, 0x00, 0x6c, 0x69, 0x6d, 0x69, 0x74, 0x65,
+    0x64, 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x57, 0x69, 0x64, 0x74, 0x68, 0x10, 0x00, 0x00, 0x00, 0x03,
+    0x15, 0x00, 0x6d, 0x61, 0x78, 0x63, 0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x63, 0x68, 0x61, 0x69,
+    0x6e, 0x6c, 0x65, 0x6e, 0x67, 0x74, 0x68, 0xff, 0xff, 0x00, 0x00, 0x01, 0x0b, 0x00, 0x6d, 0x6f,
+    0x62, 0x67, 0x72, 0x69, 0x65, 0x66, 0x69, 0x6e, 0x67, 0x01, 0x01, 0x13, 0x00, 0x6e, 0x61, 0x74,
+    0x75, 0x72, 0x61, 0x6c, 0x72, 0x65, 0x67, 0x65, 0x6e, 0x65, 0x72, 0x61, 0x74, 0x69, 0x6f, 0x6e,
+    0x01, 0x01, 0x12, 0x00, 0x6e, 0x65, 0x74, 0x65, 0x61, 0x73, 0x65, 0x45, 0x6e, 0x63, 0x72, 0x79,
+    0x70, 0x74, 0x46, 0x6c, 0x61, 0x67, 0x00, 0x09, 0x1f, 0x00, 0x6e, 0x65, 0x74, 0x65, 0x61, 0x73,
+    0x65, 0x53, 0x74, 0x72, 0x6f, 0x6e, 0x67, 0x68, 0x6f, 0x6c, 0x64, 0x53, 0x65, 0x6c, 0x65, 0x63,
+    0x74, 0x65, 0x64, 0x43, 0x68, 0x75, 0x6e, 0x6b, 0x73, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0x10,
+    0x00, 0x70, 0x65, 0x72, 0x6d, 0x69, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x73, 0x4c, 0x65, 0x76, 0x65,
+    0x6c, 0x01, 0x00, 0x00, 0x00, 0x03, 0x16, 0x00, 0x70, 0x6c, 0x61, 0x79, 0x65, 0x72, 0x50, 0x65,
+    0x72, 0x6d, 0x69, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x73, 0x4c, 0x65, 0x76, 0x65, 0x6c, 0x01, 0x00,
+    0x00, 0x00, 0x03, 0x19, 0x00, 0x70, 0x6c, 0x61, 0x79, 0x65, 0x72, 0x73, 0x73, 0x6c, 0x65, 0x65,
+    0x70, 0x69, 0x6e, 0x67, 0x70, 0x65, 0x72, 0x63, 0x65, 0x6e, 0x74, 0x61, 0x67, 0x65, 0x64, 0x00,
+    0x00, 0x00, 0x08, 0x04, 0x00, 0x70, 0x72, 0x69, 0x64, 0x00, 0x00, 0x01, 0x19, 0x00, 0x70, 0x72,
+    0x6f, 0x6a, 0x65, 0x63, 0x74, 0x69, 0x6c, 0x65, 0x73, 0x63, 0x61, 0x6e, 0x62, 0x72, 0x65, 0x61,
+    0x6b, 0x62, 0x6c, 0x6f, 0x63, 0x6b, 0x73, 0x01, 0x01, 0x03, 0x00, 0x70, 0x76, 0x70, 0x01, 0x05,
+    0x09, 0x00, 0x72, 0x61, 0x69, 0x6e, 0x4c, 0x65, 0x76, 0x65, 0x6c, 0x00, 0x00, 0x00, 0x00, 0x03,
+    0x08, 0x00, 0x72, 0x61, 0x69, 0x6e, 0x54, 0x69, 0x6d, 0x65, 0x80, 0xbb, 0x00, 0x00, 0x03, 0x0f,
+    0x00, 0x72, 0x61, 0x6e, 0x64, 0x6f, 0x6d, 0x74, 0x69, 0x63, 0x6b, 0x73, 0x70, 0x65, 0x65, 0x64,
+    0x01, 0x00, 0x00, 0x00, 0x01, 0x0d, 0x00, 0x72, 0x65, 0x63, 0x69, 0x70, 0x65, 0x73, 0x75, 0x6e,
+    0x6c, 0x6f, 0x63, 0x6b, 0x01, 0x01, 0x1e, 0x00, 0x72, 0x65, 0x71, 0x75, 0x69, 0x72, 0x65, 0x73,
+    0x43, 0x6f, 0x70, 0x69, 0x65, 0x64, 0x50, 0x61, 0x63, 0x6b, 0x52, 0x65, 0x6d, 0x6f, 0x76, 0x61,
+    0x6c, 0x43, 0x68, 0x65, 0x63, 0x6b, 0x00, 0x01, 0x14, 0x00, 0x72, 0x65, 0x73, 0x70, 0x61, 0x77,
+    0x6e, 0x62, 0x6c, 0x6f, 0x63, 0x6b, 0x73, 0x65, 0x78, 0x70, 0x6c, 0x6f, 0x64, 0x65, 0x01, 0x01,
+    0x13, 0x00, 0x73, 0x65, 0x6e, 0x64, 0x63, 0x6f, 0x6d, 0x6d, 0x61, 0x6e, 0x64, 0x66, 0x65, 0x65,
+    0x64, 0x62, 0x61, 0x63, 0x6b, 0x01, 0x03, 0x14, 0x00, 0x73, 0x65, 0x72, 0x76, 0x65, 0x72, 0x43,
+    0x68, 0x75, 0x6e, 0x6b, 0x54, 0x69, 0x63, 0x6b, 0x52, 0x61, 0x6e, 0x67, 0x65, 0x04, 0x00, 0x00,
+    0x00, 0x01, 0x10, 0x00, 0x73, 0x68, 0x6f, 0x77, 0x62, 0x6f, 0x72, 0x64, 0x65, 0x72, 0x65, 0x66,
+    0x66, 0x65, 0x63, 0x74, 0x01, 0x01, 0x0f, 0x00, 0x73, 0x68, 0x6f, 0x77, 0x63, 0x6f, 0x6f, 0x72,
+    0x64, 0x69, 0x6e, 0x61, 0x74, 0x65, 0x73, 0x00, 0x01, 0x0e, 0x00, 0x73, 0x68, 0x6f, 0x77, 0x64,
+    0x61, 0x79, 0x73, 0x70, 0x6c, 0x61, 0x79, 0x65, 0x64, 0x00, 0x01, 0x11, 0x00, 0x73, 0x68, 0x6f,
+    0x77, 0x64, 0x65, 0x61, 0x74, 0x68, 0x6d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x73, 0x01, 0x01,
+    0x12, 0x00, 0x73, 0x68, 0x6f, 0x77, 0x72, 0x65, 0x63, 0x69, 0x70, 0x65, 0x6d, 0x65, 0x73, 0x73,
+    0x61, 0x67, 0x65, 0x73, 0x01, 0x01, 0x08, 0x00, 0x73, 0x68, 0x6f, 0x77, 0x74, 0x61, 0x67, 0x73,
+    0x01, 0x01, 0x09, 0x00, 0x73, 0x70, 0x61, 0x77, 0x6e, 0x4d, 0x6f, 0x62, 0x73, 0x00, 0x03, 0x0b,
+    0x00, 0x73, 0x70, 0x61, 0x77, 0x6e, 0x72, 0x61, 0x64, 0x69, 0x75, 0x73, 0x0a, 0x00, 0x00, 0x00,
+    0x01, 0x13, 0x00, 0x73, 0x74, 0x61, 0x72, 0x74, 0x57, 0x69, 0x74, 0x68, 0x4d, 0x61, 0x70, 0x45,
+    0x6e, 0x61, 0x62, 0x6c, 0x65, 0x64, 0x00, 0x01, 0x14, 0x00, 0x74, 0x65, 0x78, 0x74, 0x75, 0x72,
+    0x65, 0x50, 0x61, 0x63, 0x6b, 0x73, 0x52, 0x65, 0x71, 0x75, 0x69, 0x72, 0x65, 0x64, 0x00, 0x01,
+    0x0b, 0x00, 0x74, 0x6e, 0x74, 0x65, 0x78, 0x70, 0x6c, 0x6f, 0x64, 0x65, 0x73, 0x01, 0x01, 0x15,
+    0x00, 0x74, 0x6e, 0x74, 0x65, 0x78, 0x70, 0x6c, 0x6f, 0x73, 0x69, 0x6f, 0x6e, 0x64, 0x72, 0x6f,
+    0x70, 0x64, 0x65, 0x63, 0x61, 0x79, 0x00, 0x01, 0x13, 0x00, 0x75, 0x73, 0x65, 0x4d, 0x73, 0x61,
+    0x47, 0x61, 0x6d, 0x65, 0x72, 0x74, 0x61, 0x67, 0x73, 0x4f, 0x6e, 0x6c, 0x79, 0x00, 0x04, 0x0f,
+    0x00, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x53, 0x74, 0x61, 0x72, 0x74, 0x43, 0x6f, 0x75, 0x6e, 0x74,
+    0xfe, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0x0a, 0x0e, 0x00, 0x77, 0x6f, 0x72, 0x6c, 0x64,
+    0x5f, 0x70, 0x6f, 0x6c, 0x69, 0x63, 0x69, 0x65, 0x73, 0x00, 0x00,
+];

src/debug/log.rs

@@ -0,0 +1,178 @@
+use std::sync::Mutex;
+
+use regex::{Captures, Regex};
+
+#[cfg(windows)]
+use windows_sys::Win32::System::Console::{
+    CONSOLE_SCREEN_BUFFER_INFO, FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_INTENSITY,
+    FOREGROUND_RED, GetConsoleScreenBufferInfo, GetStdHandle, STD_OUTPUT_HANDLE,
+    SetConsoleTextAttribute,
+};
+
+static CONSOLE_LOCK: Mutex<()> = Mutex::new(());
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ConsoleColor {
+    Default,
+    Green,
+    Red,
+    Yellow,
+    Cyan,
+    DarkGray,
+}
+
+pub struct LineBuffer {
+    buffer: String,
+    filter_python: bool,
+}
+
+impl LineBuffer {
+    pub fn new(filter_python: bool) -> Self {
+        Self {
+            buffer: String::new(),
+            filter_python,
+        }
+    }
+
+    pub fn append<F>(&mut self, bytes: &[u8], mut process_line: F)
+    where
+        F: FnMut(String),
+    {
+        self.buffer.push_str(&String::from_utf8_lossy(bytes));
+        while let Some(pos) = self.buffer.find('\n') {
+            let mut line = self.buffer[..pos].to_string();
+            self.buffer.drain(..=pos);
+            if line.ends_with('\r') {
+                line.pop();
+            }
+            if self.filter_python && !line.contains("[Python] ") {
+                continue;
+            }
+            process_line(line);
+        }
+    }
+
+    pub fn flush<F>(&mut self, mut process_line: F)
+    where
+        F: FnMut(String),
+    {
+        if self.buffer.is_empty() {
+            return;
+        }
+        let mut line = std::mem::take(&mut self.buffer);
+        if line.ends_with('\r') {
+            line.pop();
+        }
+        if self.filter_python && !line.contains("[Python] ") {
+            return;
+        }
+        process_line(line);
+    }
+}
+
+pub fn process_stdout_line(line: &str) {
+    if line.contains(" [INFO][Engine] ") {
+        return;
+    }
+    let color = if line.contains("[INFO][Developer]") {
+        ConsoleColor::DarkGray
+    } else if contains_ignore_ascii_case(line, "SUC") {
+        ConsoleColor::Green
+    } else if contains_ignore_ascii_case(line, "ERROR") {
+        ConsoleColor::Red
+    } else if contains_ignore_ascii_case(line, "WARN") {
+        ConsoleColor::Yellow
+    } else if contains_ignore_ascii_case(line, "DEBUG") {
+        ConsoleColor::Cyan
+    } else {
+        ConsoleColor::Default
+    };
+    print_colored(line, color);
+}
+
+pub fn process_stderr_line(line: &str) {
+    let line = rewrite_python_traceback_path(line);
+    print_colored(&line, ConsoleColor::Red);
+}
+
+pub fn rewrite_python_traceback_path(line: &str) -> String {
+    let re = Regex::new(r#"File "([A-Za-z0-9_\.]+)", line (\d+)"#).unwrap();
+    re.replace_all(line, |caps: &Captures<'_>| {
+        format!(
+            "File \"{}.py\", line {}",
+            caps[1].replace('.', "/"),
+            &caps[2]
+        )
+    })
+    .into_owned()
+}
+
+pub fn print_colored(message: &str, color: ConsoleColor) {
+    let _guard = CONSOLE_LOCK.lock().unwrap();
+    #[cfg(windows)]
+    unsafe {
+        let handle = GetStdHandle(STD_OUTPUT_HANDLE);
+        if handle.is_null() {
+            println!("{}", message);
+            return;
+        }
+        let mut info: CONSOLE_SCREEN_BUFFER_INFO = std::mem::zeroed();
+        let has_info = GetConsoleScreenBufferInfo(handle, &mut info) != 0;
+        if color != ConsoleColor::Default {
+            SetConsoleTextAttribute(handle, color_attr(color));
+        }
+        println!("{}", message);
+        if color != ConsoleColor::Default && has_info {
+            SetConsoleTextAttribute(handle, info.wAttributes);
+        }
+    }
+    #[cfg(not(windows))]
+    {
+        println!("{}", message);
+    }
+}
+
+#[cfg(windows)]
+fn color_attr(color: ConsoleColor) -> u16 {
+    match color {
+        ConsoleColor::Default => FOREGROUND_RED | FOREGROUND_GREEN | FOREGROUND_BLUE,
+        ConsoleColor::Green => FOREGROUND_GREEN | FOREGROUND_INTENSITY,
+        ConsoleColor::Red => FOREGROUND_RED | FOREGROUND_INTENSITY,
+        ConsoleColor::Yellow => FOREGROUND_RED | FOREGROUND_GREEN | FOREGROUND_INTENSITY,
+        ConsoleColor::Cyan => FOREGROUND_GREEN | FOREGROUND_BLUE | FOREGROUND_INTENSITY,
+        ConsoleColor::DarkGray => FOREGROUND_INTENSITY,
+    }
+}
+
+fn contains_ignore_ascii_case(haystack: &str, needle: &str) -> bool {
+    haystack
+        .as_bytes()
+        .windows(needle.len())
+        .any(|window| window.eq_ignore_ascii_case(needle.as_bytes()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{LineBuffer, rewrite_python_traceback_path};
+
+    #[test]
+    fn process_buffer_append_handles_crlf_half_lines_and_flush() {
+        let mut buffer = LineBuffer::new(true);
+        let mut lines = Vec::new();
+        buffer.append(b"noise\r\n[Python] first\r\n[Python] sec", |line| {
+            lines.push(line)
+        });
+        assert_eq!(lines, vec!["[Python] first"]);
+        buffer.append(b"ond\n", |line| lines.push(line));
+        buffer.flush(|line| lines.push(line));
+        assert_eq!(lines, vec!["[Python] first", "[Python] second"]);
+    }
+
+    #[test]
+    fn rewrite_traceback_module_path_to_file_path() {
+        assert_eq!(
+            rewrite_python_traceback_path(r#"Traceback File "a.b", line 3"#),
+            r#"Traceback File "a/b.py", line 3"#
+        );
+    }
+}

src/debug/mod.rs

@@ -0,0 +1,43 @@
+pub mod addon;
+pub mod config;
+pub mod env;
+pub mod hotreload;
+pub mod ipc;
+pub mod level;
+pub mod log;
+pub mod nbt;
+pub mod process;
+pub mod win;
+
+use std::path::Path;
+
+use crate::error::Result;
+
+pub fn run(project_dir: &Path) -> Result<()> {
+    let mut config = config::load_or_create(project_dir)?;
+    config::ensure_game_executable(project_dir, &mut config)?;
+
+    let mod_dirs = config.included_mod_dirs(project_dir)?;
+    let mut linked_packs = Vec::new();
+
+    if !config::env_is_subprocess_mode() {
+        env::clean_runtime_packs()?;
+
+        if config.include_debug_mod {
+            let debug_pack = addon::register_debug_mod(&config, &mod_dirs)?;
+            println!("[MCDK] 已注册调试MOD：{}", debug_pack.uuid);
+            linked_packs.push(debug_pack);
+        }
+
+        addon::link_user_mod_dirs(&mod_dirs, &mut linked_packs)?;
+        level::prepare_world(&config, &linked_packs)?;
+    }
+
+    let config_arg = if config.auto_join_game_effective() && !config::env_is_subprocess_mode() {
+        Some(level::write_dev_config(&config)?)
+    } else {
+        None
+    };
+
+    process::launch_game(&config, config_arg.as_deref(), &mod_dirs)
+}

src/debug/nbt.rs

@@ -0,0 +1,495 @@
+use std::{
+    collections::HashSet,
+    time::{SystemTime, UNIX_EPOCH},
+};
+
+use rand::RngCore;
+
+use crate::error::{CliError, Result};
+
+use super::config::DebugConfig;
+
+#[path = "level_template.rs"]
+mod level_template;
+
+const TAG_END: u8 = 0;
+const TAG_BYTE: u8 = 1;
+const TAG_SHORT: u8 = 2;
+const TAG_INT: u8 = 3;
+const TAG_LONG: u8 = 4;
+const TAG_FLOAT: u8 = 5;
+const TAG_DOUBLE: u8 = 6;
+const TAG_BYTE_ARRAY: u8 = 7;
+const TAG_STRING: u8 = 8;
+const TAG_LIST: u8 = 9;
+const TAG_COMPOUND: u8 = 10;
+const TAG_INT_ARRAY: u8 = 11;
+const TAG_LONG_ARRAY: u8 = 12;
+
+#[derive(Clone, Debug, PartialEq)]
+pub enum Tag {
+    Byte(i8),
+    Short(i16),
+    Int(i32),
+    Long(i64),
+    Float(f32),
+    Double(f64),
+    ByteArray(Vec<i8>),
+    String(String),
+    List { element_type: u8, items: Vec<Tag> },
+    Compound(Vec<(String, Tag)>),
+    IntArray(Vec<i32>),
+    LongArray(Vec<i64>),
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct LevelDat {
+    version: u32,
+    root_name: String,
+    root: Tag,
+}
+
+impl LevelDat {
+    pub fn parse(bytes: &[u8]) -> Result<Self> {
+        if bytes.len() < 8 {
+            return Err(CliError::InvalidData(
+                "level.dat is shorter than Bedrock header".to_string(),
+            ));
+        }
+        let version = u32::from_le_bytes(bytes[0..4].try_into().unwrap());
+        let declared_len = u32::from_le_bytes(bytes[4..8].try_into().unwrap()) as usize;
+        let payload = &bytes[8..];
+        if declared_len != payload.len() {
+            return Err(CliError::InvalidData(format!(
+                "level.dat payload length mismatch: header={declared_len}, actual={}",
+                payload.len()
+            )));
+        }
+        let mut reader = Reader {
+            bytes: payload,
+            pos: 0,
+        };
+        let tag_type = reader.u8()?;
+        if tag_type != TAG_COMPOUND {
+            return Err(CliError::InvalidData(
+                "level.dat root tag is not a compound".to_string(),
+            ));
+        }
+        let root_name = reader.string()?;
+        let root = reader.tag_payload(TAG_COMPOUND)?;
+        if reader.pos != payload.len() {
+            return Err(CliError::InvalidData(
+                "trailing bytes after level.dat root compound".to_string(),
+            ));
+        }
+        Ok(Self {
+            version,
+            root_name,
+            root,
+        })
+    }
+
+    pub fn to_bytes(&self) -> Result<Vec<u8>> {
+        let mut payload = Vec::new();
+        payload.push(TAG_COMPOUND);
+        write_string(&mut payload, &self.root_name)?;
+        write_tag_payload(&mut payload, &self.root)?;
+
+        let mut bytes = Vec::with_capacity(8 + payload.len());
+        bytes.extend_from_slice(&self.version.to_le_bytes());
+        bytes.extend_from_slice(&(payload.len() as u32).to_le_bytes());
+        bytes.extend_from_slice(&payload);
+        Ok(bytes)
+    }
+
+    pub fn set_root(&mut self, key: &str, value: Tag) -> Result<()> {
+        let Tag::Compound(items) = &mut self.root else {
+            return Err(CliError::InvalidData(
+                "level.dat root is not compound".to_string(),
+            ));
+        };
+        set_compound_item(items, key, value);
+        Ok(())
+    }
+
+    #[cfg(test)]
+    pub fn root_value(&self, key: &str) -> Option<&Tag> {
+        let Tag::Compound(items) = &self.root else {
+            return None;
+        };
+        items
+            .iter()
+            .find(|(name, _)| name == key)
+            .map(|(_, tag)| tag)
+    }
+
+    pub fn root_compound_mut(&mut self, key: &str) -> Result<&mut Vec<(String, Tag)>> {
+        let Tag::Compound(items) = &mut self.root else {
+            return Err(CliError::InvalidData(
+                "level.dat root is not compound".to_string(),
+            ));
+        };
+        if let Some(index) = items.iter().position(|(name, _)| name == key) {
+            if !matches!(items[index].1, Tag::Compound(_)) {
+                items[index].1 = Tag::Compound(Vec::new());
+            }
+            let Tag::Compound(child) = &mut items[index].1 else {
+                unreachable!()
+            };
+            return Ok(child);
+        }
+        items.push((key.to_string(), Tag::Compound(Vec::new())));
+        let Tag::Compound(child) = &mut items.last_mut().unwrap().1 else {
+            unreachable!()
+        };
+        Ok(child)
+    }
+}
+
+pub fn create_level_dat(config: &DebugConfig) -> Result<Vec<u8>> {
+    let mut level = LevelDat::parse(level_template::LEVEL_DAT_TEMPLATE)?;
+    apply_config(&mut level, config, true)?;
+    level.to_bytes()
+}
+
+pub fn update_level_dat_world_data(
+    bytes: &[u8],
+    config: &DebugConfig,
+    init: bool,
+) -> Result<Vec<u8>> {
+    let mut level = LevelDat::parse(bytes)?;
+    apply_config(&mut level, config, init)?;
+    level.to_bytes()
+}
+
+pub fn update_level_dat_last_played(bytes: &[u8]) -> Result<Vec<u8>> {
+    let mut level = LevelDat::parse(bytes)?;
+    level.set_root("LastPlayed", Tag::Long(now_seconds()))?;
+    level.to_bytes()
+}
+
+fn apply_config(level: &mut LevelDat, config: &DebugConfig, init: bool) -> Result<()> {
+    level.set_root("LastPlayed", Tag::Long(now_seconds()))?;
+    level.set_root("LevelName", Tag::String(config.world_name.clone()))?;
+    if init && config.world_type != 2 {
+        level.set_root(
+            "RandomSeed",
+            Tag::Long(config.world_seed.unwrap_or_else(random_seed)),
+        )?;
+    }
+    level.set_root("GameType", Tag::Int(config.game_mode))?;
+    if init {
+        level.set_root("Generator", Tag::Int(config.world_type))?;
+    }
+    level.set_root("keepInventory", Tag::Byte(config.keep_inventory as i8))?;
+    level.set_root("cheatsEnabled", Tag::Byte(config.enable_cheats as i8))?;
+    level.set_root("doweathercycle", Tag::Byte(config.do_weather_cycle as i8))?;
+    level.set_root("dodaylightcycle", Tag::Byte(config.do_daylight_cycle as i8))?;
+
+    if let Some(experiments) = &config.experiment_options {
+        let child = level.root_compound_mut("experiments")?;
+        set_compound_item(
+            child,
+            "data_driven_biomes",
+            Tag::Byte(experiments.data_driven_biomes as i8),
+        );
+        set_compound_item(
+            child,
+            "data_driven_items",
+            Tag::Byte(experiments.data_driven_items as i8),
+        );
+        set_compound_item(
+            child,
+            "experimental_molang_features",
+            Tag::Byte(experiments.experimental_molang_features as i8),
+        );
+    }
+
+    Ok(())
+}
+
+fn now_seconds() -> i64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs() as i64)
+        .unwrap_or(0)
+}
+
+fn random_seed() -> i64 {
+    rand::thread_rng().next_u64() as i64
+}
+
+fn set_compound_item(items: &mut Vec<(String, Tag)>, key: &str, value: Tag) {
+    if let Some((_, slot)) = items.iter_mut().find(|(name, _)| name == key) {
+        *slot = value;
+    } else {
+        items.push((key.to_string(), value));
+    }
+}
+
+struct Reader<'a> {
+    bytes: &'a [u8],
+    pos: usize,
+}
+
+impl Reader<'_> {
+    fn take(&mut self, len: usize) -> Result<&[u8]> {
+        let end = self
+            .pos
+            .checked_add(len)
+            .ok_or_else(|| CliError::InvalidData("NBT offset overflow".to_string()))?;
+        if end > self.bytes.len() {
+            return Err(CliError::InvalidData(
+                "unexpected end of NBT data".to_string(),
+            ));
+        }
+        let out = &self.bytes[self.pos..end];
+        self.pos = end;
+        Ok(out)
+    }
+
+    fn u8(&mut self) -> Result<u8> {
+        Ok(self.take(1)?[0])
+    }
+    fn i8(&mut self) -> Result<i8> {
+        Ok(self.u8()? as i8)
+    }
+    fn i16(&mut self) -> Result<i16> {
+        Ok(i16::from_le_bytes(self.take(2)?.try_into().unwrap()))
+    }
+    fn i32(&mut self) -> Result<i32> {
+        Ok(i32::from_le_bytes(self.take(4)?.try_into().unwrap()))
+    }
+    fn i64(&mut self) -> Result<i64> {
+        Ok(i64::from_le_bytes(self.take(8)?.try_into().unwrap()))
+    }
+    fn f32(&mut self) -> Result<f32> {
+        Ok(f32::from_le_bytes(self.take(4)?.try_into().unwrap()))
+    }
+    fn f64(&mut self) -> Result<f64> {
+        Ok(f64::from_le_bytes(self.take(8)?.try_into().unwrap()))
+    }
+
+    fn string(&mut self) -> Result<String> {
+        let len = u16::from_le_bytes(self.take(2)?.try_into().unwrap()) as usize;
+        let bytes = self.take(len)?;
+        String::from_utf8(bytes.to_vec())
+            .map_err(|err| CliError::InvalidData(format!("NBT string is not UTF-8: {err}")))
+    }
+
+    fn tag_payload(&mut self, tag_type: u8) -> Result<Tag> {
+        match tag_type {
+            TAG_BYTE => Ok(Tag::Byte(self.i8()?)),
+            TAG_SHORT => Ok(Tag::Short(self.i16()?)),
+            TAG_INT => Ok(Tag::Int(self.i32()?)),
+            TAG_LONG => Ok(Tag::Long(self.i64()?)),
+            TAG_FLOAT => Ok(Tag::Float(self.f32()?)),
+            TAG_DOUBLE => Ok(Tag::Double(self.f64()?)),
+            TAG_BYTE_ARRAY => {
+                let len = checked_len(self.i32()?)?;
+                let mut values = Vec::with_capacity(len);
+                for _ in 0..len {
+                    values.push(self.i8()?);
+                }
+                Ok(Tag::ByteArray(values))
+            }
+            TAG_STRING => Ok(Tag::String(self.string()?)),
+            TAG_LIST => {
+                let element_type = self.u8()?;
+                let len = checked_len(self.i32()?)?;
+                let mut items = Vec::with_capacity(len);
+                for _ in 0..len {
+                    items.push(self.tag_payload(element_type)?);
+                }
+                Ok(Tag::List {
+                    element_type,
+                    items,
+                })
+            }
+            TAG_COMPOUND => {
+                let mut items = Vec::new();
+                loop {
+                    let child_type = self.u8()?;
+                    if child_type == TAG_END {
+                        break;
+                    }
+                    let name = self.string()?;
+                    let value = self.tag_payload(child_type)?;
+                    items.push((name, value));
+                }
+                Ok(Tag::Compound(items))
+            }
+            TAG_INT_ARRAY => {
+                let len = checked_len(self.i32()?)?;
+                let mut values = Vec::with_capacity(len);
+                for _ in 0..len {
+                    values.push(self.i32()?);
+                }
+                Ok(Tag::IntArray(values))
+            }
+            TAG_LONG_ARRAY => {
+                let len = checked_len(self.i32()?)?;
+                let mut values = Vec::with_capacity(len);
+                for _ in 0..len {
+                    values.push(self.i64()?);
+                }
+                Ok(Tag::LongArray(values))
+            }
+            _ => Err(CliError::InvalidData(format!(
+                "unsupported NBT tag type {tag_type}"
+            ))),
+        }
+    }
+}
+
+fn checked_len(value: i32) -> Result<usize> {
+    usize::try_from(value)
+        .map_err(|_| CliError::InvalidData(format!("negative NBT collection length {value}")))
+}
+
+fn write_named_tag(out: &mut Vec<u8>, name: &str, tag: &Tag) -> Result<()> {
+    out.push(tag_id(tag));
+    write_string(out, name)?;
+    write_tag_payload(out, tag)
+}
+
+fn write_string(out: &mut Vec<u8>, value: &str) -> Result<()> {
+    let len = u16::try_from(value.len())
+        .map_err(|_| CliError::InvalidData("NBT string is too long".to_string()))?;
+    out.extend_from_slice(&len.to_le_bytes());
+    out.extend_from_slice(value.as_bytes());
+    Ok(())
+}
+
+fn write_tag_payload(out: &mut Vec<u8>, tag: &Tag) -> Result<()> {
+    match tag {
+        Tag::Byte(value) => out.push(*value as u8),
+        Tag::Short(value) => out.extend_from_slice(&value.to_le_bytes()),
+        Tag::Int(value) => out.extend_from_slice(&value.to_le_bytes()),
+        Tag::Long(value) => out.extend_from_slice(&value.to_le_bytes()),
+        Tag::Float(value) => out.extend_from_slice(&value.to_le_bytes()),
+        Tag::Double(value) => out.extend_from_slice(&value.to_le_bytes()),
+        Tag::ByteArray(values) => {
+            write_len(out, values.len())?;
+            out.extend(values.iter().map(|value| *value as u8));
+        }
+        Tag::String(value) => write_string(out, value)?,
+        Tag::List {
+            element_type,
+            items,
+        } => {
+            out.push(*element_type);
+            write_len(out, items.len())?;
+            for item in items {
+                if tag_id(item) != *element_type {
+                    return Err(CliError::InvalidData(
+                        "NBT list contains mixed element types".to_string(),
+                    ));
+                }
+                write_tag_payload(out, item)?;
+            }
+        }
+        Tag::Compound(items) => {
+            let mut names = HashSet::with_capacity(items.len());
+            for (name, value) in items {
+                if !names.insert(name) {
+                    return Err(CliError::InvalidData(format!(
+                        "duplicate NBT compound key {name}"
+                    )));
+                }
+                write_named_tag(out, name, value)?;
+            }
+            out.push(TAG_END);
+        }
+        Tag::IntArray(values) => {
+            write_len(out, values.len())?;
+            for value in values {
+                out.extend_from_slice(&value.to_le_bytes());
+            }
+        }
+        Tag::LongArray(values) => {
+            write_len(out, values.len())?;
+            for value in values {
+                out.extend_from_slice(&value.to_le_bytes());
+            }
+        }
+    }
+    Ok(())
+}
+
+fn write_len(out: &mut Vec<u8>, len: usize) -> Result<()> {
+    let len = i32::try_from(len)
+        .map_err(|_| CliError::InvalidData("NBT collection is too long".to_string()))?;
+    out.extend_from_slice(&len.to_le_bytes());
+    Ok(())
+}
+
+fn tag_id(tag: &Tag) -> u8 {
+    match tag {
+        Tag::Byte(_) => TAG_BYTE,
+        Tag::Short(_) => TAG_SHORT,
+        Tag::Int(_) => TAG_INT,
+        Tag::Long(_) => TAG_LONG,
+        Tag::Float(_) => TAG_FLOAT,
+        Tag::Double(_) => TAG_DOUBLE,
+        Tag::ByteArray(_) => TAG_BYTE_ARRAY,
+        Tag::String(_) => TAG_STRING,
+        Tag::List { .. } => TAG_LIST,
+        Tag::Compound(_) => TAG_COMPOUND,
+        Tag::IntArray(_) => TAG_INT_ARRAY,
+        Tag::LongArray(_) => TAG_LONG_ARRAY,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::debug::config::{DebugConfig, NeteaseConfig};
+    use serde_json::{Map, Value};
+
+    fn config() -> DebugConfig {
+        DebugConfig {
+            included_mod_dirs: Vec::new(),
+            world_seed: Some(123),
+            reset_world: false,
+            world_name: "UnitWorld".to_string(),
+            world_folder_name: "UnitWorld".to_string(),
+            auto_join_game: true,
+            include_debug_mod: true,
+            auto_hot_reload_mods: true,
+            world_type: 1,
+            game_mode: 1,
+            enable_cheats: true,
+            keep_inventory: true,
+            do_weather_cycle: true,
+            do_daylight_cycle: true,
+            game_executable_path: String::new(),
+            debug_options: Value::Object(Map::new()),
+            netease_config: NeteaseConfig::default(),
+            user_name: "developer".to_string(),
+            skin_info: None,
+            experiment_options: None,
+        }
+    }
+
+    #[test]
+    fn template_round_trips() {
+        let level = LevelDat::parse(level_template::LEVEL_DAT_TEMPLATE).unwrap();
+        let bytes = level.to_bytes().unwrap();
+        let reparsed = LevelDat::parse(&bytes).unwrap();
+        assert_eq!(level, reparsed);
+    }
+
+    #[test]
+    fn updates_required_world_fields() {
+        let bytes = create_level_dat(&config()).unwrap();
+        let level = LevelDat::parse(&bytes).unwrap();
+        assert_eq!(
+            level.root_value("LevelName"),
+            Some(&Tag::String("UnitWorld".to_string()))
+        );
+        assert_eq!(level.root_value("GameType"), Some(&Tag::Int(1)));
+        assert_eq!(level.root_value("RandomSeed"), Some(&Tag::Long(123)));
+        assert!(matches!(level.root_value("LastPlayed"), Some(Tag::Long(value)) if *value > 0));
+    }
+}

src/debug/process.rs

@@ -0,0 +1,250 @@
+use std::{io, path::Path, thread};
+
+use crate::error::{CliError, Result};
+
+use super::{
+    config::{DebugConfig, ResolvedModDir},
+    hotreload::HotReloadTask,
+    ipc::DebugIpcServer,
+    log::{self, LineBuffer},
+};
+
+#[cfg(windows)]
+use std::{ffi::OsStr, os::windows::ffi::OsStrExt, ptr};
+
+#[cfg(windows)]
+use windows_sys::Win32::{
+    Foundation::{
+        CloseHandle, ERROR_BROKEN_PIPE, GetLastError, HANDLE, HANDLE_FLAG_INHERIT,
+        SetHandleInformation,
+    },
+    Storage::FileSystem::ReadFile,
+    System::{
+        Console::{GetStdHandle, STD_INPUT_HANDLE},
+        Pipes::CreatePipe,
+        Threading::{
+            CREATE_UNICODE_ENVIRONMENT, CreateProcessW, INFINITE, PROCESS_INFORMATION,
+            STARTF_USESTDHANDLES, STARTUPINFOW, WaitForSingleObject,
+        },
+    },
+};
+
+#[cfg(windows)]
+use windows_sys::Win32::Security::SECURITY_ATTRIBUTES;
+
+#[cfg(windows)]
+use super::win::WinHandle;
+
+#[cfg(windows)]
+pub fn launch_game(
+    config: &DebugConfig,
+    config_arg: Option<&Path>,
+    mod_dirs: &[ResolvedModDir],
+) -> Result<()> {
+    let enable_ipc = config.auto_hot_reload_mods;
+    let ipc = if enable_ipc {
+        let server = DebugIpcServer::start()?;
+        println!("[MCDK] IPC调试服务器已启动，端口：{}", server.port());
+        Some(server)
+    } else {
+        None
+    };
+
+    let command = build_command(config, config_arg);
+    let mut command_w = wide_null(OsStr::new(&command));
+    let env_block = ipc
+        .as_ref()
+        .map(|server| build_environment_block(server.port()));
+
+    let mut security = SECURITY_ATTRIBUTES {
+        nLength: std::mem::size_of::<SECURITY_ATTRIBUTES>() as u32,
+        lpSecurityDescriptor: ptr::null_mut(),
+        bInheritHandle: 1,
+    };
+
+    let (out_read, out_write) = create_pipe_pair(&mut security)?;
+    let (err_read, err_write) = create_pipe_pair(&mut security)?;
+
+    let mut startup: STARTUPINFOW = unsafe { std::mem::zeroed() };
+    startup.cb = std::mem::size_of::<STARTUPINFOW>() as u32;
+    startup.dwFlags = STARTF_USESTDHANDLES;
+    startup.hStdOutput = out_write.raw();
+    startup.hStdError = err_write.raw();
+    startup.hStdInput = unsafe { GetStdHandle(STD_INPUT_HANDLE) };
+
+    let mut process_info: PROCESS_INFORMATION = unsafe { std::mem::zeroed() };
+    let env_ptr = env_block
+        .as_ref()
+        .map(|block| block.as_ptr().cast_mut().cast())
+        .unwrap_or(ptr::null_mut());
+    let creation_flags = if env_block.is_some() {
+        CREATE_UNICODE_ENVIRONMENT
+    } else {
+        0
+    };
+
+    let ok = unsafe {
+        CreateProcessW(
+            ptr::null(),
+            command_w.as_mut_ptr(),
+            ptr::null_mut(),
+            ptr::null_mut(),
+            1,
+            creation_flags,
+            env_ptr,
+            ptr::null(),
+            &startup,
+            &mut process_info,
+        )
+    };
+    if ok == 0 {
+        let err = io::Error::last_os_error();
+        return Err(CliError::Io(io::Error::new(
+            err.kind(),
+            format!("CreateProcessW failed for command {command:?}: {err}"),
+        )));
+    }
+
+    drop(out_write);
+    drop(err_write);
+
+    let pid = process_info.dwProcessId;
+    let stdout_filter = config.include_debug_mod;
+    let stderr_filter = config.include_debug_mod;
+    let stdout_thread =
+        thread::spawn(move || read_pipe(out_read, stdout_filter, log::process_stdout_line));
+    let stderr_thread =
+        thread::spawn(move || read_pipe(err_read, stderr_filter, log::process_stderr_line));
+
+    let mut hotreload = if config.auto_hot_reload_mods {
+        ipc.clone()
+            .and_then(|server| HotReloadTask::start(pid, mod_dirs, server))
+    } else {
+        None
+    };
+
+    unsafe { WaitForSingleObject(process_info.hProcess, INFINITE) };
+
+    if let Some(task) = &mut hotreload {
+        task.safe_exit();
+    }
+    if let Some(server) = &ipc {
+        server.safe_exit();
+    }
+
+    let _ = stdout_thread.join();
+    let _ = stderr_thread.join();
+
+    unsafe {
+        CloseHandle(process_info.hProcess);
+        CloseHandle(process_info.hThread);
+    }
+    Ok(())
+}
+
+#[cfg(not(windows))]
+pub fn launch_game(
+    _config: &DebugConfig,
+    _config_arg: Option<&Path>,
+    _mod_dirs: &[ResolvedModDir],
+) -> Result<()> {
+    Err(CliError::InvalidInput(
+        "debug launch is only supported on Windows".to_string(),
+    ))
+}
+
+#[cfg(windows)]
+fn build_command(config: &DebugConfig, config_arg: Option<&Path>) -> String {
+    let mut command = String::new();
+    command.push('"');
+    command.push_str(&config.game_executable_path);
+    command.push('"');
+    if !config.netease_config.chat_extension {
+        command.push_str(" chatExtension=false");
+    }
+    if let Some(path) = config_arg {
+        command.push_str(" config=\"");
+        command.push_str(&path.to_string_lossy().replace('\\', "/"));
+        command.push('"');
+    }
+    command
+}
+
+#[cfg(windows)]
+fn create_pipe_pair(security: &mut SECURITY_ATTRIBUTES) -> Result<(WinHandle, WinHandle)> {
+    let mut read: HANDLE = ptr::null_mut();
+    let mut write: HANDLE = ptr::null_mut();
+    let ok = unsafe { CreatePipe(&mut read, &mut write, security, 0) };
+    if ok == 0 {
+        return Err(CliError::Io(io::Error::last_os_error()));
+    }
+    let read = WinHandle::new(read)?;
+    let write = WinHandle::new(write)?;
+    let ok = unsafe { SetHandleInformation(read.raw(), HANDLE_FLAG_INHERIT, 0) };
+    if ok == 0 {
+        return Err(CliError::Io(io::Error::last_os_error()));
+    }
+    Ok((read, write))
+}
+
+#[cfg(windows)]
+fn read_pipe<F>(pipe: WinHandle, filter_python: bool, process_line: F)
+where
+    F: Fn(&str) + Send + 'static,
+{
+    const BUFSZ: usize = 4096;
+    let mut line_buffer = LineBuffer::new(filter_python);
+    let mut buffer = [0u8; BUFSZ];
+
+    loop {
+        let mut bytes_read = 0u32;
+        let ok = unsafe {
+            ReadFile(
+                pipe.raw(),
+                buffer.as_mut_ptr().cast(),
+                buffer.len() as u32,
+                &mut bytes_read,
+                ptr::null_mut(),
+            )
+        };
+        if ok == 0 {
+            let err = unsafe { GetLastError() };
+            if err == ERROR_BROKEN_PIPE {
+                line_buffer.flush(|line| process_line(&line));
+            }
+            break;
+        }
+        if bytes_read == 0 {
+            line_buffer.flush(|line| process_line(&line));
+            break;
+        }
+        line_buffer.append(&buffer[..bytes_read as usize], |line| process_line(&line));
+    }
+}
+
+#[cfg(windows)]
+fn build_environment_block(ipc_port: u16) -> Vec<u16> {
+    let mut pairs: Vec<(Vec<u16>, Vec<u16>)> = std::env::vars_os()
+        .map(|(key, value)| (key.encode_wide().collect(), value.encode_wide().collect()))
+        .collect();
+    pairs.push((
+        OsStr::new("MCDEV_DEBUG_IPC_PORT").encode_wide().collect(),
+        OsStr::new(&ipc_port.to_string()).encode_wide().collect(),
+    ));
+    pairs.sort_by(|a, b| a.0.cmp(&b.0));
+
+    let mut block = Vec::new();
+    for (key, value) in pairs {
+        block.extend(key);
+        block.push('=' as u16);
+        block.extend(value);
+        block.push(0);
+    }
+    block.push(0);
+    block
+}
+
+#[cfg(windows)]
+fn wide_null(value: &OsStr) -> Vec<u16> {
+    value.encode_wide().chain(std::iter::once(0)).collect()
+}

src/debug/win.rs

@@ -0,0 +1,157 @@
+use std::{ffi::OsStr, io, path::Path};
+
+#[cfg(windows)]
+use std::{mem, os::windows::ffi::OsStrExt, ptr};
+
+#[cfg(windows)]
+use windows_sys::Win32::{
+    Foundation::{CloseHandle, HANDLE, INVALID_HANDLE_VALUE},
+    Storage::FileSystem::{
+        CreateFileW, FILE_FLAG_BACKUP_SEMANTICS, FILE_FLAG_OPEN_REPARSE_POINT, OPEN_EXISTING,
+    },
+    System::IO::DeviceIoControl,
+};
+
+#[cfg(windows)]
+const IO_REPARSE_TAG_MOUNT_POINT: u32 = 0xA0000003;
+#[cfg(windows)]
+const FSCTL_SET_REPARSE_POINT: u32 = 0x0009_00A4;
+#[cfg(windows)]
+const GENERIC_WRITE_ACCESS: u32 = 0x4000_0000;
+
+#[cfg(windows)]
+#[repr(C)]
+struct ReparseDataBufferHeader {
+    reparse_tag: u32,
+    reparse_data_length: u16,
+    reserved: u16,
+    substitute_name_offset: u16,
+    substitute_name_length: u16,
+    print_name_offset: u16,
+    print_name_length: u16,
+}
+
+pub struct WinHandle(#[cfg(windows)] pub HANDLE);
+
+#[cfg(windows)]
+unsafe impl Send for WinHandle {}
+
+#[cfg(windows)]
+impl WinHandle {
+    pub fn new(handle: HANDLE) -> io::Result<Self> {
+        if handle == INVALID_HANDLE_VALUE || handle.is_null() {
+            Err(io::Error::last_os_error())
+        } else {
+            Ok(Self(handle))
+        }
+    }
+
+    pub fn raw(&self) -> HANDLE {
+        self.0
+    }
+}
+
+#[cfg(windows)]
+impl Drop for WinHandle {
+    fn drop(&mut self) {
+        if !self.0.is_null() && self.0 != INVALID_HANDLE_VALUE {
+            unsafe { CloseHandle(self.0) };
+            self.0 = ptr::null_mut();
+        }
+    }
+}
+
+#[cfg(windows)]
+pub fn wide_null(value: &OsStr) -> Vec<u16> {
+    value.encode_wide().chain(std::iter::once(0)).collect()
+}
+
+#[cfg(windows)]
+pub fn create_junction(target: &Path, link: &Path) -> io::Result<()> {
+    std::fs::create_dir_all(link.parent().unwrap_or_else(|| Path::new(".")))?;
+    if link.exists() {
+        std::fs::remove_dir_all(link)?;
+    }
+    std::fs::create_dir(link)?;
+
+    let link_w = wide_null(link.as_os_str());
+    let handle = unsafe {
+        CreateFileW(
+            link_w.as_ptr(),
+            GENERIC_WRITE_ACCESS,
+            0,
+            ptr::null_mut(),
+            OPEN_EXISTING,
+            FILE_FLAG_OPEN_REPARSE_POINT | FILE_FLAG_BACKUP_SEMANTICS,
+            ptr::null_mut(),
+        )
+    };
+    let handle = WinHandle::new(handle)?;
+
+    let real = std::fs::canonicalize(target)?;
+    let real_full_w: Vec<u16> = real.as_os_str().encode_wide().collect();
+    // Mount point reparse data uses `\??\` for SubstituteName and the
+    // plain DOS path for PrintName; `canonicalize` returns `\\?\...`.
+    const VERBATIM_PREFIX: [u16; 4] = [b'\\' as u16, b'\\' as u16, b'?' as u16, b'\\' as u16];
+    let real_w = if real_full_w.starts_with(&VERBATIM_PREFIX) {
+        &real_full_w[VERBATIM_PREFIX.len()..]
+    } else {
+        real_full_w.as_slice()
+    };
+
+    const SUBSTITUTE_PREFIX: [u16; 4] = [b'\\' as u16, b'?' as u16, b'?' as u16, b'\\' as u16];
+    let mut substitute_w = SUBSTITUTE_PREFIX.to_vec();
+    substitute_w.extend_from_slice(real_w);
+
+    let subst_len = substitute_w.len() * mem::size_of::<u16>();
+    let print_len = real_w.len() * mem::size_of::<u16>();
+    let header_len = mem::size_of::<ReparseDataBufferHeader>();
+    let total_len = header_len + subst_len + 2 + print_len + 2;
+    let mut buffer = vec![0u8; total_len];
+
+    unsafe {
+        let header = buffer.as_mut_ptr() as *mut ReparseDataBufferHeader;
+        (*header).reparse_tag = IO_REPARSE_TAG_MOUNT_POINT;
+        (*header).reparse_data_length = (total_len - 8) as u16;
+        (*header).reserved = 0;
+        (*header).substitute_name_offset = 0;
+        (*header).substitute_name_length = subst_len as u16;
+        (*header).print_name_offset = (subst_len + 2) as u16;
+        (*header).print_name_length = print_len as u16;
+
+        let path_buffer = buffer.as_mut_ptr().add(header_len) as *mut u16;
+        ptr::copy_nonoverlapping(substitute_w.as_ptr(), path_buffer, substitute_w.len());
+        ptr::copy_nonoverlapping(
+            real_w.as_ptr(),
+            path_buffer.add(substitute_w.len() + 1),
+            real_w.len(),
+        );
+    }
+
+    let mut bytes_returned = 0u32;
+    let ok = unsafe {
+        DeviceIoControl(
+            handle.raw(),
+            FSCTL_SET_REPARSE_POINT,
+            buffer.as_mut_ptr().cast(),
+            buffer.len() as u32,
+            ptr::null_mut(),
+            0,
+            &mut bytes_returned,
+            ptr::null_mut(),
+        )
+    };
+    if ok == 0 {
+        Err(io::Error::last_os_error())
+    } else {
+        Ok(())
+    }
+}
+
+#[cfg(not(windows))]
+pub fn create_junction(_target: &Path, _link: &Path) -> io::Result<()> {
+    Err(io::Error::new(
+        io::ErrorKind::Unsupported,
+        "debug launch is only supported on Windows",
+    ))
+}

src/main.rs

@@ -1,4 +1,5 @@
 mod commands;
+mod debug;
 mod entity;
 mod error;
 mod template;
@@ -14,5 +15,6 @@ fn main() {
         Commands::Create(args) => commands::create::execute(args),
         Commands::Init(args) => commands::init::execute(args),
         Commands::Components(args) => commands::components::execute(args),
+        Commands::Debug(args) => commands::debug::execute(args),
     }
 }