Infant God

yarn-spinner-project-files

8 min read

纺纱厂项目文件

[！警告] 您不需要考虑其中的大部分内容。如果您在游戏引擎中启动一个项目，然后处理 Yarn 脚本，则可能已经存在一个 Yarn Spinner 项目文件。

一个 .yarnproject file 是一个 JSON 文件，它告诉 Yarn Spinner 要编译哪些 Yarn 脚本、如何查找本地化内容以及其他项目配置选项。

Yarn 项目由 Yarn Spinner VS Code 扩展、游戏引擎（Unity、Godot、Unreal）和命令行工具使用，以了解对话文件如何组合在一起。

创建 Yarn 项目文件

您可以创建一个 .yarnproject 手动文件，或使用游戏引擎的工具：

  • Unity： 打开资产菜单并选择 Yarn Spinner → Yarn Project
  • Godot: 打开项目 → 工具 → YarnSpinner → 创建 Yarn 项目
  • VS Code / 手册： 使用以下内容创建一个新文件 .yarnproject 扩展并添加下面的 JSON 结构

文件格式

一个 .yarnproject file 是一个 JSON 文档，其结构如下：

{
  “项目文件版本”：3，
 "sourceFiles": ["**/*.yarn"],
 },
}

属性参考

项目文件版本

必需。 一个整数，用于标识正在使用的项目文件格式的版本。

  • 使用 3 用于纱线纺纱机 3.x 项目
  • 使用 2 适用于纺纱厂 2.3+ 项目

从 Yarn Spinner 2.x 升级到 3.x 时，您需要将此值从 2 到 3.

"projectFileVersion": 3

源文件

必需。 指定 Yarn 脚本 (.yarn 文件）应包含在该项目中。

图案使用 [全局语法](https://en.wikipedia.org/wiki/Glob_\(programming\)），包括支持：

  • * 匹配除路径分隔符之外的任何字符
  • ** 匹配任何字符，包括路径分隔符（globstar）
  • ? 匹配单个字符
"sourceFiles": ["**/*.yarn"]

常见模式：

图案比赛
**/*.yarn全部 .yarn 项目文件夹和所有子文件夹中的文件
*.yarn全部 .yarn 文件位于同一文件夹中 .yarnproject 仅文件
Dialogue/**/*.yarn全部 .yarn 文件在 Dialogue 文件夹及其子文件夹
../Common.yarn父目录中的特定文件

您可以包含多种模式：

"sourceFiles": [
  "**/*.yarn",
  "../SharedDialogue/*.yarn"
]

如果一个文件匹配多个模式，则只会包含一次。

排除文件

可选。 指定哪些 Yarn 脚本应从编译中排除的文件模式数组，即使它们与中的模式匹配 sourceFiles.

这对于排除备份文件夹、构建输出目录或正在进行的文件非常有用。

"excludeFiles": [
  "**/backup/**",
  "**/~*",
  "WIP_*.yarn"
]

常见排除模式：

图案不包括
**/backup/**名为的文件夹内的任何文件 backup
**/*~/**文件夹结尾为 ~ （Unity 对于忽略文件夹的约定）
**/build/**构建输出目录
**/node_modules/**Node.js 依赖项（如果您的项目使用它们）
Test_*.yarn开头为的文件 Test_

[！信息] 默认是新建的 .yarnproject Unity 中的文件排除任何 .yarn 以以下结尾的文件夹中的文件 ~。这遵循 Unity 忽略某些文件夹的约定。

基础语言

可选。 IETF BCP 47 语言标签 指示您的源 Yarn 脚本所使用的语言。

"baseLanguage": "en"

常用语言标签：

标签语言
en英语
en-AU英语（澳大利亚）
en-GB英语（英国）
en-US英语（美国）
de德语
fr法语
ja日语
zh-Hans中文（简体）

如果未指定，Yarn Spinner 将使用您计算机的当前区域设置。

本土化

可选。 描述在哪里可以找到每种语言的本地化资源的字典。每个键都是一个语言标签，每个值都是一个具有以下属性的对象：

  • strings：包含本地化行文本的文件的路径（通常是 CSV 文件）
  • assets：包含本地化资源（例如画外音音频）的目录路径
"localisation": {
  "en": {
    "assets": "./voiceover/en/"
  },
  "de": {
    "strings": "./localisation/de.csv",
    "assets": "./voiceover/de/"
  },
  "fr": {
    "strings": "./localisation/fr.csv",
    "assets": "./voiceover/fr/"
  }
}

路径是相对于位置的 .yarnproject 文件。

定义

可选。 包含项目使用的命令和函数定义的 JSON 文件的路径。该文件使用 .ysls.json 扩展并遵循 ysls.json 架构.

"definitions": "MyGameCommands.ysls.json"

[！信息] 如果您使用 Yarn Spinner for Unity，系统会自动从 C# 代码中检测命令和函数定义。你只需要一个 .ysls.json 如果您使用不同的游戏引擎或想要提供其他文档，请保存该文件。

编译器选项

可选。 包含 Yarn Spinner 编译器使用的附加设置的对象。这是保留供将来使用的，目前没有定义的选项。

"compilerOptions": {}

完整示例

这是一个完整的例子 .yarnproject 具有多种语言的游戏文件：

{
  "projectFileVersion": 3,
  "sourceFiles": [
    "Dialogue/**/*.yarn",
    "Barks/**/*.yarn"
  ],
  "excludeFiles": [
    "**/backup/**",
    "**/~*",
    "**/*.test.yarn"
  ],
  "baseLanguage": "en",
  "localisation": {
    "en": {
      "assets": "./Audio/Voiceover/en/"
    },
    "de": {
      "strings": "./Localisation/de.csv",
      "assets": "./Audio/Voiceover/de/"
    },
    "fr": {
      "strings": "./Localisation/fr.csv",
      "assets": "./Audio/Voiceover/fr/"
    },
    "ja": {
      "strings": "./Localisation/ja.csv",
      "assets": "./Audio/Voiceover/ja/"
    }
  },
  "definitions": "GameCommands.ysls.json"
}

使用 VS 代码

Yarn Spinner VS Code 扩展会自动检测 .yarnproject 工作区中的文件。当项目文件存在时：

  • 仅匹配文件 sourceFiles 模式（减去 excludeFiles 排除）已编译
  • 错误检查和自动完成使用项目的配置
  • 来自您的命令和功能 definitions 文件出现在自动完成中

如果没有 .yarnproject 文件存在于您的工作区中，VS Code 扩展将处理所有 .yarn 工作区中的文件作为单个隐式项目。

[！信息] VS Code 扩展目前不遵循 VS Code 的 files.exclude 环境。要从 Yarn Spinner 的编译中排除文件，请使用 excludeFiles 您的财产 .yarnproject 文件代替。

故障排除

重复节点错误

如果您看到“多个节点被命名…”错误，则可能有重复的节点 .yarn 正在编译的文件。这可能发生在以下情况：

  • 构建输出或缓存文件夹包含 Yarn 文件的副本
  • 备份文件夹包含旧版本的文件

解决方案： 将重复的位置添加到您的 excludeFiles 大批：

"excludeFiles": [
  "**/build/**",
  "**/backup/**",
  "**/Library/**"
]

找不到文件

如果未检测到您的 Yarn 文件：

  1. 检查您的 sourceFiles 模式是正确的
  2. 验证路径是相对于 .yarnproject 文件位置
  3. 使用 ysc list-sources 命令查看哪些文件与您的模式匹配

Graph View

Backlinks