红函数

- 引言 -

有一整类小功能，赛博朋克模组只能依赖 Cyber Engine Tweaks 来实现——不是因为它们需要 Lua，而是因为没人把引擎调用暴露给 Redscript。检查某个归档文件是否已安装就是一个很好的例子：纯 RedScript 模组根本无从询问。

RedFunctions 是一个 RED4ext 插件，旨在逐个填补这些小缺失，一次一个原生功能。存档与资源查询、真实世界时钟、受限文件访问、操作系统剪贴板、原始鼠标输入、运行时生成的存档、用于覆盖层的输入抑制，以及 TweakDB 名称查找——所有这些都可以直接从纯 Redscript 中调用。

太长不看——这引擎调用RedScript永远值得！(ﾉ◕ヮ◕)ﾉ


- 致模组作者 -

一键导入，全面覆盖：

导入红色函数。*

// 存档与资源
RedFunc.ArchiveExists("my_cool_mod")  // -> 布尔值。可选的“.archive”，不区分大小写
红函数.档案列表()  // -> array<String>，所有已挂载的模组档案，已排序
RedFunc.ResourceExists("base\\path\\file.xbm") // -> 布尔值。此路径是否能从任意来源解析
红函数.版本()// -> 字符串，插件语义化版本

// 现实世界时钟（os.date / os.time 从未有过的 RedScript 实现）
红色函数.真实时间戳()// -> 双精度浮点数，Unix 纪元秒数
红函数.真实日期()  // -> 字符串，本地时间“YYYY-MM-DD HH:MM:SS”
%H:%M// -> 字符串，strftime；第二个参数 = UTC
红函数.实时时钟毫秒()  // -> 无符号64位整数，单调毫秒数——用于计时

// TweakDB 名称
RedFunc.TweakName(t"Items.Preset_Ajax_Default") // -> 字符串，未知或仍在加载时为空
红函数.调整名称就绪() // -> 布尔值，该表在启动时于后台线程加载
红函数.调整名称数量() // -> Int32，已加载名称（约350万）
RedFunc.TweakSearch("ajax", 0, 50) // -> array<String>; 类型 0 记录 / 1 公寓 / 2 查询 / 3 全部; 最多 5000
修改子项（"Items.Preset_Ajax_Default", 200）// -> 字符串数组，记录携带的公寓
红函数.调整名称已挂钩()// -> 布尔值，TDBID.ToStringDEBUG 通过此插件解析
红函数.调整名称源()// -> 字符串，已应答内容 + 钩子状态，供你的日志使用

// 只读文本文件，限制在游戏目录内
RedFunc.FileExists("r6\\config\\thing.json")// -> 布尔值
从文件 "r6\config\thing.json" 读取前 200 行文本（最多 2000 行），返回字符串数组

// 生成的 TweakXL 文件 - 将 .yaml 写入 r6\tweaks，下次启动时加载
RedFunc.WriteTweakFile("MyMod/prices.yaml", lines) // -> 布尔值；已创建父目录
RedFunc.DeleteTweakFile("MyMod/prices.yaml")  // -> 布尔值

// 模组状态——将 .json/.txt 写入 r6\storages，然后用 ReadTextFile 读取回来
RedFunc.WriteStorageFile("MyMod/state.json", lines) // -> Bool
红色函数.删除存储文件("我的模组/状态.json") // -> 布尔值

// 操作系统剪贴板——墨水文本字段从未有过
获取剪贴板文本()// -> 字符串（UTF-8，非文本则为空）
RedFunc.SetClipboardText("一些文本") // -> 布尔值

// 鼠标：绝对位置（菜单）和原始增量（游戏玩法）
红色函数.鼠标X01()  // -> 窗口中为 0..1 的浮点数，-1 表示不可用
红色函数.鼠标Y01()
红色功能.鼠标按钮(1) // -> 布尔值。1 左键，2 右键，3 中键
检测游戏是否在前台运行// -> 布尔
鼠标钩子() // -> 布尔值，安装一次原始输入读取器
鼠标横向移动增量() // -> 浮点数，自上次调用以来的移动量
鼠标纵向移动增量函数
鼠标滚轮操作  // -> 浮点数，自上次调用以来的档位

// 运行时归档：修补模板的标记浮点数，实时挂载结果
RedFunc.MountPatchedArchive(模板路径, 输出名称, 新资源路径, 标记, 值)
红色函数.归档最后错误()// -> 字符串，上次调用失败的原因

// 输入抑制 - 覆盖层拥有键盘控制权
设置脚本输入被阻止（真）// 没有其他模组的监听器会接收到输入
允许脚本输入(myListener)  // 除了这一个（null 清除）
红函数.是否脚本输入被阻止()  // -> 布尔值
红函数.脚本输入钩子就绪()  // -> 布尔值，在不支持的构建中为 false
红函数.脚本输入钩子错误()  // -> 字符串

通用文件原生功能被刻意设为只读，且无法离开游戏目录——不允许“..”，不允许绝对路径。未知的 strftime %-code 会被剥离，而不会导致崩溃。

有两个写入面，都受扩展名锁定，因此永远无法生成脚本、归档或配置文件。TweakXL 生成器将 .yaml 写入 r6\tweaks：模组只需计算一次其 TweakDB 记录，从下次启动起，TweakXL 就会像加载任何手工编写的模组一样加载它们——不再需要在每次启动时重新推送数百个 flats。存储写入器对你的自有状态执行相同操作，将 .json 或 .txt 写入 r6\storages，并通过 ReadTextFile 读回。MO2 用户：生成的文件会落在 Overwrite 中，这是正常的。

档案答案来自引擎的ResourceDepot——实际上的 骑乘，而不是磁盘上实际存在什么。REDmod 文件夹、传统的 archive\pc\mod 安装方式以及运行时挂载的归档都会如实回答，而一个存在但加载失败的文件则会说“不行”！用 ArchiveExists 按名称查找特定的归档；ResourceExists 则是询问内容是否存在，所以即使归档被重命名或重新打包，它依然有效。


- 给悬浮窗构建者 -

存在三个原生组件，因为Redscript UI无法自行实现这些功能。它们是RedWindows运行的基础。

鼠标。 游戏过程中，游戏每一帧都会将操作系统光标固定在屏幕中央，因此读取其位置毫无意义。MouseHook 会安装一个读取器，用于获取游戏本身所使用的原始移动数据；MouseTakeDeltaX/Y 和 MouseTakeWheel 会返回自上次调用以来收到的全部数据，因此每个 tick 都可以将它们整合为一个光标。在菜单中，光标可以自由移动，此时 MouseX01/MouseY01 是更简单的选择。按钮是直接读取的，这意味着在你窗口上的点击不会泄漏到游戏中。

输入抑制。 消耗一个动作并不会阻止其他模组：每个已注册的监听器仍然会收到回调，所以玩家在你的文本框中输入“n”会触发其他模组绑定到N键的任何操作。SetScriptInputBlocked会一次性静默游戏中的所有脚本输入监听器；AllowScriptInputFor可以豁免你自己的监听器，这样你仍然可以自己消耗动作。务必在每一条退出路径上都解除阻断。如果游戏更新后钩子不再适用，ScriptInputHookReady会返回false，并且不会阻断任何内容——请检查它并回退，而不是想当然。

运行时存档。 MountPatchedArchive 会接收一个模板 .archive 文件，其中包含一个 CR2W 文件，其参数被设置为独特的标记值；它会将这些标记替换为真实数值，为结果分配一个新的 depot 路径，并在无需重启游戏的情况下挂载它。将 ResRef.FromString 指向新路径，引擎就会像加载任何已发布资源一样加载它。每个标记必须在文件中恰好出现一次，否则该调用将被拒绝，ArchiveLastError 会说明原因。

- TweakDB 名称 -

TDBID.ToStringDEBUG 不是游戏函数。 引擎本身根本不附带名称表，对每个ID都返回空字符串。它能正常工作是因为Cyber Engine Tweaks挂钩了该调用，并从自己的名称文件中返回结果。所有使用StrContains来匹配记录路径的模组——包括我自己套件中的相当一部分——都在不知不觉中依赖于已安装CET。

RedFunctions 0.10.0 加入了这个功能。一张包含所有记录、扁平名称和查询名称的表格随 DLL 一起发布，由我自己的工具从 CDPR 在每次安装中都附带的 REDmod 调整源构建，并与游戏自身的 tweakdb 进行核对，因此不涉及任何第三方数据。启动时插件会在后台线程中加载它（大约一两秒，占用约 200 MB 内存），并且当 CET 不 已实现，挂钩了ToStringDEBUG本身，这样所有现有的路径检查都能直接生效。当CET 是 钩子保持关闭，CET 持续响应；上方的原生功能依然照常服务。运行时创建的名称——TweakXL 记录、TDBID.Create——会在生成时被学习。

有几件事值得了解。未知 id 会保持为 ""，与引擎自身的返回一致，而不是 CET 的 <TDBID:...> 形式。如果你的 mod 在启动时解析名称，请先检查 TweakNamesReady。TweakSearch 是不区分大小写的子字符串搜索：仅查记录时毫秒级返回，"all" 会遍历 350 万个名称并耗时近一秒，所以除非需要 flats，否则搜索记录即可——而要获取单条记录的 flats，请使用 TweakChildren，它是一次查找而非扫描。如果你想使用不同的表，将 CDPR 格式的 tweakdb.str 或 CET 风格的 tweakdbstr.kark 放在 DLL 旁边，会优先于随附的表，并且 REDmod 为已部署 mod 写入的名称（r6\cache\modded）会叠加读取。

如果你想在没有插件的情况下运行，照常软依赖即可：

@if(ModuleExists("RedFunctions"))
导入RedFunctions.*

- 更新 -

0.11.0 - 新增：TweakChildren 以查找方式列出记录实际携带的楼层数据，包括模组在运行时添加的名称，而非通过扫描。
0.10.0 - 无CET时TweakDB名称：TweakName / TweakNamesReady / TweakNamesCount / TweakNamesSource / TweakNamesHooked / TweakSearch。引擎不附带名称表；RedFunctions自带名称表（tweakdb_names.dvns位于DLL旁边，由游戏自身的REDmod源生成——无第三方数据）并自行响应ToStringDEBUG。
0.9.1 - 地址哈希现在会软失败。
0.9.0 - 输入抑制：SetScriptInputBlocked / AllowScriptInputFor / IsScriptInputBlocked / ScriptInputHookReady / ScriptInputHookError。覆盖层可以独占键盘输入，而其他模组不会对你输入的内容做出反应。
0.8.0 - 运行时归档：MountPatchedArchive / ArchiveLastError。在运行时从模板生成资源变体，并无需重启即可挂载。
0.7.0 - 模组状态存储：WriteStorageFile / DeleteStorageFile，仅限 r6\storages 目录及 .json/.txt 文件。
0.6.0 - 原始鼠标：MouseHook / MouseTakeDeltaX / MouseTakeDeltaY / MouseTakeWheel。游戏固定光标以隐藏的移动。
0.5.0 - 绝对鼠标：MouseX01 / MouseY01 / MouseButton / IsGameForeground。仅限菜单——游戏过程中光标会重新居中。
0.4.0 - 公开发布。剪贴板访问：GetClipboardText / SetClipboardText。
0.3.0 - 生成的TweakXL文件：WriteTweakFile / DeleteTweakFile，仅限于r6\tweaks目录和.yaml文件。计算其TweakDB记录的模组现在可以将其持久化，供TweakXL在启动时加载，而无需每次启动都重新推送flat数据。
0.2.0 - 现实世界时钟（RealTimestamp / RealDate / RealDateFormat / RealClockMs）以及只读游戏目录文本文件（FileExists / ReadTextFile）。
0.1.0 - ArchiveExists、ArchiveList、ResourceExists、Version。


- 计划中 -

目标很简单：CET赋予模组作者的每一项能力，纯Redscript都能实现。欢迎提出需求——如果你的Redscript模组仍需要依赖CET进行某个特定调用，请发布出来，它将成为下一个版本的候选功能。


- 需求 -

此模组需要你安装以下内容：
RED4ext
红模组

可选：
Redscript 配置框架 用于游戏内WIKI文档。


- 安装 -

1) 安装所有依赖项。
2) 将下载的文件解压到你的游戏主目录中。


- 卸载 -

删除目录 \Cyberpunk 2077\red4ext\plugins\RedFunctions
删除目录 \Cyberpunk 2077\r6\scripts\RedFunctions

存档中没有保存任何信息，因此随时移除都是安全的。


- 制作人员名单 -

基于 红库 由psiberx和 RED4ext.SDK 由WopsS提供，两者均为MIT许可。运行时归档挂载遵循psiberx在ArchiveXL中建立的机制。TweakDB名称钩子遵循yamashi在 网络引擎微调 (MIT)；名称表本身由游戏自带的REDmod文件生成，名称归CD PROJEKT RED所有。该表使用Sean Barrett（公有领域）的stb_image进行填充。

感谢RED4ext和Redscript社区提供的工具和文档，以及 土豆 因为是个小可爱。