Package net.fabricmc.loom.configuration.providers.mappings

Class MappingConfiguration

java.lang.Object
net.fabricmc.loom.configuration.providers.mappings.MappingConfiguration
Direct Known Subclasses:
ForgeMigratedMappingConfiguration
public class MappingConfiguration extends Object

  • Field Details

    • LEGACY_INHERITED_TASK_NAME

      public static final String LEGACY_INHERITED_TASK_NAME
      补全继承方法映射的任务名（登记与依赖接线共用同一常量，避免字符串漂移）.
      See Also:

    • mappingsIdentifier

      public final String mappingsIdentifier

    • tinyMappings

      public Path tinyMappings

    • tinyMappingsJar

      public final Path tinyMappingsJar

    • tinyMappingsWithMojang

      public Path tinyMappingsWithMojang

    • tinyMappingsWithSrg

      public Path tinyMappingsWithSrg

    • tinyMappingsWithSrgInherited

      public Path tinyMappingsWithSrgInherited
      legacy Forge（1.12.2）用：补全继承方法映射后的 srg tiny（执行期任务产出）.

    • mixinTinyMappings

      public final Map<String,Path> mixinTinyMappings

    • srgToNamedSrg

      public final Path srgToNamedSrg

  • Constructor Details

    • MappingConfiguration

      protected MappingConfiguration(String mappingsIdentifier, Path mappingsWorkingDir)

  • Method Details

    • create

      public static MappingConfiguration create(org.gradle.api.Project project, ServiceFactory serviceFactory, DependencyInfo dependency, MinecraftProvider minecraftProvider)

    • hasMappingOption

      public boolean hasMappingOption(MappingOption mappingOption)
      Returns 该映射选项是否已登记..

      供环内调用方判断是否需要先补齐：WITH_SRG 只在 ensureMappingOptionsReady(org.gradle.api.Project) / setupPost(org.gradle.api.Project) 中登记， 而 Forge 的 patched jar 生产早于 setupPost。

      Returns:
      该映射选项是否已登记

    • getMappingsPath

      public Path getMappingsPath(MappingOption mappingOption)
      Returns 该映射选项指向的映射文件..

      存在性校验对**执行期产出**的映射放宽：Forge 的迁移后 mappings 由执行期任务产出 （见 ForgeMigratedMappingConfiguration.manipulateMappings），配置期它们必然还不存在， 而调用点（任务的 @InputFile 接线、运行配置里的路径字符串）只需要路径。 这类路径的就绪由任务依赖保证——每个消费任务都必须经 ForgeMigratedMappingConfiguration.addMappingsProducerDependency 声明依赖， 否则 Gradle 会在执行期以「输入文件不存在」失败（而不是静默读到空映射）。

      放宽的只有**迁移产物**这一族；其余选项（原始 mappings、mixin 派生映射）仍按存在性拒绝， 因为那些文件在配置期结束时必定已由本类的 setup/setupPost 落位，缺失说明配置流程本身出了问题。

      Returns:
      该映射选项指向的映射文件

    • isTaskProducedMappings

      protected boolean isTaskProducedMappings(MappingOption mappingOption)
      Returns 该映射选项指向的文件是否由执行期任务产出（配置期允许它尚不存在）..

      覆写者必须用 || 保留基类结果——基类已经覆盖了 legacy Forge 的继承补全映射， 直接返回自己的判断会把它漏掉。

      基类的情形：仅 legacy Forge 的 MappingOption.WITH_SRG_INHERITED 指向 mappings-srg-inherited.tiny，由 generateLegacyInheritedMappings 任务产出， 配置期必然不存在；就绪由 addMappingsProducerDependency(org.gradle.api.Task) 建立的任务依赖保证。 其余（Fabric/Quilt 的原始 mappings、WITH_SRG 的原始 srg tiny、mixin 派生映射） 都在配置期结束时已落位，存在性校验仍然生效。

      Returns:
      该映射选项指向的文件是否由执行期任务产出（配置期允许它尚不存在）

    • mappingsProducerTaskPath

      public @Nullable String mappingsProducerTaskPath()
      Returns 本配置的映射文件的产出任务路径；映射由配置期产出时为 null..

      供消费方把「我的输入就是你的产出」表达成任务依赖。返回任务**路径**而不是任务实例： 产出方可能由另一份 Loom classloader 配置（约定插件/included build 各自带一份 Loom）， 把对方的任务实例交过来会在使用处抛 ClassCastException。

      Returns:
      本配置的映射文件的产出任务路径；映射由配置期产出时为 null

    • addMappingsProducerDependency

      public void addMappingsProducerDependency(org.gradle.api.Task task)
      把「本任务以本配置的映射文件为输入」表达成任务依赖；映射由配置期产出时什么也不做.

      映射文件在投影后只在执行期落位，而它的消费者遍布各个任务（重映射、处理链、mod 重映射、 srg→named、运行配置……）。任何一处漏接都会让任务在产物落位前开跑，随后以 「@InputFile 不存在」失败。

    • getSrgNamedTaskPath

      public @Nullable String getSrgNamedTaskPath()
      Returns srg→named 产物的产出任务路径；未投影（整批回退配置期）时为 null..

      供消费方把「我的输入就是你的产出」表达成任务依赖。返回值是任务**路径**而不是任务实例：产出方 可能由另一份 Loom classloader 配置（约定插件/included build 各自带一份 Loom），把对方的任务实例 交给本 classloader 的任务会在使用处抛 ClassCastException。

      Returns:
      srg→named 产物的产出任务路径；未投影（整批回退配置期）时为 null

    • getMappingsServiceOptions

      public org.gradle.api.provider.Provider<TinyMappingsService.Options> getMappingsServiceOptions(org.gradle.api.Project project)

    • getMappingsServiceOptions

      public org.gradle.api.provider.Provider<TinyMappingsService.Options> getMappingsServiceOptions(org.gradle.api.Project project, MappingOption mappingOption)

    • getMappingsService

      public TinyMappingsService getMappingsService(org.gradle.api.Project project, ServiceFactory serviceFactory)

    • getMappingsService

      public TinyMappingsService getMappingsService(org.gradle.api.Project project, ServiceFactory serviceFactory, MappingOption mappingOption)

    • ensureMappingOptionsReady

      public void ensureMappingOptionsReady(org.gradle.api.Project project) throws IOException
      确保映射选项已登记、且 WITH_SRG 指向的合并产物已落位.

      幂等，可重复调用。

      为什么需要它：Forge 车道的 MinecraftPatchedProvider#provide() 在 access transform 阶段会经 getMappingTree 请求 MappingOption.forPlatform(net.fabricmc.loom.api.LoomGradleExtensionAPI) 给出的选项（Forge 恒为 WITH_SRG）。 而 WITH_SRG 原本只在 setupPost(org.gradle.api.Project) 里登记，且 setupPost 自身的 manipulateMappings 又会回调 provide()——二者构成环： provide() 需要 WITH_SRG，WITH_SRG 又要等 provide()。 故本方法把「登记选项 + 合并共享 mappings」从 setupPost 中拆出，供迁回环内的 调用方按需先补齐。

      本方法不触碰 patched 中间产物，因此可在环内安全调用。

      该缺陷只在冷缓存下暴露：patched 中间产物已存在时 provide() 走 isReusableJar 快路径直接复用、不进入 access transform，故本机预热过缓存后长期不可见。

      Throws:
      IOException

    • setupPost

      public void setupPost(org.gradle.api.Project project) throws IOException
      Throws:
      IOException

    • applyToProject

      public void applyToProject(org.gradle.api.Project project, DependencyInfo dependency) throws IOException
      Throws:
      IOException

    • writeSrgNamedMappings

      public static void writeSrgNamedMappings(Path source, Path target) throws IOException
      把 srg → named 的映射整份写成 SRG 文本.

      两条路径共用这一份实现：读写方式、命名空间切换与目标命名空间必须逐字一致，否则同一件产物在 「投影」与「回退」下会不一样。本流水线的其余环节（合并/拆分/重映射）同样按「同一份实现被两条路径 共用」处置。

      Parameters:
      source - 输入的 tiny 映射（srg 命名空间的映射树）
      target - 输出路径；必须是**尚不存在**的路径（调用方负责原子发布，见 AtomicFiles）
      Throws:
      IOException

    • writeSrgNamedMappings

      public static void writeSrgNamedMappings(net.fabricmc.mappingio.tree.MappingTree mappingTree, Path target) throws IOException
      把 srg → named 的映射整份写成 SRG 文本.

      与 writeSrgNamedMappings(Path, Path) 的差别只有「映射树从哪来」：执行期路径直接读 MappingOption.WITH_SRG 指向的文件，配置期回退路径读 TinyMappingsService 的树 （同一份文件、同一个读法）。写法本身共用，避免两套转换逻辑产出不等价的 srg 文本。

      Parameters:
      mappingTree - srg 命名空间的映射树
      target - 输出路径；必须是**尚不存在**的路径（调用方负责原子发布，见 AtomicFiles）
      Throws:
      IOException

    • getRawSrgFile

      public static Path getRawSrgFile(org.gradle.api.Project project) throws IOException
      Throws:
      IOException

    • getMojmapSrgFileIfPossible

      public static Path getMojmapSrgFileIfPossible(org.gradle.api.Project project)

    • manipulateMappings

      protected void manipulateMappings(org.gradle.api.Project project, Path mappingsJar) throws IOException
      Throws:
      IOException

    • extractMappings

      public static void extractMappings(Path jar, Path extractTo) throws IOException
      Throws:
      IOException

    • extractMappings

      public static void extractMappings(FileSystem jar, Path extractTo) throws IOException
      Throws:
      IOException

    • isReusableMappingsText

      public static boolean isReusableMappingsText(Path mappingsFile)
      Returns 该映射文本产物是否可作为输入复用..

      本类的多件共享产物——intermediary-v2.tiny、mappings-mojang.tiny、 mappings-srg.tiny、mappings-srg-named.srg 与 mixin 映射——都是纯文本映射，不是 jar， 故一律不适用 JarReusability.isReusable(Path) 的 zip 口径： 拿文本去开 zipfs 必然失败，会把正常产物永久判为不可用。它们的内容判据等价地取「存在且非空」：

      • 正常产物恒非空——.tiny 至少含映射头，.srg 由 MappingWriter 经 java.io.Writer 逐行写出（SRG 与 tiny 同为文本格式，不是 zip 也不是压缩流）， 二者都必然写出内容，故这条不会把正常产物拖进「每次构建都重建」；
      • 能拦下「先删后写」被中断、或旧版本 loom 就地重建时留下的 0 字节残骸。这类残骸正是本仓库 实测过的形态，而被复用后会一路传到最终产物：下游 MappingReader 读到空映射， 或 getReplacedTarget(net.fabricmc.loom.LoomGradleExtension, java.lang.String) 在改写首行时对空行表取下标而抛异常。

      刻意不做逐行解析、首尾行或末尾换行等更严的校验：该判定位于每次构建的无锁快路径上， 全量解析一份 stitch 产物是秒级开销，收益却只覆盖「截断到非 0 长度」这一小类残骸。

      Parameters:
      mappingsFile - 待判定的映射文本产物路径
      Returns:
      该映射文本产物是否可作为输入复用

    • mappingsWorkingDir

      public Path mappingsWorkingDir()

    • createMappingsIdentifier

      protected static String createMappingsIdentifier(String mappingsName, String version, String classifier, String minecraftVersion)

    • createForgeMappingsIdentifier

      protected static String createForgeMappingsIdentifier(LoomGradleExtension extension, String mappingsName, String version, String classifier, String minecraftVersion)

    • mappingsIdentifier

      public String mappingsIdentifier()

    • getUnpickDefinitionsFile

      public File getUnpickDefinitionsFile()

    • hasUnpickDefinitions

      public boolean hasUnpickDefinitions()

    • getAnnotationsData

      public List<AnnotationsData> getAnnotationsData()

    • getUnpickMetadata

      public UnpickMetadata getUnpickMetadata()

    • getSignatureFixes

      public @Nullable Map<String,String> getSignatureFixes()

    • getReplacedTarget

      public Path getReplacedTarget(LoomGradleExtension loom, String namespace)
      取得 Mixin refmap 重映射所需的映射文件.

      intermediary 命名空间直接返回平台映射文件（见 getPlatformMappingFile(net.fabricmc.loom.LoomGradleExtension)）， 其余命名空间返回一份由它派生的、改写过首行的 mappings-mixin-*.tiny（见 writeReplacedTarget(net.fabricmc.loom.LoomGradleExtension, java.lang.String, java.nio.file.Path)）。 两条路都以平台映射文件为输入，故这里先按共享产物的文本判据（见 isReusableMappingsText(Path)） 确认它可用：

      • 直接返回的分支原先没有任何就绪判定，0 字节残骸会被原样交给 Mixin AP， 让 refmap 静默地按空映射生成（直到运行时才以「找不到映射」的形式炸开）；
      • 派生分支读取该文件后立刻取首行（lines.get(0)），空行表会抛出无从诊断的 IndexOutOfBoundsException。

      这里只做「不可用即报错」，不尝试就地重建：平台映射文件由 mappings 阶段 （setup / setupPost）产出，本方法既拿不到 Project 也拿不到 ServiceFactory， 无法重跑那条流水线；而唯一的调用方（Mixin AP 的参数装配）必然在 mappings 阶段之后执行， 正常构建里该文件恒非空，故这条判定不会误报，只会在确有残骸时把静默错误换成可诊断的失败。

      Parameters:
      loom - 当前项目的 loom 扩展
      namespace - refmap 的目标命名空间

    • getPlatformMappingFile

      public Path getPlatformMappingFile(LoomGradleExtension extension)
      The mapping file that is specific to the platform settings. It contains SRG (Forge/common) or Mojang mappings (NeoForge) as needed.
      Returns:
      the platform mapping file path