RandomForge（随机熔炉）使用说明 v1.1.3
==========================================

作者：非小酋啊、Hy3、WorkBuddy
适用版本：Terraria 1.4.5.6 / TShock 6.1 / .NET 9.0
插件文件：RandomForge.dll
配置文件（单一文件）：
  · RandomForge.json   —— 内含「随机事件」「随机掉落」「随机礼物」三节，首次启动自动生成
  · RandomForge_默认配置.json —— 随包附带的"默认配置样例"，方便对照修改
                            （不要直接覆盖你的 RandomForge.json；仅在需要从零开始时把它改名用）

（首次启动时若检测到旧版拆分配置 RandomMayhem.json / RandomMancer.json / 随机礼物.json，
 会自动合并迁移进 RandomForge.json，迁移后旧文件可手动删除。）


------------------------------------------------
〇、这是什么（关于"缝合"）
------------------------------------------------
RandomForge（随机熔炉）最初是把三个插件缝在一起的合体版本：

  · RandomMayhem（随机事件）
  · RandomMancer（随机掉落）v0.1.2
  · RandomGift（随机礼物）v1.0.0（原作者：答辩）

v1.1.3 起做了大幅精简：原 RandomMayhem 的"自动随机事件"（主循环每 tick 按概率触发的
各种混乱效果）被整体移除——因为实际体验里基本没效果。最终只保留三个前身里真正有用、
彼此独立的三块功能，统一收纳进 **一个** RandomForge.json、只占一个插件槽位：

  · /请求投资 指令（来自 RandomMayhem，重做后变成"每 5 分钟随机抽一波物品"）
  · 随机掉落（来自 RandomMancer）
  · 随机礼物（来自 RandomGift，原作者：答辩）


------------------------------------------------
一、配置文件（单一 RandomForge.json）
------------------------------------------------
结构如下（键名均为中文）：

{
  "随机事件": { "冷却_秒": 300, "随机黑名单_ID列表": [71, 72, 73] },
  "随机掉落": { ... 原 RandomMancer 配置 ... },
  "随机礼物": { "是否启用": true, "间隔分钟": 5, "物品数量": 1, "提示消息": "……" }
}

  · 「随机事件」节现在只有两项：冷却_秒（指令冷却，单位秒）与 随机黑名单_ID列表（不作为
    随机物品发放的物品 ID，默认已屏蔽 71/72/73 三类钱币）。这是 v1.1.3 精简后的结果——
    自动事件相关的几十个配置项已全部移除。
  · 修改后使用 TShock 原生 /reload 即可整体生效（物品池、随机掉落黑名单、礼物定时器一并刷新）。
  · /rmtile、/rmnpc、/rmchest、/rmfish 四个开关指令的改动也写入同一个 RandomForge.json。
  · 首次启动若检测到旧版拆分配置，会自动合并迁移并生成 RandomForge.json，无需手动搬运。


------------------------------------------------
二、功能与触发机制
------------------------------------------------
合体后包含三块独立功能，互不干扰：

【/请求投资 指令】—— 玩家手动输入触发
  · 每位玩家每「冷却_秒」秒可用一次（默认 300 秒 = 5 分钟）。
  · 每次随机发放若干（1~5）个随机物品，每个物品随机类型、随机堆叠数量（上限 99），
    若该物品支持修饰词则随机一个修饰词。
  · 发放后私聊列出本次获得的物品清单（如：🎲 你获得了随机物品：铜镐 ×5、魔力果汁 ×12）。

【随机掉落】—— 四大来源的事件钩子
  · 物块破坏（挖矿/拆物块）、生物死亡、开宝箱、钓鱼钓上来 时触发随机掉落。

【随机礼物】—— 定时器的定时触发
  · 每隔「间隔分钟」分钟，给所有已登录玩家各发放「物品数量」个随机物品，并提示一句消息。

三块功能注册在同一个插件实例里，共用一套防御性 try-catch 兜底。


------------------------------------------------
三、指令一览
------------------------------------------------
/请求投资        （别名：/touzi、/invest）
  见下一节「四、/请求投资 详细说明」。

/rmtile   [on/off]   —— 物块破坏随机掉落 开/关
/rmnpc    [on/off]   —— 生物随机掉落 开/关
/rmchest  [on/off]   —— 宝箱随机掉落 开/关
/rmfish   [on/off]   —— 钓鱼随机掉落 开/关
  以上四个均为开关指令，不带参数直接输入可查看当前状态；修改后立即在内存生效，
  并写入 RandomForge.json（/reload 后持久化）。

/reload
  原生指令。整体重载 RandomForge.json（随机事件指令 + 随机掉落 + 随机礼物），
  刷新物品池、黑名单与礼物定时器，无需重启服务器。


------------------------------------------------
四、/请求投资 详细说明（v1.1.3 重做）
------------------------------------------------
原 /请求投资 是"向背包发放一把带 [轻] 前缀的铜镐"的求助指令；v1.1.3 把它重做成
"随机抽一波物品"的娱乐指令，规则如下：

  · 冷却：每位玩家独立计算，每「冷却_秒」秒（默认 300）才能用一次；未冷却好时输入会提示
    剩余等待秒数。
  · 数量：每次发放 1~5 个随机物品（随机个数）。
  · 类型：从全部物品 ID 中随机抽取，排除「随机黑名单_ID列表」中的 ID（默认屏蔽钱币）。
  · 堆叠：每个物品随机堆叠数量，上限 99（受物品自身 maxStack 限制）。
  · 修饰词：若物品支持修饰词（CanHavePrefixes），则随机一个合法修饰词。
  · 反馈：私聊列出本次获得的物品（名称 ×数量），例如
          🎲 你获得了随机物品：铜镐 ×5、魔力果汁 ×12、夜视头盔 ×1
    若物品池为空或被黑名单过滤光，则提示"这次什么都没摸到"。

  实现说明：物品通过 QuickSpawnItem 生成后，定位该物品槽位施加随机堆叠与随机修饰词，
  再以 MsgID 5 (PlayerSlot) 同步到客户端（参数顺序：number=玩家索引, number2=槽位）。


------------------------------------------------
五、随机掉落分类（四大来源）
------------------------------------------------
1) 物块破坏随机   —— 挖矿/拆物块时，按概率额外（或完全）掉落随机物品
2) 生物随机       —— 所有 NPC（敌对怪、友好生物、Boss）死亡时，按概率额外（或完全）掉落随机物品
3) 宝箱随机       —— 打开宝箱时箱内内容被随机化（每个宝箱只随机化一次，重复打开内容一致）
4) 钓鱼随机       —— 钓上来的物品纯随机（声纳药水也会显示随机物品）

每个来源都有独立的开关、掉落概率、随机黑名单；所有来源的"随机物品"还可统一配置
最小/最大堆叠、是否允许钱币。

【重要】Boss 类始终保留原掉落（含宝藏袋），即使开启"阻止原掉落"也只会在原掉落之外
额外叠加随机物品，绝不吞掉 Boss 掉落。


------------------------------------------------
六、随机礼物（定时给在线玩家发随机物品）
------------------------------------------------
由「随机礼物」插件（原作者：答辩）并入，配置在 RandomForge.json 的「随机礼物」一节：

  · 是否启用    —— 总开关（默认 true）
  · 间隔分钟    —— 每隔多少分钟发放一次（默认 5）
  · 物品数量    —— 每次给每位玩家发放几个随机物品（默认 1）
  · 提示消息    —— 发放时向玩家显示的提示前缀

机制说明：
  · 使用 System.Timers.Timer 定时触发；回调运行在线程池线程，内部通过
    Main.QueueMainThreadAction 回到游戏主线程再操作玩家，避免跨线程异常。
  · 只发给已登录（IsLoggedIn）的在线玩家，每人发放一个 1~6144 范围内的随机物品 ID，
    并发送提示消息（含物品名）。
  · 不做钱币/黑名单过滤（与原「随机礼物」行为一致）；如不需要某个物品，可在配置里
    关闭「是否启用」或调大「间隔分钟」。
  · 修改 RandomForge.json 后使用 /reload 即可重启动时器生效。


------------------------------------------------
七、稳定性说明
------------------------------------------------
· 【加载健壮性】Initialize 对配置读取/写入全程容错；物品池构建（遍历全部物品 ID 并
  SetDefaults）整体包裹 try-catch，遇异常仅降级（随机物品暂时不可用），绝不让插件初始化失败。
· 【SyncSlot 修正】物品同步包 NetMessage.SendData(MsgID=5 / PlayerSlot) 参数顺序为
  （number=玩家索引, number2=槽位）。参数写反会向客户端发送指向错误玩家/槽位的非法物品
  同步包，导致该玩家客户端崩溃/断线，甚至使服务器主线程卡死。本插件已修正。
· 【随机掉落钩子兜底】物块破坏 / 生物死亡 / 开箱 / 钓鱼判定 / 钓鱼给物品 五个钩子全部包裹
  try-catch；异常只记录日志、不外泄，且对"阻止原掉落"类钩子出错时会复位 ContinueExecution，
  即"宁可放过原版掉落，也绝不因为异常把玩家本该掉的东西吞掉"。
· 【随机礼物兜底】定时器回调内部对每位玩家单独 try-catch，单名玩家发放异常不影响他人；
  间隔分钟非法（≤0）或关闭时不会启动定时器，避免 Timer 抛异常；所有配置读写均带容错。
· v1.1.3 起移除了原 RandomMayhem 的自动随机事件系统（主循环每 tick 触发、7 类事件加权调度
  等），插件结构大幅简化，不再挂载 Main.Update 钩子，主循环零额外负担。
· 该插件不直接修改世界文件，也不与 TShock 原生 /i（给予物品）指令交互。


------------------------------------------------
八、更新日志
------------------------------------------------
v1.1.3（随机事件精简为单一指令）
  · 移除原 RandomMayhem 的全部"自动随机事件"（主循环按概率触发的生物召唤 / 物品变化 /
    血量蓝量 / 弹幕 / 增益减益 / 方块变化 / 天灾 七类事件），不再挂载 Main.Update 钩子。
  · 保留并**重做** /请求投资 指令：每位玩家每「冷却_秒」秒（默认 300）可用一次，每次随机
    发放 1~5 个随机物品（随机类型、随机堆叠上限 99、支持修饰词则随机修饰词），并私聊列出获得清单。
  · 「随机事件」配置节精简为两项：冷却_秒、随机黑名单_ID列表（默认屏蔽 71/72/73 钱币）。
  · 旧 RandomMayhem.json 迁移时仅取「冷却」与「物品黑名单」两项映射到新配置。
  · 随包附带 RandomForge_默认配置.json（全默认键值样例）。
  · 插件版本升至 v1.1.3。

v1.1.2（提示消息收敛 + 附带默认配置）
  · （注：v1.1.3 已彻底移除自动随机事件，本节所描述的"事件提示收敛"随之失效，仅作历史记录。）
  · 随包附带 RandomForge_默认配置.json。

v1.1.1（配置合一 + 修复事件触发顺序 bug）
  · 三份拆分配置合并为单一 RandomForge.json；旧拆分配置首次启动自动合并迁移。

v1.1.0（缝合第三名成员：随机礼物）
  · 将 RandomGift（随机礼物 v1.0.0，原作者：答辩）并入。

v1.0.0（缝合首发）
  · 将 RandomMayhem（随机事件）与 RandomMancer（随机掉落 v0.1.2）合并为单一插件 RandomForge。

（三个前身合并前各自最后版本要点，供溯源）
  RandomMayhem：原自动随机事件插件（v1.1.3 起其自动事件部分已移除，仅留 /请求投资 指令）。
  RandomMancer v0.1.2：五大事件钩子全部加防御性 try-catch 兜底。
  RandomGift v1.0.0（原作者：答辩）：定时给在线玩家发放随机物品。
