From 283dfc657a9959de93b8e9ebf3fd0071e714827d Mon Sep 17 00:00:00 2001 From: alwaysintreble Date: Thu, 27 Feb 2025 13:18:16 -0600 Subject: [PATCH 01/17] split up and proofread existing docs --- docfx/datastorage.md | 109 ++++++++++++++ docfx/events.md | 70 +++++++++ docfx/helpers.md | 148 +++++++++++++++++++ docfx/index.md | 341 +++---------------------------------------- docfx/packets.md | 13 ++ 5 files changed, 358 insertions(+), 323 deletions(-) create mode 100644 docfx/datastorage.md create mode 100644 docfx/events.md create mode 100644 docfx/helpers.md create mode 100644 docfx/packets.md diff --git a/docfx/datastorage.md b/docfx/datastorage.md new file mode 100644 index 00000000..0b8626b9 --- /dev/null +++ b/docfx/datastorage.md @@ -0,0 +1,109 @@ +## DataStorage + +DataStorage support is included in the library. You may save values on the archipelago server in order to share them +across other player's sessions or to simply keep track of values outside your game's state. + +The DataStorage provides an interface based on keys and their scope. By assigning a value to a key, that value is stored +on the server and by reading from a key a value is retrieved from the server. +Assigning and reading values from the store can be done using simple assignments `=`: + +* `= session.DataStorage["Key"]`, read value from the data storage synchronously +* `session.DataStorage["Key"] =`, write value to the data storage asynchronously +* Complex objects need to be stored and retrieved in the form of a `JObject`, therefore you must wrap them into a + `JObject.FromObject()` + +The DataStorage also provides methods to retrieve the value of a key asynchronously using `[key].GetAsync`. +To set the initial value of a key without overriding any existing value, the `[key].Initialize` method can be used. +If you're interested in keeping track of when a value of a certain key is changed by any client you can use the +`[key].OnValueChanged` handler to register a callback for when the value gets updated. + +Mathematical operations on values stored on the server are supported using the following operators: + +* `+`, Add right value to left value +* `-`, Subtract right value from left value +* `*`, Multiply left value by right value +* `/`, Divide left value by right value +* `%`, Gets remainder after dividing left value by right value +* `^`, Multiply left value by the power of the right value + +Bitwise operations on values stored on the server are supported using the following operations: + +* `+ Bitwise.Xor(x)`, apply logical exclusive OR to the left value using value x +* `+ Bitwise.Or(x)`, apply logical OR to the left value using value x +* `+ Bitwise.And(x)`, apply logical AND to the left value using value x +* `+ Bitwise.LeftShift(x)`, binary shift the left value to the left by x +* `+ Bitwise.RightShift(x)`, binary shift the left value to the right by x + +Other operations on values stored on the server are supported using the following operations: + +* `+ Operation.Min(x)`, get the lowest value of the left value and x +* `+ Operation.Max(x)`, get the highest value of the left value and x +* `+ Operation.Remove(x)`, when the left value is a list, removes the first element with value x +* `+ Operation.Pop(x)`, when the left value is a list or dictionary, removes the element at index x or key x +* `+ Operation.Update(x)`, when the left value is a list or dictionary, updates the dictionary with the keys/values in x + +Operation specific callbacks are supported, these get called only once with the results of the current operation: + +* `+ Callback.Add((oldValue, newValue) => {});`, calls this method after your operation or chain of operations are + processed by the server + +Mathematical operations, bitwise operations and callbacks can be chained, given the extended syntax with `()` around +each operation. + +Examples: + +```csharp +var session = ArchipelagoSessionFactory.CreateSession("localhost", 38281); +session.TryConnectAndLogin("Timespinner", "Jarno", ItemsHandlingFlags.AllItems); + +//Initializing +session.DataStorage["B"].Initialize(20); //Set initial value for B in global scope if it has no value assigned yet + +//Storing/Updating +session.DataStorage[Scope.Slot, "SetPersonal"] = 20; //Set `SetPersonal` to 20, in scope of the current connected user\slot +session.DataStorage[Scope.Global, "SetGlobal"] = 30; //Set `SetGlobal` to 30, in global scope shared among all players (the default scope is global) +session.DataStorage["Add"] += 50; //Add 50 to the current value of `Add` +session.DataStorage["Divide"] /= 2; //Divide current value of `Divide` in half +session.DataStorage["Max"] += + Operation.Max(80); //Set `Max` to 80 if the stored value is lower than 80 +session.DataStorage["Dictionary"] = JObject.FromObject(new Dictionary()); //Set `Dictionary` to a Dictionary +session.DataStorage["SetObject"] = JObject.FromObject(new SomeClassOrStruct()); //Set `SetObject` to a custom object +session.DataStorage["BitShiftLeft"] += Bitwise.LeftShift(1); //Bitshift current value of `BitShiftLeft` to left by 1 +session.DataStorage["Xor"] += Bitwise.Xor(0xFF); //Modify `Xor` using the Bitwise exclusive or operation +session.DataStorage["DifferentKey"] = session.DataStorage["A"] - 30; //Get value of `A`, Assign it to `DifferentKey` and then subtract 30 +session.DataStorage["Array"] = new []{ "One", "Two" }; //Arrays can be stored directly, List's needs to be converted ToArray() first +session.DataStorage["Array"] += new []{ "Three" }; //Append array values to existing array on the server + +//Chaining operations +session.DataStorage["Min"] = (session.DataStorage["Min"] + 40) + Operation.Min(100); //Add 40 to `Min`, then Set `Min` to 100 if `Min` is bigger than 100 +session.DataStorage["C"] = ((session.DataStorage["C"] - 6) + Bitwise.RightShift(1)) ^ 3; //Subtract 6 from `C`, then multiply `C` by 2 using bitshifting, then take `C` to the power of 3 + +//Update callbacks +//EnergyLink deplete pattern, subtract 50, then set value to 0 if its lower than 0 +session.DataStorage["EnergyLink"] = ((session.DataStorage["EnergyLink"] - 50) + Operation.Min(0)) + Callback.Add((oldData, newData) => { + var actualDepleted = (float)newData - (float)oldData; //calculate the actual change, might differ if there was less than 50 left on the server +}); + +//Keeping track of changes +session.DataStorage["OnChangeHandler"].OnValueChanged += (oldData, newData) => { + var changed = (int)newData - (int)oldData; //Keep track of changes made to `OnChangeHandler` by any client, and calculate the difference +}; + +//Keeping track of change (but for more complex data structures) +session.DataStorage["OnChangeHandler"].OnValueChanged += (oldData, newData) => { + var old_dict = oldData.ToObject>(); + var new_dict = newData.ToObject>(); +}; + +//Retrieving +session.DataStorage["Async"].GetAsync(s => { string r = s }); //Retrieve value of `Async` asynchronously +float f = session.DataStorage["Float"]; //Retrieve value for `Float` synchronously and store it as a float +var d = session.DataStorage["DateTime"].To() //Retrieve value for `DateTime` as a DateTime struct +var array = session.DataStorage["Strings"].To() //Retrieve value for `Strings` as string Array + +//Handling anonymous object, if the target type is not known you can use `To()` and use its interface to access the members +session.DataStorage["Anonymous"] = JObject.FromObject(new { Number = 10, Text = "Hello" }); //Set `Anonymous` to an anonymous object +var obj = session.DataStorage["Anonymous"].To(); //Retrieve value for `Anonymous` where an anonymous object was stored +var number = (int)obj["Number"]; //Get value for anonymous object key `Number` +var text = (string)obj["Text"]; //Get value for anonymous object key `Text` + +``` diff --git a/docfx/events.md b/docfx/events.md new file mode 100644 index 00000000..a9f20c2c --- /dev/null +++ b/docfx/events.md @@ -0,0 +1,70 @@ + +# Event Hooks + +If using .net 4.0 or higher, you can use `ConnectAsync` and `LoginAsync` to prevent hitching for injection-based implementations like harmony. + +## Message Logging + +The Archipelago server can send messages to client to be displayed on screen as sort of a log, this is done by handling the `PrintJsonPacket` packets. This library simplifies this process into a single handler for you to handle. +```csharp +var session = ArchipelagoSessionFactory.CreateSession("localhost", 38281); +session.MessageLog.OnMessageReceived += OnMessageReceived; +session.TryConnectAndLogin("Timespinner", "Jarno", ItemsHandlingFlags.AllItems, new Version(0,3,5)); + +static void OnMessageReceived(LogMessage message) +{ + DisplayOnScreen(message.ToString()); +} +``` + +In some cased you might want extra information that is provided by the server in such cases you can use type checking + +```csharp +static void OnMessageReceived(LogMessage message) +{ + switch (message) + { + case ItemHintLogMessage hintLogMessage: + var receiver = itemSendLogMessage.Receiver; + var sender = itemSendLogMessage.Sender; + var networkItem = itemSendLogMessage.Item; + var found = hintLogMessage.IsFound; + break; + case ItemSendLogMessage itemSendLogMessage: + var receiver = itemSendLogMessage.Receiver; + var sender = itemSendLogMessage.Sender; + var networkItem = itemSendLogMessage.Item; + break; + } + + DisplayOnScreen(message.ToString()); +} +``` + +If you want more control over how the message is displayed, like for example you might want to color certain parts of the message, +Then you can use the `Parts` property. This returns each part of the message in order of appearnce with the `Text` to be displayed and also the `Color` it would normally be diplayed in. +If `IsBackgroundColor` is true, then the color should be applied to the message background instead. +The MessagePart message can also contain additional information that can be retrieved by type checking. + + +```csharp +foreach (part in message.Parts) +{ + switch (part) + { + case ItemMessagePart itemMessagePart: + var itemId = itemMessagePart.ItemId; + var flags = itemMessagePart.Flags; + break; + case LocationMessagePart locationMessagePart: + var locationId = locationMessagePart.LocationId; + break; + case PlayerMessagePart playerMessagePart: + var slotId = playerMessagePart.SlotId; + var isCurrentPlayer = playerMessagePart.IsActivePlayer; + break; + } + + DisplayOnScreen(part.Text, part.Color, part.IsBackgroundColor); +} +``` diff --git a/docfx/helpers.md b/docfx/helpers.md new file mode 100644 index 00000000..b683f9ad --- /dev/null +++ b/docfx/helpers.md @@ -0,0 +1,148 @@ +# Helper Overview + +```csharp +session.Socket // Payload-agnostic interface for sending/receving the most basic transmission units between client/server +session.Items // Helpers for handling receipt of items +session.Locations // Helpers for reporting visited locations to the server +session.Players // Helpers for translating player information such as number, alias, name etc. +session.DataStorage // Helpers for reading/writing data globally accessible to any client connected in the room +session.ConnectionInfo // Helpers for reading/handling useful information on the current connection +session.RoomState // Information on the state of the room +session.MessageLog // Interface for the server to push info messages to the user +``` + +## Players + +The player helper provides methods for accessing details about the other players currently connected to the Archipelago +session. + +### Get All Player Names + +```csharp +var sortedPlayerNames = session.Players.AllPlayers.Select(x => x.Name).OrderBy(x => x); +``` + +### Get Current Player Name + +```csharp +string playerName = session.Players.GetPlayerAliasAndName(session.ConnectionInfo.Slot); +``` + +## Locations + +### Report Collected Location(s) + +Call the following method to inform the server of locations whose items have been "found", and therefore should be +distributed if necessary: + +```csharp +// Report multiple at once +session.Locations.CompleteLocationChecks(new []{1,3,8}); + +// Or report one at a time +session.Locations.CompleteLocationChecks(3); +``` + +The location ID used is of that defined in the AP world. + +### Location ID <--> Name + +```csharp +string locationName = session.Locations.GetLocationNameFromId(42) ?? $"Location: {locationId}"; +long locationId = session.Locations.GetLocationIdFromName(locationName); +``` + +### Scout Location Checks + +Scouting means asking the server what is stored in a specific location *without* collecting it: + +```csharp +session.Locations.ScoutLocationsAsync(locationInfoPacket => Console.WriteLine(locationInfoPacket.Locations.Count)); +``` + +## Items + +### Item ID --> Name + +```csharp +string itemName = session.Items.GetItemName(88) ?? $"Item: {itemId}"; +``` + +### Access Received Items + +At any time, you can access the current inventory for the active session/slot via the `Items` helper like so: + +```csharp +foreach(NetworkItem item in session.Items.AllItemsReceived) +{ + long itemId = item.Item; +} +``` + +*Note: The list of received items will never shrink and the collection is guaranteed to be in the order that the server +sent the items. Because of this, it is safe to assume that if the size of this collection has changed it's because new +items were received and appended to the end of the collection.* + +### Received Item Callback Handler (Asynchronous) + +```csharp +// Must go BEFORE a successful connection attempt +session.Items.ItemReceived += (receivedItemsHelper) => { + var itemReceivedName = receivedItemsHelper.PeekItemName() ?? $"Item: {itemId}"; + + // ... Handle item receipt here + + receivedItemsHelper.DequeueItem(); +}; +``` + +*Note: This callback event will occur for every item on connection and reconnection.* + +## RoomState + +The RoomState helper provides access to values that represent the current state of the multiworld room, with information +such as the cost of a hint and or your current accumulated amount of hint point or the permissions for things like +forfeiting + +```csharp +Console.WriteLine($"You have {session.RoomState.HintPoints}, and need {session.RoomState.HintCost} for a hint"); +``` + +## ConnectionInfo + +The ConnectionInfo helper provides access to values under which you are currently connected, such as your slot number or +your currently used tags and item handling flags + +```csharp +Console.WriteLine($"You are connected on slot {session.ConnectionInfo.Slot}, on team {session.ConnectionInfo.Team}"); +``` + +## ArchipelagoSocket + +The socket helper is a lower level API allowing for direct access to the socket which the session object uses to +communicate with the Archipelago server. You may use this object to hook onto when messages are received, or you may use +it to send any packets defined in the library. Various events are exposed to allow for receipt of errors or notifying of +socket close. + +```csharp +session.Socket.SendPacket(new SayPacket(){Text = "Woof woof!"}); +``` + +## DeathLink + +DeathLink support is included in the library. You may enable it by using the `CreateDeathLinkService` in the +`DeathLinkProvider` class, and the `EnableDeathlink` method on the service. Deathlink can be toggled on and off using +the `EnableDeathlink` and `DisableDeathlink` methods on the service. + +```csharp +var session = ArchipelagoSessionFactory.CreateSession("localhost", 38281); + +var deathLinkService = session.CreateDeathLinkService().EnableDeathlink(); + +deathLinkService.OnDeathLinkReceived += (deathLinkObject) => { + // ... Kill your player(s). +}; + +// ... On death: +deathLinkService.SendDeathLink(new DeathLink("Ijwu", "Died to exposure.")); +``` diff --git a/docfx/index.md b/docfx/index.md index e053c0dd..5c530397 100644 --- a/docfx/index.md +++ b/docfx/index.md @@ -2,7 +2,11 @@ ## Installing the package -First, install [the Archipelago.MultiClient.Net package from NuGet](https://www.nuget.org/packages/Archipelago.MultiClient.Net). NuGet provides several options for how to do this with examples given on the page. Optionally, you can also install the community-supported [Archipelago.MultiClient.Net.Analyzers package](https://www.nuget.org/packages/Archipelago.MultiClient.Net.Analyzers), which provides source generators, code analysis, and fixes to help prevent and correct common usage errors at compile time. +First, install [the Archipelago.MultiClient.Net package from NuGet](https://www.nuget.org/packages/Archipelago.MultiClient.Net). +NuGet provides several options for how to do this with examples given on the page. Optionally, you can also install the +community-supported [Archipelago.MultiClient.Net.Analyzers package](https://www.nuget.org/packages/Archipelago.MultiClient.Net.Analyzers), +which provides source generators, code analysis, and fixes to help prevent and correct common usage errors at compile +time. ## Create Session Instance @@ -15,7 +19,9 @@ var session = ArchipelagoSessionFactory.CreateSession("localhost:38281"); var session = ArchipelagoSessionFactory.CreateSession("localhost"); ``` -The freshly created `ArchipelagoSession` object is the entrypoint for all incoming and outgoing interactions with the server. Keep it in scope for at least the lifetime of the connection. If the room changes ports, or the user needs to connect to a different room, then a new session needs to be created at the new host and port. +The freshly created `ArchipelagoSession` object is the entrypoint for all incoming and outgoing interactions with the +server. Keep it in scope for at least the lifetime of the connection. If the room changes ports, or the user needs to +connect to a different room, then a new session needs to be created at the new host and port. ## Connect to Room @@ -32,7 +38,7 @@ LoginResult TryConnectAndLogin( IncludeStartingInventory AllItems */ - Version version = null, // Minimum Archipelago world specification version which this client can successfuly interface with + Version version = null, // Minimum Archipelago API specification version which this client can successfuly interface with string[] tags = null, /* One of the following (see AP docs for details) "DeathLink" "Tracker" @@ -40,7 +46,7 @@ LoginResult TryConnectAndLogin( */ string uuid = null, // Unique identifier for this player/client, if null randomly generated string password = null, // Password that was set when the room was created - bool requestSlotData = true // If the LoginResult should contain the slot data + bool requestSlotData = true // If the LoginResult should contain the slot data ); ``` @@ -50,9 +56,11 @@ For example, LoginResult result = session.TryConnectAndLogin("Risk of Rain 2", "Ijwu", ItemsHandlingFlags.AllItems); ``` -Would attempt to connect to a password-less room at the slot `Ijwu`, and report the game `Risk of Rain 2` with a minimum apworld version of `v2.1.0`. +would attempt to connect to a password-less room with the slot name `Ijwu`, report the game as `Risk of Rain 2`, and +tell the server that we need to be sent ReceivedItems Packets for all item sources. -Once connected, you have access to a suite of helper objects which provide an interface for sending/receiving information with the server. +Once connected, you have access to a suite of helper objects which provide an interface for sending/receiving +information with the server. ### Example Connection @@ -64,6 +72,7 @@ private static void Connect(string server, string user, string pass) try { // handle TryConnectAndLogin attempt here and save the returned object to `result` + result = session.TryConnectAndLogin("Risk of Rain 2", "Ijwu", ItemsHandlingFlags.AllItems); } catch (Exception e) { @@ -86,323 +95,9 @@ private static void Connect(string server, string user, string pass) return; // Did not connect, show the user the contents of `errorMessage` } - // Successfully connected, `ArchipelagoSession` (assume statically defined as `session` from now on) can now be used to interact with the server and the returned `LoginSuccessful` contains some useful information about the initial connection (e.g. a copy of the slot data as `loginSuccess.SlotData`) + // Successfully connected, `ArchipelagoSession` (assume statically defined as `session` from now on) can now be + // used to interact with the server and the returned `LoginSuccessful` contains some useful information about the + // initial connection (e.g. a copy of the slot data as `loginSuccess.SlotData`) var loginSuccess = (LoginSuccessful)result; } ``` - -If using .net 4.0 or higher, you can use `ConnectAsync` and `LoginAsync` to prevent hitching for injection-based implementations like harmony. - -## Helper Overview - -```csharp -session.Socket // Payload-agnostic interface for sending/receving the most basic transmission units between client/server -session.Items // Helpers for handling receipt of items -session.Locations // Helpers for reporting visited locations to the servers -session.Players // Helpers for translating player number, alias, name etc. -session.DataStorage // Helpers for reading/writing globally accessible to any client connected in the room -session.ConnectionInfo // Helpers for reading/handling useful information on the current connection -session.RoomState // Information on the state of the room -session.MessageLog // Interface for the server to push info messages to the user -``` - -## Players - -The player helper provides methods for accessing details about the other players currently connected to the Archipelago session. - -### Get All Player Names - -```csharp -var sortedPlayerNames = session.Players.AllPlayers.Select(x => x.Name).OrderBy(x => x); -``` - -### Get Current Player Name - -```csharp -string playerName = session.Players.GetPlayerAliasAndName(session.ConnectionInfo.Slot); -``` - -## Locations - -### Report Collected Location(s) - -Call the following method to inform the server of locations whose items have been "found", and therefore should be distributed (if neccessary): - -```csharp -// Report multiple at once -session.Locations.CompleteLocationChecks(new []{1,3,8}); - -// Or report one at a time -session.Locations.CompleteLocationChecks(3); -``` - -The location ID used is of that defined in the AP world. - -### Location ID <--> Name - -```csharp -string locationName = session.Locations.GetLocationNameFromId(42) ?? $"Location: {locationId}"; -long locationId = session.Locations.GetLocationIdFromName(locationName); -``` - -### Scout Location Checks - -Scouting means asking the server what is stored in a specific location *without* collecting it: - -```csharp -session.Locations.ScoutLocationsAsync(locationInfoPacket => Console.WriteLine(locationInfoPacket.Locations.Count)); -``` - -## Items - -### Item ID --> Name - -```csharp -string itemName = session.Items.GetItemName(88) ?? $"Item: {itemId}"; -``` - -### Access Received Items - -At any time, you can access the current inventory for the active session/slot via the `Items` helper like so: - -```csharp -foreach(NetworkItem item in session.Items.AllItemsReceived) -{ - long itemId = item.Item; -} -``` - -*Note: The list of received items will never shrink and the collection is guaranteed to be in the order that the server sent the items. Because of this, it is safe to assume that if the size of this collection has changed it's because new items were received and appended to the end of the collection.* - -### Received Item Callback Handler (Asynchronous) - -```csharp -// Must go AFTER a successful connection attempt -session.Items.ItemReceived += (receivedItemsHelper) => { - var itemReceivedName = receivedItemsHelper.PeekItemName() ?? $"Item: {itemId}"; - - // ... Handle item receipt here - - receivedItemsHelper.DequeueItem(); -}; -``` - -*Note: This callback event will occur for every item on connection and reconnection. Whether or not it includes the first batch of remote items depends on your `ItemHandlingFlags` when connecting.* - -## RoomState - -The roomstate helper provides access to values that represent the current state of the multiworld room, with information such as the cost of a hint and or your current accumulated amount of hint point or the permissions for things like forfeiting - -```csharp -Console.WriteLine($"You have {session.RoomState.HintPoints}, and need {session.RoomState.HintCost} for a hint"); -``` - -## ConnectionInfo - -The conection info helper provides access to values under which you are currently connected, such as your slot number or your currently used tags and item handling flags - -```csharp -Console.WriteLine($"You are connected on slot {session.ConnectionInfo.Slot}, on team {session.ConnectionInfo.Team}"); -``` - -## ArchipelagoSocket - -The socket helper is a lower level API allowing for direct access to the socket which the session object uses to communicate with the Archipelago server. You may use this object to hook onto when messages are received or you may use it to send any packets defined in the library. Various events are exposed to allow for receipt of errors or notifying of socket close. - -```csharp -session.Socket.SendPacket(new SayPacket(){Text = "Woof woof!"}); -``` - -## DeathLink - -DeathLink support is included in the library. You may enable it by using the `CreateDeathLinkService` in the `DeathLinkProvider` class, and the `EnableDeathlink` method on the service. Deathlink can be toggled on an off by the the `EnableDeathlink` and `DisableDeathlink` methods on the service - -```csharp -var session = ArchipelagoSessionFactory.CreateSession("localhost", 38281); - -var deathLinkService = session.CreateDeathLinkService().EnableDeathlink(); -session.TryConnectAndLogin("Risk of Rain 2", "Ijwu", ItemsHandlingFlags.AllItems); - -deathLinkService.OnDeathLinkReceived += (deathLinkObject) => { - // ... Kill your player(s). -}; - -// ... On death: -deathLinkService.SendDeathLink(new DeathLink("Ijwu", "Died to exposure.")); -``` - -## DataStorage - -DataStorage support is included in the library. You may save values on the archipelago server in order to share them across other player's sessions or to simply keep track of values outside of your game's state. - -The DataStorage provides an interface based on keys and their scope. By assigning a value to a key, that value is stored on the server and by reading from a key a value is retrieved from the server. -Assigning and reading values from the store can be done using simple assignments `=`: -* `= session.DataStorage["Key"]`, read value from the data storage synchronously -* `session.DataStorage["Key"] =`, write value to the data storage asynchronously -* Complex objects need to be stored and retrieved in the form of a `JObject`, therefor you must wrap them into a `JObject.FromObject()` - -The DataStorage also provides methods to retrieve the value of a key asynchronously using `[key].GetAsync`. -To set the initial value of a key without overriding any existing value the `[key].Initialize` method can be used. -If you're interested in keeping track of when a value of a certain key is changed by any client you can use the `[key].OnValueChanged` handler to register a callback for when the value gets updated. - -Mathematical operations on values stored on the server are supported using the following operators: -* `+`, Add right value to left value -* `-`, Subtract right value from left value -* `*`, Multiply left value by right value -* `/`, Divide left value by right value -* `%`, Gets remainder after dividing left value by right value -* `^`, Multiply left value by the power of the right value - -Bitwise operations on values stored on the server are supported using the following opperations: -* `+ Bitwise.Xor(x)`, apply logical exclusive OR to the left value using value x -* `+ Bitwise.Or(x)`, apply logical OR to the left value using value x -* `+ Bitwise.And(x)`, apply logical AND to the left value using value x -* `+ Bitwise.LeftShift(x)`, binary shift the left value to the left by x -* `+ Bitwise.RightShift(x)`, binary shift the left value to the right by x - -Other operations on values stored on the server are supported using the following opperations: -* `+ Operation.Min(x)`, get the lowest value of the left value and x -* `+ Operation.Max(x)`, get the highest value of the left value and x -* `+ Operation.Remove(x)`, when the left value is a list, removes the first element with value x -* `+ Operation.Pop(x)`, when the left value is a list or dictionary, removes the element at index x or key x -* `+ Operation.Update(x)`, when the left value is a list or dictionary, updates the dictionary with the keys/values in x - -Operation specific callbacks are supported, these get called only once with the results of the current operation: -* `+ Callback.Add((oldValue, newValue) => {});`, calls this method after your operation or chain of operations are proccesed by the server - -Mathematical operations, bitwise operations and callbacks can be chained, given the extended syntax with `()` around each operation. - -Examples: -```csharp -var session = ArchipelagoSessionFactory.CreateSession("localhost", 38281); -session.TryConnectAndLogin("Timespinner", "Jarno", ItemsHandlingFlags.AllItems); - -//Initializing -session.DataStorage["B"].Initialize(20); //Set initial value for B in global scope if it has no value assigned yet - -//Storing/Updating -session.DataStorage[Scope.Slot, "SetPersonal"] = 20; //Set `SetPersonal` to 20, in scope of the current connected user\slot -session.DataStorage[Scope.Global, "SetGlobal"] = 30; //Set `SetGlobal` to 30, in global scope shared among all players (the default scope is global) -session.DataStorage["Add"] += 50; //Add 50 to the current value of `Add` -session.DataStorage["Divide"] /= 2; //Divide current value of `Divide` in half -session.DataStorage["Max"] += + Operation.Max(80); //Set `Max` to 80 if the stored value is lower than 80 -session.DataStorage["Dictionary"] = JObject.FromObject(new Dictionary()); //Set `Dictionary` to a Dictionary -session.DataStorage["SetObject"] = JObject.FromObject(new SomeClassOrStruct()); //Set `SetObject` to a custom object -session.DataStorage["BitShiftLeft"] += Bitwise.LeftShift(1); //Bitshift current value of `BitShiftLeft` to left by 1 -session.DataStorage["Xor"] += Bitwise.Xor(0xFF); //Modify `Xor` using the Bitwise exclusive or operation -session.DataStorage["DifferentKey"] = session.DataStorage["A"] - 30; //Get value of `A`, Assign it to `DifferentKey` and then subtract 30 -session.DataStorage["Array"] = new []{ "One", "Two" }; //Arrays can be stored directly, List's needs to be converted ToArray() first -session.DataStorage["Array"] += new []{ "Three" }; //Append array values to existing array on the server - -//Chaining operations -session.DataStorage["Min"] = (session.DataStorage["Min"] + 40) + Operation.Min(100); //Add 40 to `Min`, then Set `Min` to 100 if `Min` is bigger than 100 -session.DataStorage["C"] = ((session.DataStorage["C"] - 6) + Bitwise.RightShift(1)) ^ 3; //Subtract 6 from `C`, then multiply `C` by 2 using bitshifting, then take `C` to the power of 3 - -//Update callbacks -//EnergyLink deplete pattern, subtract 50, then set value to 0 if its lower than 0 -session.DataStorage["EnergyLink"] = ((session.DataStorage["EnergyLink"] - 50) + Operation.Min(0)) + Callback.Add((oldData, newData) => { - var actualDepleted = (float)newData - (float)oldData; //calculate the actual change, might differ if there was less than 50 left on the server -}); - -//Keeping track of changes -session.DataStorage["OnChangeHandler"].OnValueChanged += (oldData, newData) => { - var changed = (int)newData - (int)oldData; //Keep track of changes made to `OnChangeHandler` by any client, and calculate the difference -}; - -//Keeping track of change (but for more complex data structures) -session.DataStorage["OnChangeHandler"].OnValueChanged += (oldData, newData) => { - var old_dict = oldData.ToObject>(); - var new_dict = newData.ToObject>(); -}; - -//Retrieving -session.DataStorage["Async"].GetAsync(s => { string r = s }); //Retrieve value of `Async` asynchronously -float f = session.DataStorage["Float"]; //Retrieve value for `Float` synchronously and store it as a float -var d = session.DataStorage["DateTime"].To() //Retrieve value for `DateTime` as a DateTime struct -var array = session.DataStorage["Strings"].To() //Retrieve value for `Strings` as string Array - -//Handling anonymous object, if the target type is not known you can use `To()` and use its interface to access the members -session.DataStorage["Anonymous"] = JObject.FromObject(new { Number = 10, Text = "Hello" }); //Set `Anonymous` to an anonymous object -var obj = session.DataStorage["Anonymous"].To(); //Retrieve value for `Anonymous` where an anonymous object was stored -var number = (int)obj["Number"]; //Get value for anonymous object key `Number` -var text = (string)obj["Text"]; //Get value for anonymous object key `Text` - -``` - -## Message Logging - -The Archipelago server can send messages to client to be displayed on screen as sort of a log, this is done by handling the `PrintJsonPacket` packets. This library simplifies this process into a single handler for you to handle. -```csharp -var session = ArchipelagoSessionFactory.CreateSession("localhost", 38281); -session.MessageLog.OnMessageReceived += OnMessageReceived; -session.TryConnectAndLogin("Timespinner", "Jarno", ItemsHandlingFlags.AllItems, new Version(0,3,5)); - -static void OnMessageReceived(LogMessage message) -{ - DisplayOnScreen(message.ToString()); -} -``` - -In some cased you might want extra information that is provided by the server in such cases you can use type checking - -```csharp -static void OnMessageReceived(LogMessage message) -{ - switch (message) - { - case ItemHintLogMessage hintLogMessage: - var receiver = itemSendLogMessage.Receiver; - var sender = itemSendLogMessage.Sender; - var networkItem = itemSendLogMessage.Item; - var found = hintLogMessage.IsFound; - break; - case ItemSendLogMessage itemSendLogMessage: - var receiver = itemSendLogMessage.Receiver; - var sender = itemSendLogMessage.Sender; - var networkItem = itemSendLogMessage.Item; - break; - } - DisplayOnScreen(message.ToString()); -} -``` - -If you want more control over how the message is displayed, like for example you might want to color certain parts of the message, -Then you can use the `Parts` property. This returns each part of the message in order of appearnce with the `Text` to be displayed and also the `Color` it would normally be diplayed in. -If `IsBackgroundColor` is true, then the color should be applied to the message background instead. -The MessagePart message can also contain additional information that can be retrieved by type checking. - - -```csharp -foreach (part in message.Parts) -{ - switch (part) - { - case ItemMessagePart itemMessagePart: - var itemId = itemMessagePart.ItemId; - var flags = itemMessagePart.Flags; - break; - case LocationMessagePart locationMessagePart: - var locationId = locationMessagePart.LocationId; - break; - case PlayerMessagePart playerMessagePart: - var slotId = playerMessagePart.SlotId; - var isCurrentPlayer = playerMessagePart.IsActivePlayer; - break; - } - - DisplayOnScreen(part.Text, part.Color, part.IsBackgroundColor); -} -``` - -## Send Completion - -You can report the completion of the player's goal like so: - -```csharp -public static void send_completion() -{ - var statusUpdatePacket = new StatusUpdatePacket(); - statusUpdatePacket.Status = ArchipelagoClientState.ClientGoal; - Session.Socket.SendPacket(statusUpdatePacket); -} -``` diff --git a/docfx/packets.md b/docfx/packets.md new file mode 100644 index 00000000..d4dc689e --- /dev/null +++ b/docfx/packets.md @@ -0,0 +1,13 @@ + +## Send Completion + +You can report the completion of the player's goal like so: + +```csharp +public static void send_completion() +{ + var statusUpdatePacket = new StatusUpdatePacket(); + statusUpdatePacket.Status = ArchipelagoClientState.ClientGoal; + Session.Socket.SendPacket(statusUpdatePacket); +} +``` From 1f277c0d31572a3a0c014f9b02796e5b12aac83d Mon Sep 17 00:00:00 2001 From: alwaysintreble Date: Thu, 27 Feb 2025 13:41:24 -0600 Subject: [PATCH 02/17] expand toc to have new docs --- docfx/datastorage.md | 2 +- docfx/docs/toc.yml | 12 ++++++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/docfx/datastorage.md b/docfx/datastorage.md index 0b8626b9..2700aa1a 100644 --- a/docfx/datastorage.md +++ b/docfx/datastorage.md @@ -1,4 +1,4 @@ -## DataStorage +# DataStorage DataStorage support is included in the library. You may save values on the archipelago server in order to share them across other player's sessions or to simply keep track of values outside your game's state. diff --git a/docfx/docs/toc.yml b/docfx/docs/toc.yml index e93466df..f3ae71cd 100644 --- a/docfx/docs/toc.yml +++ b/docfx/docs/toc.yml @@ -1,2 +1,10 @@ -- name: Get Started -- href: ../index.md \ No newline at end of file +items: + - name: Get Started + href: ../index.md + - name: Helpers + items: + - href: ../helpers.md + - href: ../events.md + - href: ../datastorage.md + - name: Packets + href: ../packets.md \ No newline at end of file From 835d3aaaf0888c66cac40985844f7bb569dcbef6 Mon Sep 17 00:00:00 2001 From: alwaysintreble Date: Thu, 27 Feb 2025 13:49:42 -0600 Subject: [PATCH 03/17] change structure a bit --- docfx/{ => docs}/datastorage.md | 0 docfx/{ => docs}/events.md | 0 docfx/{index.md => docs/gettingStarted.md} | 0 docfx/{ => docs}/helpers.md | 0 docfx/{ => docs}/packets.md | 2 ++ docfx/docs/toc.yml | 12 +++++------- 6 files changed, 7 insertions(+), 7 deletions(-) rename docfx/{ => docs}/datastorage.md (100%) rename docfx/{ => docs}/events.md (100%) rename docfx/{index.md => docs/gettingStarted.md} (100%) rename docfx/{ => docs}/helpers.md (100%) rename docfx/{ => docs}/packets.md (96%) diff --git a/docfx/datastorage.md b/docfx/docs/datastorage.md similarity index 100% rename from docfx/datastorage.md rename to docfx/docs/datastorage.md diff --git a/docfx/events.md b/docfx/docs/events.md similarity index 100% rename from docfx/events.md rename to docfx/docs/events.md diff --git a/docfx/index.md b/docfx/docs/gettingStarted.md similarity index 100% rename from docfx/index.md rename to docfx/docs/gettingStarted.md diff --git a/docfx/helpers.md b/docfx/docs/helpers.md similarity index 100% rename from docfx/helpers.md rename to docfx/docs/helpers.md diff --git a/docfx/packets.md b/docfx/docs/packets.md similarity index 96% rename from docfx/packets.md rename to docfx/docs/packets.md index d4dc689e..89d4047e 100644 --- a/docfx/packets.md +++ b/docfx/docs/packets.md @@ -1,4 +1,6 @@  +# Packets + ## Send Completion You can report the completion of the player's goal like so: diff --git a/docfx/docs/toc.yml b/docfx/docs/toc.yml index f3ae71cd..3781d0bd 100644 --- a/docfx/docs/toc.yml +++ b/docfx/docs/toc.yml @@ -1,10 +1,8 @@ items: - - name: Get Started - href: ../index.md + - href: gettingStarted.md - name: Helpers items: - - href: ../helpers.md - - href: ../events.md - - href: ../datastorage.md - - name: Packets - href: ../packets.md \ No newline at end of file + - href: helpers.md + - href: events.md + - href: datastorage.md + - href: packets.md \ No newline at end of file From ef058a0993536f55da70cb3723ea9ee6d030aa4a Mon Sep 17 00:00:00 2001 From: alwaysintreble Date: Thu, 27 Feb 2025 14:09:36 -0600 Subject: [PATCH 04/17] docfx specifically needs the base index.md for the home page --- docfx/docfx.json | 4 ++-- docfx/docs/{datastorage.md => datastore.md} | 0 docfx/docs/{gettingStarted.md => quick-start.md} | 10 +--------- docfx/docs/toc.yml | 9 ++++++--- docfx/index.md | 13 +++++++++++++ 5 files changed, 22 insertions(+), 14 deletions(-) rename docfx/docs/{datastorage.md => datastore.md} (100%) rename docfx/docs/{gettingStarted.md => quick-start.md} (86%) create mode 100644 docfx/index.md diff --git a/docfx/docfx.json b/docfx/docfx.json index 516bf3be..d51b29ad 100644 --- a/docfx/docfx.json +++ b/docfx/docfx.json @@ -36,8 +36,8 @@ "modern" ], "globalMetadata": { - "_appName": "multiclient", - "_appTitle": "multiclient", + "_appName": "Archipelago.MultiClient.Net", + "_appTitle": "Archipelago.MultiClient.Net", "_enableSearch": true, "pdf": false } diff --git a/docfx/docs/datastorage.md b/docfx/docs/datastore.md similarity index 100% rename from docfx/docs/datastorage.md rename to docfx/docs/datastore.md diff --git a/docfx/docs/gettingStarted.md b/docfx/docs/quick-start.md similarity index 86% rename from docfx/docs/gettingStarted.md rename to docfx/docs/quick-start.md index 5c530397..239f5db3 100644 --- a/docfx/docs/gettingStarted.md +++ b/docfx/docs/quick-start.md @@ -1,12 +1,4 @@ -# Getting Started - -## Installing the package - -First, install [the Archipelago.MultiClient.Net package from NuGet](https://www.nuget.org/packages/Archipelago.MultiClient.Net). -NuGet provides several options for how to do this with examples given on the page. Optionally, you can also install the -community-supported [Archipelago.MultiClient.Net.Analyzers package](https://www.nuget.org/packages/Archipelago.MultiClient.Net.Analyzers), -which provides source generators, code analysis, and fixes to help prevent and correct common usage errors at compile -time. +# Quick Start ## Create Session Instance diff --git a/docfx/docs/toc.yml b/docfx/docs/toc.yml index 3781d0bd..3e36d5f7 100644 --- a/docfx/docs/toc.yml +++ b/docfx/docs/toc.yml @@ -1,8 +1,11 @@ items: - - href: gettingStarted.md + - name: Get Started + items: + - href: ../index.md + - href: quick-start.md - name: Helpers items: - href: helpers.md - href: events.md - - href: datastorage.md - - href: packets.md \ No newline at end of file + - href: datastore.md + - href: packets.md diff --git a/docfx/index.md b/docfx/index.md new file mode 100644 index 00000000..9866db2d --- /dev/null +++ b/docfx/index.md @@ -0,0 +1,13 @@ +# Introduction + +Archipelago.MultiClient.net is a client library for use with .NET based applications for interfacing with +[Archipelago](https://github.com/ArchipelagoMW/Archipelago) server hosts. This library conforms with the latest stable +[Archipelago Network Protocol Specification](https://github.com/ArchipelagoMW/Archipelago/blob/main/docs/network%20protocol.md). + +## Installing the package + +First, install the [Archipelago.MultiClient.Net package from NuGet](https://www.nuget.org/packages/Archipelago.MultiClient.Net). +NuGet provides several options for how to do this with examples given on the page. Optionally, you can also install the +community-supported [Archipelago.MultiClient.Net.Analyzers package](https://www.nuget.org/packages/Archipelago.MultiClient.Net.Analyzers), +which provides source generators, code analysis, and fixes to help prevent and correct common usage errors at compile +time. From 6283bc14ba076654b35766d41a321f92884274db Mon Sep 17 00:00:00 2001 From: alwaysintreble Date: Thu, 27 Feb 2025 14:34:31 -0600 Subject: [PATCH 05/17] add descriptions of basic concepts --- docfx/index.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docfx/index.md b/docfx/index.md index 9866db2d..4da8b943 100644 --- a/docfx/index.md +++ b/docfx/index.md @@ -11,3 +11,24 @@ NuGet provides several options for how to do this with examples given on the pag community-supported [Archipelago.MultiClient.Net.Analyzers package](https://www.nuget.org/packages/Archipelago.MultiClient.Net.Analyzers), which provides source generators, code analysis, and fixes to help prevent and correct common usage errors at compile time. + +## Concepts + +### Session + +The @"Archipelago.MultiClient.Net.ArchipelagoSession?text=ArchipelagoSession" is the basis of all operations involved +with communicating with the Archipelago server. Before any communicating can be executed, a new session must be created, +and any relevant [event hooks](docs/events.md) should be registered before attempting a connection. + +### Helpers + +There exist many [helper classes and methods](docs/helpers.md) to help digest the information received from the server +into specific formats, or to send specific information to the server. If a helper doesn't do what you need, the raw +server data is also available to do what is needed through the +@"Archipelago.MultiClient.Net.Helpers.IArchipelagoSocketHelper?text=Session.Socket". + +### Packets + +Communication with the Archipelago server is done by sending and receiving various json packets through the websocket +connection. Most packets that you want to send will have abstraction layers available through the helpers, but sometimes +there is need to send raw packets such as a @"Archipelago.MultiClient.Net.Packets.SayPacket?text=SayPacket". From 741cda19a9589e45bf403e5bac63419efd8c4953 Mon Sep 17 00:00:00 2001 From: alwaysintreble Date: Thu, 27 Feb 2025 15:01:09 -0600 Subject: [PATCH 06/17] helpers rewrite with links --- docfx/docfx.json | 1 + docfx/docs/{ => helpers}/datastore.md | 0 docfx/docs/{ => helpers}/events.md | 18 +++--- docfx/docs/{ => helpers}/helpers.md | 80 ++++++++++----------------- docfx/docs/helpers/players.md | 0 docfx/docs/toc.yml | 6 +- 6 files changed, 44 insertions(+), 61 deletions(-) rename docfx/docs/{ => helpers}/datastore.md (100%) rename docfx/docs/{ => helpers}/events.md (81%) rename docfx/docs/{ => helpers}/helpers.md (56%) create mode 100644 docfx/docs/helpers/players.md diff --git a/docfx/docfx.json b/docfx/docfx.json index d51b29ad..12e84f05 100644 --- a/docfx/docfx.json +++ b/docfx/docfx.json @@ -38,6 +38,7 @@ "globalMetadata": { "_appName": "Archipelago.MultiClient.Net", "_appTitle": "Archipelago.MultiClient.Net", + "_appLogoPath": "https://github.com/ArchipelagoMW/Archipelago/blob/main/WebHostLib/static/static/branding/header-logo.svg", "_enableSearch": true, "pdf": false } diff --git a/docfx/docs/datastore.md b/docfx/docs/helpers/datastore.md similarity index 100% rename from docfx/docs/datastore.md rename to docfx/docs/helpers/datastore.md diff --git a/docfx/docs/events.md b/docfx/docs/helpers/events.md similarity index 81% rename from docfx/docs/events.md rename to docfx/docs/helpers/events.md index a9f20c2c..270a0479 100644 --- a/docfx/docs/events.md +++ b/docfx/docs/helpers/events.md @@ -1,11 +1,14 @@ - -# Event Hooks +# Event Hooks -If using .net 4.0 or higher, you can use `ConnectAsync` and `LoginAsync` to prevent hitching for injection-based implementations like harmony. +If using .net 4.0 or higher, you can use `ConnectAsync` and `LoginAsync` to prevent hitching for injection-based +implementations like harmony. ## Message Logging -The Archipelago server can send messages to client to be displayed on screen as sort of a log, this is done by handling the `PrintJsonPacket` packets. This library simplifies this process into a single handler for you to handle. +The Archipelago server can send messages to client to be displayed on screen as a sort of log, this is done by handling +the `PrintJsonPacket` packets. This library simplifies this process into a @" +Archipelago.MultiClient.Net.Helpers.IMessageLogHelper?text='single handler'". + ```csharp var session = ArchipelagoSessionFactory.CreateSession("localhost", 38281); session.MessageLog.OnMessageReceived += OnMessageReceived; @@ -41,12 +44,13 @@ static void OnMessageReceived(LogMessage message) } ``` -If you want more control over how the message is displayed, like for example you might want to color certain parts of the message, -Then you can use the `Parts` property. This returns each part of the message in order of appearnce with the `Text` to be displayed and also the `Color` it would normally be diplayed in. +If you want more control over how the message is displayed, like for example you might want to color certain parts of +the message, +Then you can use the `Parts` property. This returns each part of the message in order of appearnce with the `Text` to be +displayed and also the `Color` it would normally be diplayed in. If `IsBackgroundColor` is true, then the color should be applied to the message background instead. The MessagePart message can also contain additional information that can be retrieved by type checking. - ```csharp foreach (part in message.Parts) { diff --git a/docfx/docs/helpers.md b/docfx/docs/helpers/helpers.md similarity index 56% rename from docfx/docs/helpers.md rename to docfx/docs/helpers/helpers.md index b683f9ad..ee3c0a38 100644 --- a/docfx/docs/helpers.md +++ b/docfx/docs/helpers/helpers.md @@ -13,23 +13,15 @@ session.MessageLog // Interface for the server to push info messages to the ## Players -The player helper provides methods for accessing details about the other players currently connected to the Archipelago +The @"Archipelago.MultiClient.Net.Helpers.IPlayerHelper?text='Player Helper'" provides methods for accessing details +about the other players currently connected to the Archipelago session. -### Get All Player Names - -```csharp -var sortedPlayerNames = session.Players.AllPlayers.Select(x => x.Name).OrderBy(x => x); -``` - -### Get Current Player Name - -```csharp -string playerName = session.Players.GetPlayerAliasAndName(session.ConnectionInfo.Slot); -``` - ## Locations +The @"Archipelago.MultiClient.Net.Helpers.ILocationCheckHelper?text='Locations Helper'" provides methods for accessing +information regarding the current player's locations, as well as updating the server on the status of their locations. + ### Report Collected Location(s) Call the following method to inform the server of locations whose items have been "found", and therefore should be @@ -45,43 +37,20 @@ session.Locations.CompleteLocationChecks(3); The location ID used is of that defined in the AP world. -### Location ID <--> Name - -```csharp -string locationName = session.Locations.GetLocationNameFromId(42) ?? $"Location: {locationId}"; -long locationId = session.Locations.GetLocationIdFromName(locationName); -``` - ### Scout Location Checks -Scouting means asking the server what is stored in a specific location *without* collecting it: +Scouting means asking the server what is stored in a specific location *without* collecting it. This can also be +utilized in order to create a hint, if - for instance - the current player knows what is on the location to inform other +players of this knowledge. ```csharp -session.Locations.ScoutLocationsAsync(locationInfoPacket => Console.WriteLine(locationInfoPacket.Locations.Count)); +session.Locations.ScoutLocationsAsync(locationInfoPacket => Console.WriteLine(locationInfoPacket.Locations.Count), HintCreationPolicy.CreateAndAnnounceOnce, new []{4, 5}); ``` ## Items -### Item ID --> Name - -```csharp -string itemName = session.Items.GetItemName(88) ?? $"Item: {itemId}"; -``` - -### Access Received Items - -At any time, you can access the current inventory for the active session/slot via the `Items` helper like so: - -```csharp -foreach(NetworkItem item in session.Items.AllItemsReceived) -{ - long itemId = item.Item; -} -``` - -*Note: The list of received items will never shrink and the collection is guaranteed to be in the order that the server -sent the items. Because of this, it is safe to assume that if the size of this collection has changed it's because new -items were received and appended to the end of the collection.* +The @"Archipelago.MultiClient.Net.Helpers.IReceivedItemsHelper?text='Received Items Helper'" provides methods for +checking the player's current inventory, and receiving items from the server. ### Received Item Callback Handler (Asynchronous) @@ -100,9 +69,9 @@ session.Items.ItemReceived += (receivedItemsHelper) => { ## RoomState -The RoomState helper provides access to values that represent the current state of the multiworld room, with information -such as the cost of a hint and or your current accumulated amount of hint point or the permissions for things like -forfeiting +The @"Archipelago.MultiClient.Net.Helpers.IRoomStateHelper?text='RoomState helper'" provides access to values that +represent the current state of the multiworld room, with information such as the cost of a hint and or your current +accumulated amount of hint point or the permissions for things like forfeiting. ```csharp Console.WriteLine($"You have {session.RoomState.HintPoints}, and need {session.RoomState.HintCost} for a hint"); @@ -110,8 +79,9 @@ Console.WriteLine($"You have {session.RoomState.HintPoints}, and need {session.R ## ConnectionInfo -The ConnectionInfo helper provides access to values under which you are currently connected, such as your slot number or -your currently used tags and item handling flags +The @"Archipelago.MultiClient.Net.Helpers.IConnectionInfoProvider?text='ConnectionInfo helper'" provides access to +values under which you are currently connected, such as your slot number or your currently used tags and item handling +flags. ```csharp Console.WriteLine($"You are connected on slot {session.ConnectionInfo.Slot}, on team {session.ConnectionInfo.Team}"); @@ -119,15 +89,23 @@ Console.WriteLine($"You are connected on slot {session.ConnectionInfo.Slot}, on ## ArchipelagoSocket -The socket helper is a lower level API allowing for direct access to the socket which the session object uses to -communicate with the Archipelago server. You may use this object to hook onto when messages are received, or you may use -it to send any packets defined in the library. Various events are exposed to allow for receipt of errors or notifying of -socket close. +The @"Archipelago.MultiClient.Net.Helpers.IConnectionInfoProvider?text='socket helper'" is a lower level API allowing +for direct access to the socket which the session object uses to communicate with the Archipelago server. You may use +this object to hook onto when messages are received, or you may use it to send any packets defined in the library. +Various events are exposed to allow for receipt of errors or notifying of socket close. ```csharp session.Socket.SendPacket(new SayPacket(){Text = "Woof woof!"}); ``` +## MessageLog + +The Archipelago server can send messages to client to be displayed on screen as a sort of log, this is done by handling +the `PrintJsonPacket` packets. This library simplifies this process into a +@"Archipelago.MultiClient.Net.Helpers.IMessageLogHelper?text='single handler'" that can be subscribed to with an +[event hook](docs/events.md). + + ## DeathLink DeathLink support is included in the library. You may enable it by using the `CreateDeathLinkService` in the diff --git a/docfx/docs/helpers/players.md b/docfx/docs/helpers/players.md new file mode 100644 index 00000000..e69de29b diff --git a/docfx/docs/toc.yml b/docfx/docs/toc.yml index 3e36d5f7..b61cf7f9 100644 --- a/docfx/docs/toc.yml +++ b/docfx/docs/toc.yml @@ -5,7 +5,7 @@ items: - href: quick-start.md - name: Helpers items: - - href: helpers.md - - href: events.md - - href: datastore.md + - href: helpers/helpers.md + - href: helpers/events.md + - href: helpers/datastore.md - href: packets.md From defd67bbaccea657c13193cb9b4053057b859ea2 Mon Sep 17 00:00:00 2001 From: alwaysintreble Date: Thu, 27 Feb 2025 15:08:44 -0600 Subject: [PATCH 07/17] add the AP logo --- docfx/docfx.json | 2 +- docfx/img/logo/LICENSE.txt | 1 + docfx/img/logo/color-icon.svg | 43 +++++++++++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 docfx/img/logo/LICENSE.txt create mode 100644 docfx/img/logo/color-icon.svg diff --git a/docfx/docfx.json b/docfx/docfx.json index 12e84f05..589e8631 100644 --- a/docfx/docfx.json +++ b/docfx/docfx.json @@ -38,7 +38,7 @@ "globalMetadata": { "_appName": "Archipelago.MultiClient.Net", "_appTitle": "Archipelago.MultiClient.Net", - "_appLogoPath": "https://github.com/ArchipelagoMW/Archipelago/blob/main/WebHostLib/static/static/branding/header-logo.svg", + "_appLogoPath": "img/logo/color-icon.svg", "_enableSearch": true, "pdf": false } diff --git a/docfx/img/logo/LICENSE.txt b/docfx/img/logo/LICENSE.txt new file mode 100644 index 00000000..24bc1fb9 --- /dev/null +++ b/docfx/img/logo/LICENSE.txt @@ -0,0 +1 @@ +This work © 2022 by Krista Corkos and Christopher Wilson is licensed under Attribution-NonCommercial 4.0 International. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/4.0/ \ No newline at end of file diff --git a/docfx/img/logo/color-icon.svg b/docfx/img/logo/color-icon.svg new file mode 100644 index 00000000..8cfd65b9 --- /dev/null +++ b/docfx/img/logo/color-icon.svg @@ -0,0 +1,43 @@ + + + + + + + + + + + + + From c374ec24ed199c1be6387ee6ec492602b430cf77 Mon Sep 17 00:00:00 2001 From: alwaysintreble Date: Thu, 27 Feb 2025 15:16:50 -0600 Subject: [PATCH 08/17] fix and add some links --- docfx/docs/helpers/helpers.md | 28 +++++++++++++++------------- docfx/index.md | 4 ++-- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/docfx/docs/helpers/helpers.md b/docfx/docs/helpers/helpers.md index ee3c0a38..d9c4b985 100644 --- a/docfx/docs/helpers/helpers.md +++ b/docfx/docs/helpers/helpers.md @@ -13,13 +13,13 @@ session.MessageLog // Interface for the server to push info messages to the ## Players -The @"Archipelago.MultiClient.Net.Helpers.IPlayerHelper?text='Player Helper'" provides methods for accessing details +The @"Archipelago.MultiClient.Net.Helpers.IPlayerHelper?text=Player Helper" provides methods for accessing details about the other players currently connected to the Archipelago session. ## Locations -The @"Archipelago.MultiClient.Net.Helpers.ILocationCheckHelper?text='Locations Helper'" provides methods for accessing +The @"Archipelago.MultiClient.Net.Helpers.ILocationCheckHelper?text=Locations Helper" provides methods for accessing information regarding the current player's locations, as well as updating the server on the status of their locations. ### Report Collected Location(s) @@ -49,7 +49,7 @@ session.Locations.ScoutLocationsAsync(locationInfoPacket => Console.WriteLine(lo ## Items -The @"Archipelago.MultiClient.Net.Helpers.IReceivedItemsHelper?text='Received Items Helper'" provides methods for +The @"Archipelago.MultiClient.Net.Helpers.IReceivedItemsHelper?text=Received Items Helper" provides methods for checking the player's current inventory, and receiving items from the server. ### Received Item Callback Handler (Asynchronous) @@ -69,7 +69,7 @@ session.Items.ItemReceived += (receivedItemsHelper) => { ## RoomState -The @"Archipelago.MultiClient.Net.Helpers.IRoomStateHelper?text='RoomState helper'" provides access to values that +The @"Archipelago.MultiClient.Net.Helpers.IRoomStateHelper?text=RoomState Helper" provides access to values that represent the current state of the multiworld room, with information such as the cost of a hint and or your current accumulated amount of hint point or the permissions for things like forfeiting. @@ -79,7 +79,7 @@ Console.WriteLine($"You have {session.RoomState.HintPoints}, and need {session.R ## ConnectionInfo -The @"Archipelago.MultiClient.Net.Helpers.IConnectionInfoProvider?text='ConnectionInfo helper'" provides access to +The @"Archipelago.MultiClient.Net.Helpers.IConnectionInfoProvider?text=ConnectionInfo Helper" provides access to values under which you are currently connected, such as your slot number or your currently used tags and item handling flags. @@ -89,7 +89,7 @@ Console.WriteLine($"You are connected on slot {session.ConnectionInfo.Slot}, on ## ArchipelagoSocket -The @"Archipelago.MultiClient.Net.Helpers.IConnectionInfoProvider?text='socket helper'" is a lower level API allowing +The @"Archipelago.MultiClient.Net.Helpers.IConnectionInfoProvider?text=Socket Helper" is a lower level API allowing for direct access to the socket which the session object uses to communicate with the Archipelago server. You may use this object to hook onto when messages are received, or you may use it to send any packets defined in the library. Various events are exposed to allow for receipt of errors or notifying of socket close. @@ -102,25 +102,27 @@ session.Socket.SendPacket(new SayPacket(){Text = "Woof woof!"}); The Archipelago server can send messages to client to be displayed on screen as a sort of log, this is done by handling the `PrintJsonPacket` packets. This library simplifies this process into a -@"Archipelago.MultiClient.Net.Helpers.IMessageLogHelper?text='single handler'" that can be subscribed to with an -[event hook](docs/events.md). - +@"Archipelago.MultiClient.Net.Helpers.IMessageLogHelper?text=single handler" that can be subscribed to with an +[event hook](docs/helpers/events.md). ## DeathLink -DeathLink support is included in the library. You may enable it by using the `CreateDeathLinkService` in the -`DeathLinkProvider` class, and the `EnableDeathlink` method on the service. Deathlink can be toggled on and off using -the `EnableDeathlink` and `DisableDeathlink` methods on the service. +DeathLink support is included in the library. You may enable it by creating a new +@"Archipelago.MultiClient.Net.BounceFeatures.DeathLink.DeathLinkService?text=DeathLinkService" from the +@"Archipelago.MultiClient.Net.BounceFeatures.DeathLink.DeathLinkProvider?text=DeathLinkProvider`, and subscribing to the +`OnDeathLinkReceived` event. Deathlink can then be toggled on and off using the `EnableDeathlink` and `DisableDeathlink` +methods on the service. ```csharp var session = ArchipelagoSessionFactory.CreateSession("localhost", 38281); -var deathLinkService = session.CreateDeathLinkService().EnableDeathlink(); +var deathLinkService = session.CreateDeathLinkService(); deathLinkService.OnDeathLinkReceived += (deathLinkObject) => { // ... Kill your player(s). }; +deathLinkService.EnableDeathlink(); // ... On death: deathLinkService.SendDeathLink(new DeathLink("Ijwu", "Died to exposure.")); ``` diff --git a/docfx/index.md b/docfx/index.md index 4da8b943..9c00cc1c 100644 --- a/docfx/index.md +++ b/docfx/index.md @@ -18,11 +18,11 @@ time. The @"Archipelago.MultiClient.Net.ArchipelagoSession?text=ArchipelagoSession" is the basis of all operations involved with communicating with the Archipelago server. Before any communicating can be executed, a new session must be created, -and any relevant [event hooks](docs/events.md) should be registered before attempting a connection. +and any relevant [event hooks](docs/helpers/events.md) should be registered before attempting a connection. ### Helpers -There exist many [helper classes and methods](docs/helpers.md) to help digest the information received from the server +There exist many [helper classes and methods](docs/helpers/helpers.md) to help digest the information received from the server into specific formats, or to send specific information to the server. If a helper doesn't do what you need, the raw server data is also available to do what is needed through the @"Archipelago.MultiClient.Net.Helpers.IArchipelagoSocketHelper?text=Session.Socket". From 71d8385c448730eedfc23bc53472367b012d778f Mon Sep 17 00:00:00 2001 From: alwaysintreble Date: Thu, 27 Feb 2025 15:20:51 -0600 Subject: [PATCH 09/17] make sure to copy over the image directory --- docfx/docfx.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docfx/docfx.json b/docfx/docfx.json index 589e8631..a463c9f2 100644 --- a/docfx/docfx.json +++ b/docfx/docfx.json @@ -26,7 +26,7 @@ "resource": [ { "files": [ - "images/**" + "img/**" ] } ], From 8ba74baeea00ea3234af82ab8d3123d1376f045b Mon Sep 17 00:00:00 2001 From: alwaysintreble Date: Thu, 27 Feb 2025 15:32:09 -0600 Subject: [PATCH 10/17] hard set width and height since docfx doesn't --- docfx/img/logo/color-icon.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docfx/img/logo/color-icon.svg b/docfx/img/logo/color-icon.svg index 8cfd65b9..c9c7f614 100644 --- a/docfx/img/logo/color-icon.svg +++ b/docfx/img/logo/color-icon.svg @@ -1,7 +1,7 @@ + width="38pt" height="38pt" viewBox="0 0 2034 2112" style="enable-background:new 0 0 2034 2112;" xml:space="preserve">