unison.vfs — 虚拟文件系统

unison.vfs 提供统一的文件访问接口，优先从已挂载的 VFS（CPK 加密包）中查找文件，找不到时自动 fallback 到真实文件系统。

使用方式

from unison import vfs

基础函数

这些函数由 <pymodules> 配置从后端模块（如 exio3）映射而来，具体可用性取决于配置。

mount(path, mount_point, *, encryption_key=0)

挂载 CPK 文件到虚拟文件系统。

vfs.mount("Lib.cpk", "Lib/", encryption_key=-231)
vfs.mount("data.cpk", "data/")

参数	类型	说明
path	str	CPK 文件路径
mount_point	str	挂载点，通常以 / 结尾
encryption_key	int	加密密钥，0=不加密，负数=有密钥

find_file(path)

检查文件是否存在于 VFS 中。

if vfs.find_file("Scripts/main.py"):
    print("文件存在")

参数	类型	说明
path	str	虚拟路径
返回	bool	文件是否存在

get_file(path)

从 VFS 读取文件内容（字节）。

data = vfs.get_file("data/config.json")

参数	类型	说明
path	str	虚拟路径
返回	bytes	文件内容

list_dir(directory)

列出 VFS 目录中的文件。

files = vfs.list_dir("Scripts/")

参数	类型	说明
directory	str	虚拟目录路径
返回	list	文件路径列表

get_doc_dir()

获取用户文档目录路径。

doc_dir = vfs.get_doc_dir()

| 返回 | str | 文档目录绝对路径 |

get_real_path(virtual_path)

将虚拟路径转换为真实文件系统路径。

real = vfs.get_real_path("Scripts/main.py")

参数	类型	说明
virtual_path	str	虚拟路径
返回	str	真实文件系统路径

混合 API

以下 API 由引擎自动注册，优先使用 VFS，VFS 不可用时 fallback 到真实文件系统。

file_exists(path)

检查文件是否存在（VFS 优先，找不到则查真实文件系统）。

if vfs.file_exists("data/save.json"):
    print("文件可用")

参数	类型	说明
path	str	文件路径（虚拟或真实）
返回	bool	文件是否存在

read_file_bytes(path)

读取文件为字节（VFS 优先）。

raw = vfs.read_file_bytes("textures/icon.png")

参数	类型	说明
path	str	文件路径
返回	bytes	文件原始字节

read_file_text(path)

读取文件为 UTF-8 文本（VFS 优先）。

code = vfs.read_file_text("Scripts/main.py")

参数	类型	说明
path	str	文件路径
返回	str	UTF-8 文本内容

list_files(directory)

列出目录中的所有文件（VFS 优先）。

all_files = vfs.list_files("data/")

参数	类型	说明
directory	str	目录路径
返回	list[str]	完整路径列表