Table of Contents

Class TuningArchiveFile

Namespace
LlamaLogic.TuningArchive
Assembly
LlamaLogic.TuningArchive.dll

Represents an archive of The Sims 4's tuning across versions of the game, stored in a SQLite database file (🔒)

public sealed class TuningArchiveFile : IDisposable
Inheritance
TuningArchiveFile
Implements
Inherited Members

Remarks

Each TuningArchiveSnapshot records the tuning, SimData and strings of a version of the game, as captured from an installation or imported from extracted files. Content is stored once however many snapshots contain it, and each resource's history is kept as ranges of snapshots, so a snapshot adds only what changed.

An archive's members are safe to use from multiple threads. Operations that change the archive are serialized.

An application that only reads an archive another application maintains should open it with OpenReadOnly(string), which never changes the file, rather than Open(string), which upgrades the file to this library's version.

Properties

IsReadOnly

Gets whether the archive was opened for reading only (see OpenReadOnly(string))

public bool IsReadOnly { get; }

Property Value

bool

Path

Gets the path of the archive's database file

public string Path { get; }

Property Value

string

VoiceCodes

Gets the codes of the voices for which the game keeps versions of an audio configuration that tuning names without a voice, in the order the archive lists the versions (see GetVoiceVersionInstance(ulong, string))

public static IReadOnlyList<string> VoiceCodes { get; }

Property Value

IReadOnlyList<string>

Remarks

f codes are female voices, m codes male voices and c codes child voices; the game has no versions for fb or md.

Methods

Analyze(TuningArchiveSnapshot, TuningArchiveEntry)

Analyzes the specified tuning entry with the tuning descriptions best suited to the specified snapshot, or returns null if the archive has no tuning descriptions

public TuningAnalysis? Analyze(TuningArchiveSnapshot snapshot, TuningArchiveEntry entry)

Parameters

snapshot TuningArchiveSnapshot
entry TuningArchiveEntry

Returns

TuningAnalysis

CaptureAsync(GameInstallation, TuningArchiveCaptureOptions?, IProgress<TuningArchiveProgress>?, CancellationToken)

Captures a snapshot of the tuning, SimData, animation state machines, strings and media of the specified installation (💤)

public Task<TuningArchiveCaptureResult> CaptureAsync(GameInstallation installation, TuningArchiveCaptureOptions? options = null, IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

installation GameInstallation
options TuningArchiveCaptureOptions
progress IProgress<TuningArchiveProgress>
cancellationToken CancellationToken

Returns

Task<TuningArchiveCaptureResult>

Remarks

Media are the images, sounds and videos to which the captured tuning and SimData refer (with the audio the sounds use), taken from the client packages of the packs with the same rules as tuning; which kinds are captured is up to the options. Strings are merged from every string table of every pack the way the game merges them: a string in a package of higher priority replaces the same string in a package of lower priority (packages of the same priority in pack order, the base game first), so a pack's Delta strings add to and correct its installed strings rather than replacing them. Within a pack, tuning, SimData and animation state machines are taken from the pack's Delta packages before its installed packages, because the Delta folder patches the installed one: its resources replace theirs and its delete records retire theirs, whatever priorities the two folders' configurations assign. The game does not load the patches of packs that are not installed, so their tuning is not captured; only the names of the tunings they patch are recorded (see GetUninstalledTunings(TuningArchiveSnapshot)), so that what refers to them can still be explained.

Exceptions

InvalidOperationException

No game version was specified and the installation's version could not be found

NotSupportedException

The archive was opened for reading only

Compare(TuningArchiveSnapshot, TuningArchiveSnapshot, TuningArchiveResourceKind, bool)

Gets the resources of the specified kind that differ between the older and newer snapshots, and, if includeUnchanged is true, those that do not (as Unchanged)

public IReadOnlyList<TuningArchiveChange> Compare(TuningArchiveSnapshot older, TuningArchiveSnapshot newer, TuningArchiveResourceKind kind = TuningArchiveResourceKind.Tuning, bool includeUnchanged = false)

Parameters

older TuningArchiveSnapshot
newer TuningArchiveSnapshot
kind TuningArchiveResourceKind
includeUnchanged bool

Returns

IReadOnlyList<TuningArchiveChange>

CompareStrings(TuningArchiveSnapshot, TuningArchiveSnapshot, bool)

Gets the strings that differ between the older and newer snapshots, and, if includeUnchanged is true, those that do not (as Unchanged), in the newer snapshot's locale

public IReadOnlyList<TuningArchiveStringChange> CompareStrings(TuningArchiveSnapshot older, TuningArchiveSnapshot newer, bool includeUnchanged = false)

Parameters

older TuningArchiveSnapshot
newer TuningArchiveSnapshot
includeUnchanged bool

Returns

IReadOnlyList<TuningArchiveStringChange>

Remarks

A string whose text is the same in both snapshots is reported as Moved only when both snapshots were captured from the game, because an extracted strings file does not say which pack each string comes from.

DeleteSnapshotAsync(TuningArchiveSnapshot, CancellationToken)

Deletes the specified snapshot and any content no other snapshot shares (💤)

public Task DeleteSnapshotAsync(TuningArchiveSnapshot snapshot, CancellationToken cancellationToken = default)

Parameters

snapshot TuningArchiveSnapshot
cancellationToken CancellationToken

Returns

Task

Exceptions

NotSupportedException

The archive was opened for reading only

DeleteTuningDescriptionsAsync(TuningArchiveDescriptions, CancellationToken)

Deletes the specified set of tuning descriptions and the references indexed with it (💤)

public Task DeleteTuningDescriptionsAsync(TuningArchiveDescriptions descriptions, CancellationToken cancellationToken = default)

Parameters

descriptions TuningArchiveDescriptions
cancellationToken CancellationToken

Returns

Task

Exceptions

NotSupportedException

The archive was opened for reading only

Dispose()

Releases the archive's resources

public void Dispose()

ExportAsync(TuningArchiveSnapshot, string, TuningArchiveExportOptions?, IProgress<TuningArchiveProgress>?, CancellationToken)

Exports the tuning of the specified snapshot (and, optionally, its animation state machines and SimData) as files in the specified folder, laid out and named the way Scumbumbo's XML Extractor extracts the game's tuning (💤)

public Task<TuningArchiveExportResult> ExportAsync(TuningArchiveSnapshot snapshot, string folder, TuningArchiveExportOptions? options = null, IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

snapshot TuningArchiveSnapshot
folder string
options TuningArchiveExportOptions
progress IProgress<TuningArchiveProgress>
cancellationToken CancellationToken

Returns

Task<TuningArchiveExportResult>

Remarks

Each resource is written to a folder for its pack (such as EP01) and, in it, a folder for its tuning type (such as buff) or AsmJazz, as indented UTF-8 XML with a byte order mark and CRLF line endings. SimData is written beside the tuning with its instance, so that both can be chosen together for Sims 4 Studio's batch import, or to a SimData folder in its pack's folder if there is no such tuning. The group in file names is the pack's identifier, as XML Extractor writes it: taken from the snapshot's game scripts when it has them, otherwise from the pack stamp of the pack's SimData, otherwise from XML Extractor's own table of packs.

A tuning that more than one pack contains is written once, to the folder of the pack the snapshot attributes it to; XML Extractor writes it to the folder of each pack. The archive does not keep the order of the attributes the game ships, so elements' attributes are in canonical order (see TuningXml), with the n and t attributes ordered as AttributeOrder specifies. References to tuning of packs that were not installed are commented with the names the packs' patches give it, as XML Extractor comments them (see GetUninstalledTunings(TuningArchiveSnapshot)), and those names are in the reference files, but the tuning itself is not exported.

FindTuningDescriptions(TuningArchiveSnapshot)

Gets the set of tuning descriptions best suited to the specified snapshot: the one for its game version, otherwise the nearest earlier one, otherwise the nearest later one

public TuningArchiveDescriptions? FindTuningDescriptions(TuningArchiveSnapshot snapshot)

Parameters

snapshot TuningArchiveSnapshot

Returns

TuningArchiveDescriptions

FindTuningDescriptions(TuningArchiveSnapshot, bool)

Gets the set of tuning descriptions for the game version of the specified snapshot: when exactGameVersion is true, only the one for that game version (or null if the archive has none), otherwise the one best suited to it (see FindTuningDescriptions(TuningArchiveSnapshot))

public TuningArchiveDescriptions? FindTuningDescriptions(TuningArchiveSnapshot snapshot, bool exactGameVersion)

Parameters

snapshot TuningArchiveSnapshot
exactGameVersion bool

Returns

TuningArchiveDescriptions

GetBrokenMediaReferences(TuningArchiveSnapshot)

Gets the references in the specified snapshot to media it captured that are not in it

public IReadOnlyList<TuningArchiveReference> GetBrokenMediaReferences(TuningArchiveSnapshot snapshot)

Parameters

snapshot TuningArchiveSnapshot

Returns

IReadOnlyList<TuningArchiveReference>

Remarks

Only references to kinds of media the snapshot captured are considered (see HasKind(TuningArchiveSnapshot, TuningArchiveResourceKind)), and only tunings whose references have been indexed (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)). A reference to an audio configuration that the snapshot has only voices' versions of is not broken (see GetVoiceVersionInstance(ulong, string)).

GetBrokenReferences(TuningArchiveSnapshot)

Gets the references in the specified snapshot to tunings that are not in it

public IReadOnlyList<TuningArchiveReference> GetBrokenReferences(TuningArchiveSnapshot snapshot)

Parameters

snapshot TuningArchiveSnapshot

Returns

IReadOnlyList<TuningArchiveReference>

Remarks

Only references to tuning types the archive has seen are considered, and only tunings whose references have been indexed (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)).

GetContent(TuningArchiveEntry)

Gets the content of the specified entry as the archive stores it

public byte[] GetContent(TuningArchiveEntry entry)

Parameters

entry TuningArchiveEntry

Returns

byte[]

Remarks

Media (see Image, Sound and Video) are stored as the game stores them; other kinds are stored as UTF-8 text (see GetText(TuningArchiveEntry)).

GetEntries(TuningArchiveSnapshot, TuningArchiveResourceKind)

Gets the resources of the specified kind in the specified snapshot

public IReadOnlyList<TuningArchiveEntry> GetEntries(TuningArchiveSnapshot snapshot, TuningArchiveResourceKind kind = TuningArchiveResourceKind.Tuning)

Parameters

snapshot TuningArchiveSnapshot
kind TuningArchiveResourceKind

Returns

IReadOnlyList<TuningArchiveEntry>

GetEntriesByInstance(TuningArchiveSnapshot, TuningArchiveResourceKind, ulong)

Gets the resources of the specified kind with the specified instance in the specified snapshot, whatever their type

public IReadOnlyList<TuningArchiveEntry> GetEntriesByInstance(TuningArchiveSnapshot snapshot, TuningArchiveResourceKind kind, ulong instance)

Parameters

snapshot TuningArchiveSnapshot
kind TuningArchiveResourceKind
instance ulong

Returns

IReadOnlyList<TuningArchiveEntry>

GetEntry(TuningArchiveSnapshot, TuningArchiveResourceKind, ResourceType, ulong, uint?)

Gets the resource of the specified kind, type and instance in the specified snapshot, if it is there

public TuningArchiveEntry? GetEntry(TuningArchiveSnapshot snapshot, TuningArchiveResourceKind kind, ResourceType type, ulong instance, uint? group = null)

Parameters

snapshot TuningArchiveSnapshot
kind TuningArchiveResourceKind
type ResourceType
instance ulong
group uint?

Returns

TuningArchiveEntry

Remarks

When group is null, the resource with the lowest group is returned.

GetHistory(TuningArchiveEntry)

Gets the history of the resource of the specified entry: each version it has had and the snapshots containing it

public IReadOnlyList<TuningArchiveHistoryItem> GetHistory(TuningArchiveEntry entry)

Parameters

entry TuningArchiveEntry

Returns

IReadOnlyList<TuningArchiveHistoryItem>

GetMediaEntries(TuningArchiveSnapshot, ResourceKey)

Gets the media in the specified snapshot to which tuning or SimData refers with the specified reference: the medium GetMediaEntry(TuningArchiveSnapshot, ResourceKey) finds, or, for a reference to an audio configuration that has none of its own, the versions of it for each voice the snapshot contains, in the order of VoiceCodes

public IReadOnlyList<TuningArchiveEntry> GetMediaEntries(TuningArchiveSnapshot snapshot, ResourceKey reference)

Parameters

snapshot TuningArchiveSnapshot
reference ResourceKey

Returns

IReadOnlyList<TuningArchiveEntry>

GetMediaEntry(TuningArchiveSnapshot, ResourceKey)

Gets the medium in the specified snapshot to which tuning or SimData refers with the specified reference, or null if the snapshot does not contain it

public TuningArchiveEntry? GetMediaEntry(TuningArchiveSnapshot snapshot, ResourceKey reference)

Parameters

snapshot TuningArchiveSnapshot
reference ResourceKey

Returns

TuningArchiveEntry

Remarks

References are resolved as the game resolves them (see GetMediaKind(ResourceType)); a reference to an audio configuration resolves to the configuration rather than to the audio it uses.

GetMediaKind(ResourceType)

Gets the kind of media to which tuning or SimData refers with a resource key of the specified type, or null if the type is not one of media

public static TuningArchiveResourceKind? GetMediaKind(ResourceType type)

Parameters

type ResourceType

Returns

TuningArchiveResourceKind?

Remarks

Tuning refers to images with PNGImage and PNGImage2 keys, which the game resolves to the DSTImage with the same instance, and to sounds with AudioConfigurationReference keys, which it resolves to the AudioConfiguration with the same instance, or, when there is none, to the versions of it for each voice (see GetVoiceVersionInstance(ulong, string)).

GetMediaReferrers(TuningArchiveSnapshot, TuningArchiveEntry)

Gets the tunings in the specified snapshot that refer to the medium in the specified entry

public IReadOnlyList<TuningArchiveReference> GetMediaReferrers(TuningArchiveSnapshot snapshot, TuningArchiveEntry entry)

Parameters

snapshot TuningArchiveSnapshot
entry TuningArchiveEntry

Returns

IReadOnlyList<TuningArchiveReference>

Remarks

References with any of the resource types tuning uses for the medium are found (for an image, PNGImage, PNGImage2 and DSTImage), and, for a voice's version of an audio configuration, references to the configuration it is a version of (see GetVoiceVersionSource(TuningArchiveSnapshot, TuningArchiveEntry)). Only tunings whose references have been indexed (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)) are found.

GetMediaResourceTypes(ResourceType)

Gets the resource types to which the game resolves a reference to media with the specified type, in the order it tries them (see GetMediaKind(ResourceType)), or only the type itself if it is not a type tuning uses for media

public static IReadOnlyList<ResourceType> GetMediaResourceTypes(ResourceType type)

Parameters

type ResourceType

Returns

IReadOnlyList<ResourceType>

GetPythonModule(TuningArchiveSnapshot, string)

Gets the decompiled source of the specified Python module (such as buffs.buff) in the specified snapshot, if the snapshot has the game's scripts

public TuningArchiveEntry? GetPythonModule(TuningArchiveSnapshot snapshot, string module)

Parameters

snapshot TuningArchiveSnapshot
module string

Returns

TuningArchiveEntry

GetPythonModuleInstance(string)

Gets the resource instance under which the archive keeps the Python module at the specified path (relative to the decompiled scripts, with forward slashes, such as buffs/buff.py)

public static ulong GetPythonModuleInstance(string path)

Parameters

path string

Returns

ulong

GetPythonModulePaths(string)

Gets the path of the decompiled source file of the specified Python module (such as buffs.buff), relative to the decompiled scripts

public static IReadOnlyList<string> GetPythonModulePaths(string module)

Parameters

module string

Returns

IReadOnlyList<string>

GetReferenceIndexStatus()

Gets how many tunings have had their references indexed, and how many tunings there are

public (int indexed, int total) GetReferenceIndexStatus()

Returns

(int indexed, int total)

GetReferrers(TuningArchiveSnapshot, ResourceType, ulong)

Gets the tunings in the specified snapshot that refer to the resource with the specified type and instance

public IReadOnlyList<TuningArchiveReference> GetReferrers(TuningArchiveSnapshot snapshot, ResourceType type, ulong instance)

Parameters

snapshot TuningArchiveSnapshot
type ResourceType
instance ulong

Returns

IReadOnlyList<TuningArchiveReference>

Remarks

Tunings refer to other tunings and to non-tuning resources (such as object definitions) by tuning reference, and to animation state machines and media by resource key (see GetMediaReferrers(TuningArchiveSnapshot, TuningArchiveEntry) to find a medium's referrers by any of the types tuning uses for it). Only tunings whose references have been indexed (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)) are found.

GetSnapshots()

Gets the snapshots in the archive, in order of game version (and then of when they were captured)

public IReadOnlyList<TuningArchiveSnapshot> GetSnapshots()

Returns

IReadOnlyList<TuningArchiveSnapshot>

GetSoundSamples(TuningArchiveSnapshot, TuningArchiveEntry)

Gets the audio that the audio configuration in the specified entry uses (its samples, and those of the configurations it inherits from), as the specified snapshot contains them

public IReadOnlyList<TuningArchiveEntry> GetSoundSamples(TuningArchiveSnapshot snapshot, TuningArchiveEntry entry)

Parameters

snapshot TuningArchiveSnapshot
entry TuningArchiveEntry

Returns

IReadOnlyList<TuningArchiveEntry>

GetStringReferrers(TuningArchiveSnapshot, IEnumerable<uint>)

Gets the tunings in the specified snapshot that use any of the strings with the specified keys

public IReadOnlyList<TuningArchiveReference> GetStringReferrers(TuningArchiveSnapshot snapshot, IEnumerable<uint> keys)

Parameters

snapshot TuningArchiveSnapshot
keys IEnumerable<uint>

Returns

IReadOnlyList<TuningArchiveReference>

Remarks

Each reference's TargetType is StringTable and its TargetInstance is the key of the string used; a tuning using several of the strings appears once for each. Only tunings whose references have been indexed (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)) are found.

GetStrings(TuningArchiveSnapshot)

Gets the strings of the specified snapshot, by key, in its Locale

public IReadOnlyDictionary<uint, string> GetStrings(TuningArchiveSnapshot snapshot)

Parameters

snapshot TuningArchiveSnapshot

Returns

IReadOnlyDictionary<uint, string>

GetText(TuningArchiveEntry)

Gets the content of the specified entry, as canonical text (see TuningXml) or Python source

public string GetText(TuningArchiveEntry entry)

Parameters

entry TuningArchiveEntry

Returns

string

GetTuningDescriptionCache(TuningArchiveDescriptions)

Gets the cache the archive keeps for the specified set of tuning descriptions, so that repeated analyses are fast

public TuningDescriptionCache GetTuningDescriptionCache(TuningArchiveDescriptions descriptions)

Parameters

descriptions TuningArchiveDescriptions

Returns

TuningDescriptionCache

GetTuningDescriptions()

Gets the sets of tuning descriptions imported into the archive, in order of game version

public IReadOnlyList<TuningArchiveDescriptions> GetTuningDescriptions()

Returns

IReadOnlyList<TuningArchiveDescriptions>

GetTuningTypeNames()

Gets the names of the tuning types the archive has seen, by resource type

public IReadOnlyDictionary<ResourceType, string> GetTuningTypeNames()

Returns

IReadOnlyDictionary<ResourceType, string>

GetUninstalledTunings(TuningArchiveSnapshot)

Gets the tunings of packs that were not installed when the specified snapshot was captured, known only by name from the packs' patches in the game's Delta folder

public IReadOnlyList<TuningArchiveUninstalledTuning> GetUninstalledTunings(TuningArchiveSnapshot snapshot)

Parameters

snapshot TuningArchiveSnapshot

Returns

IReadOnlyList<TuningArchiveUninstalledTuning>

Remarks

None of them is in the snapshot. Only snapshots captured from an installation have them.

GetVoiceVersionInstance(ulong, string)

Gets the instance of the version for the voice with the specified voiceCode (see VoiceCodes) of the audio configuration that tuning names with the specified instance

public static ulong GetVoiceVersionInstance(ulong instance, string voiceCode)

Parameters

instance ulong
voiceCode string

Returns

ulong

Remarks

Tuning names some sounds sims sing or speak (vocal_clip in recipes, for example) by the FNV-1 64 hash of a file name that has no audio configuration of its own, such as vo_karaoke_solojazz2_tune_67sec. The game has a configuration for each voice instead, hashed from the file name followed by an underscore and the voice's code (vo_karaoke_solojazz2_tune_67sec_fa). FNV-1 has no finalization, so the version's instance is found by continuing the hash from the instance tuning names, without the file name.

GetVoiceVersionSource(TuningArchiveSnapshot, TuningArchiveEntry)

Gets the instance by which tuning names the audio configuration of which the specified entry is a voice's version, with that voice's code, or null if it is not a voice's version (see GetVoiceVersionInstance(ulong, string))

public (ulong instance, string voiceCode)? GetVoiceVersionSource(TuningArchiveSnapshot snapshot, TuningArchiveEntry entry)

Parameters

snapshot TuningArchiveSnapshot
entry TuningArchiveEntry

Returns

(ulong instance, string voiceCode)?

Remarks

A configuration is taken to be a voice's version when tuning in the specified snapshot refers to the configuration it would be a version of (only tunings whose references have been indexed are found; see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)), or another voice's version of that configuration is in the snapshot. Codes that share their first letter differ only in the last character hashed, so working back with the wrong one of them leads to a configuration with versions of its own in the snapshot (this one, and the version for another voice of the same group); of the configurations it could be a version of, the one tuning refers to is preferred, then the one with the most versions in the snapshot.

GetVoicelessInstance(ulong, string)

Gets the instance of the audio configuration whose version for the voice with the specified voiceCode (see VoiceCodes) would have the specified voiceVersionInstance: the inverse of GetVoiceVersionInstance(ulong, string)

public static ulong GetVoicelessInstance(ulong voiceVersionInstance, string voiceCode)

Parameters

voiceVersionInstance ulong
voiceCode string

Returns

ulong

Remarks

Any instance has a voiceless instance for every code; to tell which configuration an entry is really a version of, use GetVoiceVersionSource(TuningArchiveSnapshot, TuningArchiveEntry).

HasKind(TuningArchiveSnapshot, TuningArchiveResourceKind)

Gets whether the specified snapshot contains resources of the specified kind

public bool HasKind(TuningArchiveSnapshot snapshot, TuningArchiveResourceKind kind)

Parameters

snapshot TuningArchiveSnapshot
kind TuningArchiveResourceKind

Returns

bool

ImportFolderAsync(string, string, TuningArchiveImportOptions?, IProgress<TuningArchiveProgress>?, CancellationToken)

Imports a folder of tuning files extracted by another tool (such as Scumbumbo's XML Extractor or Sims 4 Studio) as a snapshot of the specified gameVersion (💤)

public Task<TuningArchiveCaptureResult> ImportFolderAsync(string folder, string gameVersion, TuningArchiveImportOptions? options = null, IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

folder string
gameVersion string
options TuningArchiveImportOptions
progress IProgress<TuningArchiveProgress>
cancellationToken CancellationToken

Returns

Task<TuningArchiveCaptureResult>

Remarks

Every .xml file under the folder whose root is an instance (I) or module (M) tuning element is imported as tuning, every one whose root is SimData as SimData, and every other one whose file name has a resource key of type AnimationStateMachine (as Scumbumbo's XML Extractor names the files in its AsmJazz folders) as an animation state machine. A tuning's type is derived from its i attribute the way the game derives it, falling back to a resource key in its file name, and its group is always 0 (the game identifies tuning by type and instance); comments are discarded. A file is attributed to the pack named by a folder in its path (such as EP01), or to DefaultPack.

A file named Reference - All Strings.txt in the folder, as Scumbumbo's XML Extractor writes it, is imported as the snapshot's strings.

Exceptions

NotSupportedException

The archive was opened for reading only

ImportPythonAsync(TuningArchiveSnapshot, string, IProgress<TuningArchiveProgress>?, CancellationToken)

Imports the game's decompiled Python scripts, as Motherlode writes them, into the specified snapshot, replacing any it already has (💤)

public Task<TuningArchiveCaptureResult> ImportPythonAsync(TuningArchiveSnapshot snapshot, string folder, IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

snapshot TuningArchiveSnapshot
folder string
progress IProgress<TuningArchiveProgress>
cancellationToken CancellationToken

Returns

Task<TuningArchiveCaptureResult>

Remarks

folder is Motherlode's output folder (containing scripts and motherlode-report.json) or its scripts folder. Every .py file under scripts is imported, keyed by its path relative to it; Motherlode's report, if present, is imported with them, so that the functions it could not verify can be shown.

Exceptions

NotSupportedException

The archive was opened for reading only

ImportTuningDescriptionsAsync(string, string?, CancellationToken)

Imports the ZIP archive of tuning descriptions at the specified path, as Maxis distributes them, replacing any set already imported for the same game version (💤)

public Task<TuningArchiveDescriptions> ImportTuningDescriptionsAsync(string path, string? gameVersion = null, CancellationToken cancellationToken = default)

Parameters

path string
gameVersion string
cancellationToken CancellationToken

Returns

Task<TuningArchiveDescriptions>

Remarks

When gameVersion is null, it is taken from the name of the file (such as 1.128.90.1030-TDESC.zip).

Exceptions

InvalidOperationException

No game version was specified and the file's name does not contain one

NotSupportedException

The archive was opened for reading only

IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)

Indexes the references in every tuning that has not yet been indexed with the tuning descriptions best suited to it, returning how many tunings were indexed (💤)

public Task<int> IndexReferencesAsync(IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

progress IProgress<TuningArchiveProgress>
cancellationToken CancellationToken

Returns

Task<int>

Remarks

The tuning descriptions best suited to a tuning are those best suited to the earliest snapshot containing it (see FindTuningDescriptions(TuningArchiveSnapshot)). Indexing is needed after capturing or importing a snapshot, after importing tuning descriptions, and after opening the archive with a version of this library that indexes differently (which discards the old index); tunings already indexed with the right descriptions are skipped.

Exceptions

NotSupportedException

The archive was opened for reading only

Open(string)

Opens the archive at the specified path, creating it if it does not exist (🗑️)

public static TuningArchiveFile Open(string path)

Parameters

path string

Returns

TuningArchiveFile

Remarks

An archive created by an earlier version of this library is upgraded, and its reference index is discarded if an earlier version built it (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)).

Exceptions

InvalidDataException

The file is an archive created by a newer version of this library

OpenReadOnly(string)

Opens the existing archive at the specified path for reading only, without changing the file (🗑️)

public static TuningArchiveFile OpenReadOnly(string path)

Parameters

path string

Returns

TuningArchiveFile

Remarks

The archive can be read while another application has it open with Open(string), and sees what that application writes as it is written. Members that would change the archive throw NotSupportedException.

If the archive's reference index was built by a different version of this library, it is left as it is and treated as empty: members that use it find no references, and GetReferenceIndexStatus() reports no tunings indexed.

Exceptions

FileNotFoundException

There is no file at path

InvalidDataException

The file is not an archive, or is an archive created by a newer version of this library, or by an earlier version and not yet upgraded by opening it with Open(string)

OpenTuningDescriptions(TuningArchiveDescriptions)

Opens the specified set of tuning descriptions; the archive owns the set, so it must not be disposed

public TuningDescriptionSet OpenTuningDescriptions(TuningArchiveDescriptions descriptions)

Parameters

descriptions TuningArchiveDescriptions

Returns

TuningDescriptionSet

UpdateSnapshotAsync(TuningArchiveSnapshot, string?, string?, CancellationToken)

Changes the label and notes of the specified snapshot, returning the updated snapshot (💤)

public Task<TuningArchiveSnapshot> UpdateSnapshotAsync(TuningArchiveSnapshot snapshot, string? label, string? notes, CancellationToken cancellationToken = default)

Parameters

snapshot TuningArchiveSnapshot
label string
notes string
cancellationToken CancellationToken

Returns

Task<TuningArchiveSnapshot>

Exceptions

NotSupportedException

The archive was opened for reading only