Table of Contents

Class TuningFolderUpdate

Namespace
LlamaLogic.TuningArchive
Assembly
LlamaLogic.TuningArchive.dll

Finds the overrides of game tuning in every package in a folder and its subfolders, works out what a game version means for each, checks the SimData of the tuning the packages add against the game version's tuning descriptions, and writes updated copies of the packages with the changes that need no judgment from the creator, with a report of everything

public sealed class TuningFolderUpdate
Inheritance
TuningFolderUpdate
Inherited Members

Remarks

The changes that need no judgment are merges without conflicts whose base is not uncertain (see BaseIsUncertain), the SimData changes and fixes the options allow, and, if the options say so, removing overrides that do nothing. Everything else is left as the package has it and marked in the report as needing the creator.

The packages in the folder are never changed, and updated copies are never written inside it, where the game would load them beside the originals.

Properties

DeclaredBase

Gets the game version the creator said the packages were last updated for, if they said

public TuningArchiveSnapshot? DeclaredBase { get; }

Property Value

TuningArchiveSnapshot

Folder

Gets the folder

public string Folder { get; }

Property Value

string

Packages

Gets the packages in the folder that override game tuning, add tuning whose SimData isn't what the tuning descriptions give, or couldn't be read, in order of their paths

public IReadOnlyList<TuningFolderUpdatePackage> Packages { get; }

Property Value

IReadOnlyList<TuningFolderUpdatePackage>

Target

Gets the snapshot of the game version the packages are being updated for

public TuningArchiveSnapshot Target { get; }

Property Value

TuningArchiveSnapshot

Methods

AnalyzeAsync(TuningArchiveFile, TuningArchiveSnapshot, string, TuningSimDataDrafter?, TuningArchiveSnapshot?, IProgress<TuningArchiveProgress>?, CancellationToken)

Finds the overrides of game tuning in every package in the specified folder and its subfolders and works out what the target game version in the specified archive means for each (🏃)

public static Task<TuningFolderUpdate> AnalyzeAsync(TuningArchiveFile archive, TuningArchiveSnapshot target, string folder, TuningSimDataDrafter? simData = null, TuningArchiveSnapshot? declaredBase = null, IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

archive TuningArchiveFile

The archive with the game versions

target TuningArchiveSnapshot

The game version to update the packages for

folder string

The folder

simData TuningSimDataDrafter

A drafter for the target snapshot, to check the packages' SimData against what their overrides need and the SimData of the tuning they add against the tuning descriptions, or null not to

declaredBase TuningArchiveSnapshot

The game version the creator says the packages were last updated for, to use as the base instead of inferring it, or null to infer it

progress IProgress<TuningArchiveProgress>

Receives progress

cancellationToken CancellationToken

The token to monitor for cancellation requests

Returns

Task<TuningFolderUpdate>

GetReport(TuningFolderUpdateOptions, IReadOnlyList<TuningFolderUpdateWrite>?)

Gets a report of every override in the folder and the SimData of the tuning the packages add, as comma-separated values with a header row (see GetReportRows(TuningFolderUpdateOptions, IReadOnlyList<TuningFolderUpdateWrite>?))

public string GetReport(TuningFolderUpdateOptions options, IReadOnlyList<TuningFolderUpdateWrite>? written = null)

Parameters

options TuningFolderUpdateOptions
written IReadOnlyList<TuningFolderUpdateWrite>

Returns

string

GetReportRows(TuningFolderUpdateOptions, IReadOnlyList<TuningFolderUpdateWrite>?)

Gets a row for every override in the folder, for the SimData of every tuning the packages add that isn't what the tuning descriptions give, and for every package that couldn't be read, for the specified options and, if the updated copies were written, what writing them did

public IReadOnlyList<TuningFolderUpdateReportRow> GetReportRows(TuningFolderUpdateOptions options, IReadOnlyList<TuningFolderUpdateWrite>? written = null)

Parameters

options TuningFolderUpdateOptions
written IReadOnlyList<TuningFolderUpdateWrite>

Returns

IReadOnlyList<TuningFolderUpdateReportRow>

GetTuning(TuningPackageUpdate, TuningFolderUpdateOptions)

Gets the tuning the update writes in place of the specified update's overrides with the specified options

public static IReadOnlyDictionary<ResourceKey, string?> GetTuning(TuningPackageUpdate update, TuningFolderUpdateOptions options)

Parameters

update TuningPackageUpdate
options TuningFolderUpdateOptions

Returns

IReadOnlyDictionary<ResourceKey, string>

IsAutomatic(TuningPackageOverride)

Gets whether the update makes the change to the specified item on its own: the merge of a mod's changes without conflicts, whose base is not uncertain

public static bool IsAutomatic(TuningPackageOverride item)

Parameters

item TuningPackageOverride

Returns

bool

NeedsCreator(TuningPackageAddedSimData, TuningFolderUpdateOptions)

Gets whether the specified item needs the creator's judgment after the update makes the fixes the specified options allow

public static bool NeedsCreator(TuningPackageAddedSimData item, TuningFolderUpdateOptions options)

Parameters

item TuningPackageAddedSimData
options TuningFolderUpdateOptions

Returns

bool

NeedsCreator(TuningPackageOverride, TuningFolderUpdateOptions)

Gets whether the specified item needs the creator's judgment after the update makes the changes the specified options allow

public static bool NeedsCreator(TuningPackageOverride item, TuningFolderUpdateOptions options)

Parameters

item TuningPackageOverride
options TuningFolderUpdateOptions

Returns

bool

Remarks

An override whose declared base disagrees always does, even if it looks up to date: when the creator's declared version is wrong for it, it may be undoing the game's changes since the version it was really made from.

WriteAsync(string, TuningFolderUpdateOptions, bool, IProgress<TuningArchiveProgress>?, CancellationToken)

Writes an updated copy of each package the specified options change to the same relative path in the specified outputFolder, skipping any whose path there already has a file, and, unless told not to, the report beside them (🏃)

public Task<TuningFolderUpdateResult> WriteAsync(string outputFolder, TuningFolderUpdateOptions options, bool writeReport = true, IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

outputFolder string

Where to write the updated copies, which must not be in the folder

options TuningFolderUpdateOptions

Which changes to make

writeReport bool

Whether to write the report (see GetReport(TuningFolderUpdateOptions, IReadOnlyList<TuningFolderUpdateWrite>?)) beside the copies, as Update report for the game version, with .csv

progress IProgress<TuningArchiveProgress>

Receives progress

cancellationToken CancellationToken

The token to monitor for cancellation requests

Returns

Task<TuningFolderUpdateResult>

Exceptions

ArgumentException

outputFolder is the folder or in it

WriteReportAsync(string, TuningFolderUpdateOptions, IReadOnlyList<TuningFolderUpdateWrite>?, CancellationToken)

Writes the report (see GetReport(TuningFolderUpdateOptions, IReadOnlyList<TuningFolderUpdateWrite>?)) to the specified path, as UTF-8 with a byte order mark so that Excel reads it as UTF-8 (🏃)

public Task WriteReportAsync(string path, TuningFolderUpdateOptions options, IReadOnlyList<TuningFolderUpdateWrite>? written = null, CancellationToken cancellationToken = default)

Parameters

path string
options TuningFolderUpdateOptions
written IReadOnlyList<TuningFolderUpdateWrite>
cancellationToken CancellationToken

Returns

Task