UniversalUnityDemosaics技术文档

1. 项目概述

UniversalUnityDemosaics是一套基于BepInEx框架开发的Unity3D游戏马赛克移除插件集合。该项目通过智能识别并禁用游戏中的马赛克渲染对象，实现视觉遮挡效果的移除，从而还原游戏原始视觉体验。项目采用模块化设计，提供多种不同技术路径的解决方案，以适应各类Unity游戏的实现差异。

1.1 核心技术优势

• 非侵入式设计：插件通过运行时修改渲染状态实现效果，不修改任何游戏原始文件
• 多方案适配：提供基于渲染器、材质、着色器等多种技术路径的解决方案
• 跨版本兼容：支持Unity 5.x至2022.x的主流版本
• 性能优化：核心算法经过优化，对游戏帧率影响控制在5%以内
• 开源可扩展：遵循MIT许可协议，代码完全开放可定制

1.2 技术实现原理

项目核心技术基于Unity引擎的渲染流水线干预，主要通过以下机制实现：

1. 渲染对象过滤：通过名称、标签或组件特征识别马赛克对象
2. 材质替换：将含马赛克效果的材质替换为透明或原始材质
3. 着色器重定向：修改渲染管线中的着色器参数或替换着色器
4. 网格操作：对包含马赛克的组合网格进行分离或隐藏处理

核心功能模块位于DemozaicCommon目录，提供统一的马赛克检测算法和工具类，各插件模块基于此实现具体功能。

2. 环境准备与安装

2.1 系统要求

• 操作系统：Windows 10/11 (64位)
• 游戏引擎：Unity3D 5.6及以上版本
• 前置框架：BepInEx 5.x或6.x（需与游戏架构匹配）
• 运行时：.NET Framework 4.x或.NET Core 3.1（取决于游戏版本）

2.2 获取与部署

2.2.1 源码获取

git clone https://gitcode.com/gh_mirrors/un/UniversalUnityDemosaics

2.2.2 编译流程（可选）

1. 使用Visual Studio 2019或更高版本打开解决方案文件UniversalDemosaics.sln
2. 根据目标游戏的Unity版本选择对应的项目配置
3. 构建解决方案，输出DLL文件位于各项目的bin/Debug或bin/Release目录

2.2.3 部署步骤

1. 确认游戏已安装BepInEx框架（参考BepInEx官方文档）
2. 将编译好的插件DLL文件复制到游戏目录下的BepInEx/plugins文件夹
3. 启动游戏，插件会自动加载并应用效果

3. 插件选择指南

3.1 插件类型及适用场景

DumbRendererDemosaic

• 技术路径：通过禁用包含特定关键词的渲染器组件实现效果
• 适用场景：大多数Unity游戏，特别是独立挂载马赛克组件的情况
• 实现位置：DumbRendererDemosaic/DumbRendererDemosaic.cs
• 优势：兼容性广，性能消耗低
• 限制：对组合网格或复杂嵌套结构支持有限

CombinedMeshDemosaic

• 技术路径：深度扫描并处理组合网格渲染器中的材质
• 适用场景：使用合并网格的新版Unity游戏（2018+）
• 实现位置：CombinedMeshDemosaic/CombinedMeshDemosaic.cs
• 优势：处理复杂网格结构能力强
• 限制：对性能有一定影响，配置相对复杂

MaterialReplaceDemosaic

• 技术路径：识别并替换含马赛克效果的材质
• 适用场景：Live2D模型或基于材质实现的马赛克效果
• 实现位置：MaterialReplaceDemosaic/MaterialReplaceDemosaic.cs
• 优势：对2D渲染对象效果显著
• 限制：需要正确识别目标材质名称

ShaderReplaceDemosaic

• 技术路径：替换或修改特定着色器参数
• 适用场景：使用自定义着色器实现的马赛克效果
• 实现位置：ShaderReplaceDemosaic/ShaderReplaceDemosaicPlugin.cs
• 优势：处理基于着色器的动态马赛克效果
• 限制：需要知道目标着色器名称和参数结构

3.2 插件选择决策流程

1. 首先尝试DumbRendererDemosaic作为基础解决方案
2. 如效果不完全，添加CombinedMeshDemosaic处理复杂网格
3. 针对2D元素，补充MaterialReplaceDemosaic
4. 如仍有残留，启用ShaderReplaceDemosaic处理着色器级效果

4. 配置与使用

4.1 基础配置

大多数插件可直接使用默认配置运行。对于需要自定义的场景，可在BepInEx配置文件中调整以下常见参数：

• Enabled：插件启用状态（true/false）
• TargetKeywords：用于识别马赛克对象的关键词列表
• CheckInterval：扫描间隔时间（毫秒）
• DebugMode：调试信息输出开关

4.2 高级配置示例

以ShaderReplaceDemosaic为例，典型配置如下：

[ShaderReplaceDemosaic]
Enabled = true
TargetShaderNames = MosaicShader,BlurEffect
ReplacementShader = Unlit/Transparent
DebugLog = false

4.3 多插件协同使用

对于复杂游戏场景，建议采用插件组合策略：

• 标准组合：DumbRendererDemosaic + CombinedMeshDemosaic
• 增强组合：标准组合 + MaterialReplaceDemosaic
• 完全组合：增强组合 + ShaderReplaceDemosaic

启用多个插件时，建议调整扫描优先级和间隔时间，避免资源竞争。

5. 故障排除

5.1 常见问题及解决方案

问题：插件已加载但无效果

排查步骤：

1. 检查游戏日志确认插件是否正常初始化
2. 启用DebugMode查看识别到的对象列表
3. 尝试调整TargetKeywords参数，添加游戏特定关键词
4. 确认是否使用了正确的插件组合

问题：游戏启动崩溃

排查步骤：

1. 检查BepInEx版本与游戏架构是否匹配（32位/64位）
2. 尝试单独加载一个插件，确定是否存在插件冲突
3. 检查游戏日志中的异常堆栈信息
4. 尝试降低插件扫描频率（增大CheckInterval值）

问题：部分场景马赛克未移除

排查步骤：

1. 确认是否使用了组合网格渲染器（需CombinedMeshDemosaic支持）
2. 检查是否存在基于着色器的动态马赛克效果
3. 使用DebugMode获取未处理对象信息，添加到TargetKeywords
4. 尝试更换或组合使用不同插件

5.2 日志分析

插件日志位于BepInEx/LogOutput.log，关键信息包括：

• 插件加载状态
• 识别到的马赛克对象数量
• 操作执行结果
• 错误及异常信息

6. 技术实现细节

6.1 核心模块解析

MosaicTools.cs（位于DemozaicCommon）提供核心功能：

• FindMosaicRenderers()：基于关键词搜索渲染器
• ReplaceMaterial()：替换指定对象的材质
• ModifyShaderParameters()：修改着色器参数
• IsMosaicCandidate()：马赛克对象判断逻辑

Metadata.cs提供版本信息和兼容性检查功能，确保插件与目标游戏版本匹配。

6.2 性能优化策略

• 采用对象池模式减少GC开销
• 使用层级遍历替代全局搜索
• 实现增量扫描机制，避免帧阻塞
• 针对不同Unity版本使用条件编译

7. 使用注意事项

• 本工具仅用于个人学习研究，请勿用于商业用途
• 使用前请确保拥有游戏的合法使用权
• 部分游戏可能采用反作弊机制，使用插件可能导致账号风险
• 插件可能与其他修改工具存在冲突，建议单独测试
• 定期更新插件以获取最新兼容性支持

8. 案例分析

案例1：某3D冒险游戏

问题：角色对话时面部马赛克无法移除 分析：使用组合网格渲染器，马赛克是网格的一部分 解决方案：启用CombinedMeshDemosaic插件，配置适当的材质过滤参数 效果：成功分离并隐藏马赛克网格部分，不影响角色其他部分渲染

案例2：某Live2D视觉小说

问题：角色立绘存在动态马赛克效果 分析：通过材质透明度实现的动态遮挡 解决方案：使用MaterialReplaceDemosaic插件，替换目标材质为原始透明材质 效果：完全移除动态遮挡效果，保持角色动画正常

案例3：某开放世界游戏

问题：特定场景中的环境马赛克时有时无 分析：基于距离和视角动态加载的着色器效果 解决方案：组合使用DumbRendererDemosaic和ShaderReplaceDemosaic 效果：稳定移除各类场景中的动态马赛克效果