Scripting API

Scripting API

PackageRegistry

Class in Abyss.Core, from Abyss.Core.

The registry: a folder of packages as their authors made them, every version an archive, acme.physics/1.2.0.abypackage, which a game installs from, Export writes into, and a file sent or downloaded is added to; never changed by a game's edits to its copy.

public sealed class PackageRegistry

Remarks

Where it is is the editor's preference; PackageRegistry.DefaultFolder where it says none, one for each person on the machine.

Constructors

PackageRegistry

public PackageRegistry(string folder)

The registry at folder, made where it is not there yet as anything is put into it.

Parameters

  • folder

Properties

DefaultFolder

public static string DefaultFolder { get; }

Where the registry is where the editor's preferences name nowhere: the person's own local application data, %LOCALAPPDATA%\AbyssEngine\Registry, ~/.local/share/AbyssEngine/Registry.

Folder

public string Folder { get; }

Its folder, whole.

Methods

Revert

public PackageChanges Revert(string id, string home, Action<string> putInTrash)

Puts the game's copy of its package id in home back as the registry has its version: each file changed written as it was, each gone written again, each added taken out, and its hashes kept again. The game's own versions of what that changes or takes out go into the platform's trash first, by putInTrash, so nothing of the person's is lost; what it put back.

Parameters

  • id
  • home
  • putInTrash

Exceptions

  • InvalidOperationException: The game has no such package, or the registry has not its version, or cannot read it.
  • PackageHeldException: A file it would change is held by another program; nothing was done.
  • IOException: The trash would not take the person's versions; nothing was done.

All of it, or nothing: every file it changes or takes out is opened first, alone, so one another program holds is said before anything is done, the person's versions not yet in the trash. A project the engine wrote beside the package's files is none of them, and stays.

ArchiveOf

public string ArchiveOf(string id, string version)

Where the registry keeps a version of a package.

Parameters

  • id
  • version

Packages

public IReadOnlyList<RegisteredPackage> Packages(Action<string>? refused = null)

Every package it has, in order of their ids, each version oldest first; an archive that cannot be read, or is not where its id and version say, is told to refused and left out.

Parameters

  • refused

Find

public RegisteredPackage? Find(string id)

A package the registry has, by its id; null where it has none of it.

Parameters

  • id

Add

public string Add(string archive)

Copies the archive archive into the registry, having checked it is one and its files are as its hashes say; where it is now. One the registry has already, the same file, is where it was.

Parameters

  • archive

Exceptions

  • FormatException: It is not a package's archive, saying why.
  • InvalidOperationException: The registry has another file of that version.

Offer

public (string Archive, bool Written) Offer(string folder)

Puts the package in folder into the registry at the version its manifest gives, as an archive, where the registry has none of it or holds other files at that version: what the editor does with the engine's own packages it carries, which change at one version while the engine is made, as its SDK does. Not what a person's version is put in with, which once made stays as it was made (PackageRegistry.Add).

Parameters

  • folder

Returns Where its archive is, and whether it was written now.

Exceptions

  • InvalidOperationException: Its manifest cannot be read, saying why.

Export

public string Export(string folder, string version)

Writes the package in folder into the registry as version: its manifest given that version, its archive made, and the hashes of what it now is kept beside it as its original's; where the archive is.

Parameters

  • folder
  • version

Exceptions

  • InvalidOperationException: The version is none, or the registry has it already, or the package cannot be written, saying why.

Install

public IReadOnlyList<string> Install(string id, string version, string home)

Installs version of the package id into the game home, as its folder in the game's packages, with every package it needs that the game has not, each the newest version the registry has that its range takes; the ids installed, those needed first. Nothing is installed where any of them cannot be.

Parameters

  • id
  • version
  • home

Exceptions

  • InvalidOperationException: It, or a package it needs, cannot be installed, saying why.

PlanUpdate

public PackageUpdate PlanUpdate(string id, string version, string home)

What changing the game's copy of its package id to version would do: each file compared three ways — what it was installed as, what it is now, what the version has — the version's taken where only it changed a file, and a file both changed a conflict, the person's to settle; with what the version needs and what needs it.

Parameters

  • id
  • version
  • home

Exceptions

  • InvalidOperationException: The game has no such package, or the registry has not the version, or cannot read it.

A copy made here keeps no original, so each file it and the version both have, differing, is a conflict, and each it has alone is the person's.

Update

public UpdateDone Update(string id, string version, string home, IReadOnlySet<string> take, Action<string> putInTrash)

Changes the game's copy of its package id to version: each file of PackageRegistry.PlanUpdate in take written as the version has it, or taken out where it has none — the manifest always — and every other left as it is; the person's versions of those taken over their own changes put in the platform's trash first, by putInTrash; and the version's hashes kept as the copy's original, so what the person kept shows as their change of it.

Parameters

  • id
  • version
  • home
  • take
  • putInTrash

Exceptions

  • InvalidOperationException: As PackageRegistry.PlanUpdate, or the version needs a package the game has not at a version it takes.
  • PackageHeldException: A file it would change is held by another program; nothing was done.
  • IOException: The trash would not take the person's versions; nothing was done.

All of it, or nothing: every file it writes over or takes out is opened alone first, so one another program holds stops it before anything is done.