安装与初始化（Install & Setup）

本章节将带你快速安装并导入 Fink Framework 到您的项目中，并进行必要的初始化设置。
如果你是第一次使用 Fink Framework，建议从这里开始。

1. 下载文件

Fink Framework 推荐使用 UnityPackage 进行安装，是最简单、最稳定的方式。

官方 Release 版本：

如无法访问 GitHub，可使用以下镜像下载：

2 框架依赖说明

在导入框架之前，请确认项目中并未已经安装以下表格中框架所需的四项依赖，否则导入框架时会重复安装依赖，不推荐重复安装。

Fink Framework 内置以下必要依赖，并已全部内置在
Assets/FinkFramework/Plugins/ 目录中：

依赖库用途版本备注
UniTask异步加载、任务系统支持源码版必需，提供性能优于协程的 async/await
Odin Serializer数据序列化与反射支持源码版必需，框架数据管线核心依赖
Newtonsoft.JsonJSON 解析与调试输出DLL可选（但推荐保持）
ExcelDataReaderExcel 配表读取DLL数据管线必需

⚠ 注意 ：请不要重复安装以上依赖。

如果你的项目中已经存在同名依赖（例如已有 UniTask 或 Newtonsoft.Json等），
可能出现以下问题：

  • 类型重复 / 命名空间冲突
  • 第三方 DLL 重复导入导致编译失败
  • 框架无法引用正确版本的依赖

解决方案：

  1. 如果你的项目已经安装过相同依赖（如 UniTask / Newtonsoft.Json）
    → 你可以安全地删除 Assets/FinkFramework/Plugins/ 下对应的那一份。

  2. 如果你不确定是否应删除
    → 推荐保留 FinkFramework 自带的版本，并移除你项目原来的版本。

  3. 若两边版本不同，推荐使用 较新版本。

框架内置依赖已按照正确顺序组织，不会污染你的项目结构。

3. 导入到 Unity 项目

下载后，直接 将 .unitypackage 文件拖入Project项目视图中，Unity 会自动导入。

unity

当您导入并编译完成后会自动弹出欢迎使用窗口，如下图。若您看到该窗口则表示已安装完毕。

unity

4. 全局配置说明

导入完毕框架后，我们需要对框架进行必要的初始化设置。您可以用以下两种任意一种方式进入全局设置界面。

  • 点击欢迎使用窗口中的打开框架设置按钮
  • 点击Edit->Project Settings->Fink Framework窗口。

当您看到如下图所示的窗口，即表示您已进入框架全局设置流程。

unity

框架提供 5 类核心配置：数据管线、加密策略、环境行为、UI 系统、资源后端。以下将逐项说明。

5 数据配置

unity

数据配置（Data Pipeline Settings）用于控制框架的数据驱动流程，包括：

  • 运行时使用的数据源类型（Binary / JSON）
  • C# 数据类的生成路径模式（内部 / 外部）

5.1 运行时数据加载模式

用于指定游戏运行时实际读取的数据文件类型。

模式行为说明
Binary（推荐）游戏运行时读取 加密二进制数据。
同时仍然会自动导出 JSON 文件，但该 JSON 仅用于外部调试，不会被运行时读取。
JSON游戏运行时改为读取 JSON 文件。
不会导出二进制数据，且 JSON 将写入 StreamingAssets 中以供运行时加载。

5.2 C# 数据类路径模式

提供两种生成路径：

模式C# 数据类生成位置使用场景
内部路径（默认）Assets/Scripts/Data/AutoGen/DataClass/适合个人项目、简单结构 会自动触发重编译
外部路径FinkFramework_Data/AutoGen/Data/DataClass/适合团队开发，将框架与项目代码物理分离 不会触发重编译

该选项对应：

// 若为 false → 生成到 Assets 内部(触发重编译)
// 若为 true  → 生成到 FinkFramework_Data 根目录(不会触发重编译 更快速)
public bool CSharpUseExternal = false;

6 加密配置

unity

用于管理框架的整体数据加密策略，包括 AES 密钥、文件后缀等。

6.1 开启加密

  • 开启后，所有 DataUtil.Save() 生成的二进制数据将使用 AES 加密处理。
  • 若关闭，则框架写入纯二进制数据（明文）。

6.2 AES 密钥

输入用于 AES 加密与解密的核心密钥。

注意：正式环境不要使用简单字符，可混合大小写、数字、符号。

6.3 加密文件后缀名

所有加密数据文件将使用指定后缀，例如：

  • .fink
  • .dat
  • .bytes

您可自定义后缀名以提高混淆程度。

7 环境配置

unity

环境配置用于控制框架的运行方式，包括 VR / 输入系统 / URP 渲染管线的全局开关。

本界面不推荐做任何修改，除非您确认自己有明确的需求，否则后果自负。

7.1 XR 设置

强制关闭 XR

是否强制关闭 XR（比自动检测优先级更高）。若为 true，则即使已安装 XRI 也会禁用 XR 相关系统。若为 false，则按自动检测结果处理。

7.2 输入系统设置

强制关闭新输入系统（Input System）

是否强制关闭 新输入系统（比自动检测优先级更高）。若为 true，则即使已安装 Input System 也会禁用 Input System 相关系统。若为 false，则按自动检测结果处理。

7.3 渲染管线设置

强制关闭 URP

是否强制关闭 URP（比自动检测优先级更高）。若为 true，则即使已安装 URP 也会禁用 URP 相关系统。若为 false，则按自动检测结果处理。

7.4 构建设置

启用 构建前扫描 editor/ 资源

若开启，则在 Build 时扫描项目是否误将 editor/ 资源参与构建，避免构建失败或误用编辑器资源加载时打包。

推荐：保持开启。

8 UI 配置

unity

用于配置框架 UI 系统的渲染方式。

8.1 UI 渲染模式

模式说明
ScreenSpace普通 2D UI（绝大多数 Unity 项目使用）
WorldSpace3D UI，适用于 VR 或需要放置在 3D 世界中的界面
Auto（推荐）自动判断是否为 VR 项目：VR → WorldSpace；非 VR → ScreenSpace

**建议：**绝大多数项目使用 Auto 即可。

9 资源后端配置

unity

资源后端配置用于管理构建型资源系统，即需要在构建阶段提前生成资源数据、并在运行时进行初始化加载的资源方案。

该配置 不是必须项。
仅当项目需要使用 AssetBundle、Addressables 或自定义资源系统 时才需要进行配置。

若项目仅使用以下即时型加载方式：

  • Resources
  • file://
  • http / https

则可保持默认配置，无需启用资源后端。

9.1 资源后端类型

用于指定当前项目所使用的构建型资源后端方案。

类型说明
None不启用任何构建型资源后端
AssetBundle使用 AssetBundle 作为资源后端（不推荐新项目）
Addressables（推荐）使用 Unity Addressables 作为资源后端
Custom使用自定义资源后端（如 YooAsset / 自研系统）

9.2 None（未启用）

  • 当前项目不使用任何构建型资源系统
  • 资源仅通过以下 Provider 加载：
    • ResourcesProvider
    • FileProvider
    • WebProvider
  • 不需要构建资源包
  • 不存在初始化流程

适用于：

  • 小型项目
  • 无热更新需求
  • 原型验证阶段

9.3 AssetBundle 后端

使用 AssetBundle 作为构建型资源后端。

⚠ 不推荐新项目使用
AssetBundle 为 Unity 旧资源方案，维护成本高，已逐步被 Addressables 替代。

特点说明

  • 需要在构建阶段提前生成 AB 包
  • 运行时需要初始化 AB 后端
  • 支持：
    • 依赖关系加载
    • 内置包 + 热更包路径
  • 不包含：
    • 下载
    • 版本管理
    • 校验
    • 差分更新

框架 不提供 AssetBundle 打包工具，
仅负责运行时加载与引用管理。

官方打包工具

如需使用 AssetBundle，可使用 Unity 官方提供的 AB 打包工具：https://github.com/Unity-Technologies/AssetBundles-Browser

该工具仅用于 编辑器打包阶段，不属于运行时系统。

使用建议

  • 仅建议用于：
    • 旧项目迁移
    • 已有完整 AB 工作流的项目
  • 新项目请优先选择 Addressables

9.4 Addressables 后端（推荐）

使用 Unity Addressables 作为构建型资源后端。

这是 Unity 官方推荐的现代资源解决方案，
也是框架 默认推荐的生产级资源后端。

特点说明

  • 自动处理资源依赖关系
  • 自动管理资源生命周期
  • 支持远程资源与版本控制
  • 支持同步 / 异步加载
  • 支持真实加载进度
  • 与 Unity Addressables 原生工作流完全一致

同步加载说明

  • 默认 禁止同步加载
  • 若在配置中开启：
    • 内部将使用 WaitForCompletion
    • 可能阻塞主线程
  • 仅建议用于：
    • Editor 环境
    • 初始化阶段

9.5 自定义资源后端（Custom）

用于接入 自定义构建型资源系统。

适用于：

  • YooAsset
  • 完全自研资源系统
  • 其它第三方资源后端方案

说明

  • 框架仅提供：
    • 后端类型枚举
    • 配置入口
    • Provider 接入点
  • 不干预任何具体实现逻辑
  • 需要开发者自行实现：
    • 构建流程
    • 初始化逻辑
    • 加载 Provider

9.6 使用建议

  • 小型 / 无热更项目
    → None
  • 新项目 / 中大型项目
    → Addressables
  • 旧项目迁移 / 特殊需求
    → AssetBundle 或 Custom

一般情况下，不建议同时维护多种构建型资源后端，
请在项目初期尽早确定资源方案。

以上就是 Fink Framework 运行前最核心的四类初始化配置。
确保这些选项正确设置后，框架的运行将更加稳定并符合项目需求。