GameFramework——FileSystem篇

目录一、快速入门1.1 什么是文件系统模块1.2 基本使用步骤1.2.1 创建文件系统1.2.2 写入文件1.2.3 读取文件1.2.4 删除文件1.2.5 加载已有文件系统二、文件布局2.1 HeaderData文件头2.2 BlockData块数据2.3 StringData文件名数据2.4 文件数据区三、源码分析3.1 核心数据结构3.2 关键方法详解3.2.1 FileSystem.Create3.2.2 FileSystem.Load3.2.3 WriteFile3.2.4 AllocBlock核心分配算法3.2.5 DeleteFile3.2.6 TryCombineFreeBlocks合并空闲块3.3 辅助类说明四、架构一览FileSystem模块架构很清晰但作为小白来说看源码还是有些吃力,这篇是借助AI辅助阅读的,部分细节想想还是觉得挺模糊的。下文如有错误还请大佬们指出。一、快速入门1.1 什么是文件系统模块在 Game Framework 中文件系统模块FileSystem是一个虚拟文件系统。它将多个小文件打包进一个物理文件例如.dat文件提供类似磁盘的文件管理功能。这样做的好处是减少物理文件数量便于分发、管理和加密。支持加密文件名加密。按簇分配空间类似真实文件系统的块管理提高 I/O 效率。1.2 基本使用步骤1.2.1 创建文件系统// 通过文件系统组件或管理器创建 IFileSystem fileSystem fileSystemComponent.CreateFileSystem( fullPath: Application.persistentDataPath /GameData.dat, access: FileSystemAccess.ReadWrite, maxFileCount: 100, maxBlockCount: 200 );fullPath物理文件的完整路径。access访问方式Read、Write、ReadWrite。创建时必须为可写。maxFileCount最多能存储多少个文件。maxBlockCount最多能分配多少个块通常 ≥maxFileCount。1.2.2 写入文件byte[] data Encoding.UTF8.GetBytes(Hello, Game Framework!); bool success fileSystem.WriteFile(hello.txt, data);1.2.3 读取文件byte[] readData fileSystem.ReadFile(hello.txt); string text Encoding.UTF8.GetString(readData);1.2.4 删除文件bool deleted fileSystem.DeleteFile(hello.txt);1.2.5 加载已有文件系统IFileSystem loadedFileSystem fileSystemComponent.LoadFileSystem( fullPath: Application.persistentDataPath /GameData.dat, access: FileSystemAccess.ReadWrite );二、文件布局2.1 HeaderData文件头魔数G,F,F3 字节版本号固定为0加密密钥4 字节随机数最大文件数MaxFileCount最大块数MaxBlockCount当前块数BlockCount2.2 BlockData块数据每个块对应一个文件或空闲空间结构如下StringIndex文件名在StringData数组中的索引-1 表示空闲ClusterIndex起始簇索引簇大小为 4KBLength文件实际占用的字节数按簇对齐后的长度2.3 StringData文件名数据Length文件名长度字节Bytes加密后的文件名最大 255 字节2.4 文件数据区实际存放文件内容按簇4KB组织。每个文件的数据从ClusterIndex * ClusterSize开始连续存放Length字节。三、源码分析3.1 核心数据结构FileSystem类字段类型作用m_FileDatasDictionarystring, int文件名 → 块索引的映射用于快速查找文件m_BlockDatasListBlockData所有块的元数据与物理文件中的 BlockData 数组一一对应m_FreeBlockIndexesGameFrameworkMultiDictionaryint, int空闲块索引列表按块长度分组支持最佳适应分配m_StringDatasSortedDictionaryint, StringData正在使用的文件名索引 → 文件名数据m_FreeStringDatasQueueKeyValuePairint, StringData可复用的文件名数据对象减少 GC3.2 关键方法详解3.2.1FileSystem.Create校验参数初始化HeaderData生成随机加密密钥。调用CalcOffsets计算各区域在物理文件中的偏移。写入头部设置文件长度返回FileSystem实例。3.2.2FileSystem.Load读取头部校验魔数和版本。根据BlockCount循环读取所有BlockData重建m_BlockDatas。遍历每个块若正在使用读取对应的StringData解密得到文件名加入m_FileDatas和m_StringDatas。若空闲将块索引按长度加入m_FreeBlockIndexes。重建空闲字符串索引队列m_FreeStringIndexes。3.2.3WriteFile检查权限、文件名长度。根据文件名判断文件之前是否存在存在则先释放旧块。调用AllocBlock分配新块最佳适应算法必要时扩展文件。写入文件数据到对应簇位置。更新块元数据如果是新文件分配文件名索引AllocString并加密存储如果是覆盖复用旧文件名索引。更新m_FileDatas、m_BlockDatas并持久化块和字符串数据。3.2.4ReadFile检查权限必须是可读模式Read或ReadWrite。获取文件信息通过GetFileInfo得到文件偏移起始簇位置和长度。定位流位置m_Stream.Position fileInfo.Offset。读取数据调用m_Stream.Read(buffer, 0, length)将数据读入缓冲区。根据不同重载 返回实际读取字节数或者实际读取的字节数据。3.2.5AllocBlockBlockData分配算法将请求长度向上取整到簇大小GetUpBoundClusterOffset。从m_FreeBlockIndexes中寻找不小于请求长度的最小空闲块最佳适应。如果找到且长度大于请求则拆分出剩余部分作为新的空闲块加入字典;如果没有找到合适的空闲块则尝试在文件末尾追加新块获取新的块索引GetEmptyBlockIndex。扩展物理文件长度设置新块起始簇索引为当前文件末尾的簇号。返回块索引。3.2.6AllocStringstringData分配算法优先从freeStringData找是否有空闲的stringData,即复用若无则使用当前m_StringDatas的计数作为新索引即递增分配。将传入的文件名字符串转换为字节数组。如果长度超过 255 字节抛出异常文件系统限制。使用头部中的加密密钥m_HeaderData.GetEncryptBytes()对字节数组进行异或加密。将加密后的字节数组拷贝到StringData对象的m_Bytes字段中并设置长度字段。将索引 →StringData的映射添加到m_StringDatas字典中。调用WriteStringData将StringData写入物理文件对应位置。返回StringData索引。3.2.7DeleteFile从m_FileDatas中移除文件名。获取块中的StringIndex释放文件名资源清空StringData加入空闲队列。将块标记为空闲BlockData.Free()并尝试与相邻空闲块合并TryCombineFreeBlocks。更新m_BlockDatas和m_FreeBlockIndexes。3.2.8TryCombineFreeBlocks合并空闲块给定一个空闲块索引检查其前后相邻块是否也是空闲块。如果是则将它们合并成一个更大的空闲块并更新m_FreeBlockIndexes移除原块添加合并后的块。被合并的相邻块会被标记为长度为 0 的“空块”便于后续复用其索引。3.3 辅助类说明FileSystemStream抽象类封装底层文件流操作读、写、定位等。CommonFileSystemStream基于FileStream对FileSystemStream的实现用于普通文件。AndroidFileSystemStream基于AndroidJavaObject对FileSystemStream的实现用于读取 APK 内的 assets只读。FileSystemManager管理多个FileSystem实例按路径区分。FileSystemComponentUnity 组件负责初始化管理器和辅助器。FileSystemHelperBase辅助器基类用于根据路径创建合适的FileSystemStream。四、架构一览