Archipelago.MultiClient.Net.Analyzers 1.3.0

Archipelago.MultiClient.Net.Analyzers

Source analyzers, fixes, and code generation for the Archipelago.MultiClient.Net library.

Analyzers and Diagnostics

MULTICLIENT001 - DataStorageElement assigned outside of DataStorageHelper

This warning is intended to prevent bugs which may be caused by misuse of DataStorageHelper. The Archipelago network protocol allows batching several data storage operations in an atomic fashion. In order to support this, DataStorageHelper only sends a packet to the server when a DataStorageElement, containing the batched operations, is re-assigned back to the DataStorageHelper. This means that storing a DataStorageElement into a variable can cause undesirable side effects on the element, as well as prevent it from being sent to the server at all. Instead, it is recommended to use a compound assignment operator to apply edits directly to the DataStorageHelper.

This analyzer also offers a corresponding fix action "Make DataStorage access inline" on variable declarations, which will remove the offending declaration and inline it at all usage sites.

Incorrect Code:

// MULTICLIENT001
DataStorageElement elem = session.DataStorage[Scope.Slot, "MyData"];
elem.Initialize(0);
// This will never make it to the server
elem += 2;

Fixed Code:

session.DataStorage[Scope.Slot, "MyData"].Initialize(0);
// This will make it to the server
session.DataStorage[Scope.Slot, "MyData"] += 2;

MULTICLIENT002 - Use HasFlag when comparing ItemFlags

This warning is intended to prevent bugs when comparing ItemFlags. Because item classification is a flag, an item might have multiple flag values set, such as ItemFlags.Advancement | ItemFlags.Trap. In such scenarios, a comparison like item.Flags == ItemFlags.Advancement does not capture the programmer's intent ("is this item a progression item"). Instead, HasFlag should be used to perform the comparison. ItemFlags.Filler is exempt from this rule because it has the value 0 and HasFlag(0) always returns true.

This analyzer also offers a corresponding fix action "Use HasFlag" on offending comparisons that contain a constant on exactly one side of the comparison. These comparisons will be replaced with a matching HasFlag check.

Incorrect Code:

// MULTICLIENT002
return item.Flags == ItemFlags.Advancement;

Fixed Code:

return item.Flags.HasFlag(ItemFlags.Advancement);

Source Generators

Data Storage Properties

Due to the verbosity of DataStorageHelper's API, it is commonly desirable to assign a DataStorageElement to a variable for repeated access. Unfortunately, this does not work for most use cases, and there is an analyzer to prevent misuse of the API. This package offers a source generator to create a thin wrapper around the data storage API which is also considered an acceptable use by the MULTICLIENT001 analyzer. Note in the example below that you must have a session defined in a scope that is available to members of the containing class - again, this is only a thin wrapper so you have bring your own session.

Example Usage:

partial class MyClass
{
	private ArchipelagoSession session;

	[DataStorageProperty(nameof(session), Scope.Slot, "MyScopedData")]
	private readonly DataStorageElement _myScopedData;

	[DataStorageProperty(nameof(session), "MyGlobalData")]
	private readonly DataStorageElement _myGlobalData;

	public void DoStuff()
	{
		MyScopedData.Initialize(0);
		MyGlobalData += 2;
	}
}