morgan/Grinch-AP
1
0
Fork 0
mirror of https://github.com/MarioSpore/Grinch-AP.git synced 2025-10-21 20:21:32 -06:00
Code Issues Packages Projects Releases Wiki Activity

Network: implement read_only datastore keys: hints and slot_data (#1286)

Browse Source 
Co-authored-by: black-sliver <59490463+black-sliver@users.noreply.github.com>
This commit is contained in:
Fabian Dill
2022-12-03 23:29:33 +01:00
committed by GitHub
parent 64e2d55e92
commit 65995cd586
4 changed files with 139 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
docs/network protocol.md
View File

@@ -121,15 +121,15 @@ InvalidItemsHandling indicates a wrong value type or flag combination was sent.
### Connected
Sent to clients when the connection handshake is successfully completed.
#### Arguments
| Name | Type | Notes |
| ---- | ---- | ----- |
| team | int | Your team number. See [NetworkPlayer](#NetworkPlayer) for more info on team number. |
| slot | int | Your slot number on your team. See [NetworkPlayer](#NetworkPlayer) for more info on the slot number. |
| players | list\[[NetworkPlayer](#NetworkPlayer)\] | List denoting other players in the multiworld, whether connected or not. |
| missing_locations | list\[int\] | Contains ids of remaining locations that need to be checked. Useful for trackers, among other things. |
| checked_locations | list\[int\] | Contains ids of all locations that have been checked. Useful for trackers, among other things. Location ids are in the range of ± 2<sup>53</sup>-1. |
| slot_data | dict | Contains a json object for slot related data, differs per game. Empty if not required. |
| slot_info | dict\[int, [NetworkSlot](#NetworkSlot)\] | maps each slot to a [NetworkSlot](#NetworkSlot) information |
| Name | Type | Notes |
|-------------------|------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| team | int | Your team number. See [NetworkPlayer](#NetworkPlayer) for more info on team number. |
| slot | int | Your slot number on your team. See [NetworkPlayer](#NetworkPlayer) for more info on the slot number. |
| players | list\[[NetworkPlayer](#NetworkPlayer)\] | List denoting other players in the multiworld, whether connected or not. |
| missing_locations | list\[int\] | Contains ids of remaining locations that need to be checked. Useful for trackers, among other things. |
| checked_locations | list\[int\] | Contains ids of all locations that have been checked. Useful for trackers, among other things. Location ids are in the range of ± 2<sup>53</sup>-1. |
| slot_data | dict | Contains a json object for slot related data, differs per game. Empty if not required. Not present if slot_data in [Connect](#Connect) is false. |
| slot_info | dict\[int, [NetworkSlot](#NetworkSlot)\] | maps each slot to a [NetworkSlot](#NetworkSlot) information |
### ReceivedItems
Sent to clients when they receive an item.
@@ -242,11 +242,11 @@ Additional arguments added to the [Get](#Get) package that triggered this [Retri
### SetReply
Sent to clients in response to a [Set](#Set) package if want_reply was set to true, or if the client has registered to receive updates for a certain key using the [SetNotify](#SetNotify) package. SetReply packages are sent even if a [Set](#Set) package did not alter the value for the key.
#### Arguments
| Name | Type | Notes |
| ---- | ---- | ----- |
| key | str | The key that was updated. |
| value | any | The new value for the key. |
| original_value | any | The value the key had before it was updated. |
| Name | Type | Notes |
|----------------|------|--------------------------------------------------------------------------------------------|
| key | str | The key that was updated. |
| value | any | The new value for the key. |
| original_value | any | The value the key had before it was updated. Not present on "_read" prefixed special keys. |
Additional arguments added to the [Set](#Set) package that triggered this [SetReply](#SetReply) will also be passed along.
@@ -269,15 +269,16 @@ These packets are sent purely from client to server. They are not accepted by cl
Sent by the client to initiate a connection to an Archipelago game session.
#### Arguments
| Name | Type | Notes |
| ---- | ---- | ----- |
| password | str | If the game session requires a password, it should be passed here. |
| game | str | The name of the game the client is playing. Example: `A Link to the Past` |
| name | str | The player name for this client. |
| uuid | str | Unique identifier for player client. |
| version | [NetworkVersion](#NetworkVersion) | An object representing the Archipelago version this client supports. |
| items_handling | int | Flags configuring which items should be sent by the server. Read below for individual flags. |
| tags | list\[str\] | Denotes special features or capabilities that the sender is capable of. [Tags](#Tags) |
| Name | Type | Notes |
|----------------|-----------------------------------|----------------------------------------------------------------------------------------------|
| password | str | If the game session requires a password, it should be passed here. |
| game | str | The name of the game the client is playing. Example: `A Link to the Past` |
| name | str | The player name for this client. |
| uuid | str | Unique identifier for player client. |
| version | [NetworkVersion](#NetworkVersion) | An object representing the Archipelago version this client supports. |
| items_handling | int | Flags configuring which items should be sent by the server. Read below for individual flags. |
| tags | list\[str\] | Denotes special features or capabilities that the sender is capable of. [Tags](#Tags) |
| slot_data | bool | If true, the Connect answer will contain slot_data |
#### items_handling flags
| Value | Meaning |
@@ -366,15 +367,22 @@ Used to request a single or multiple values from the server's data storage, see
| keys | list\[str\] | Keys to retrieve the values for. |
Additional arguments sent in this package will also be added to the [Retrieved](#Retrieved) package it triggers.
Some special keys exist with specific return data:
| Name | Type | Notes |
|----------------------------|-----------------------|----------------------------------------------|
| \_read_hints_{team}_{slot} | list\[[Hint](#Hint)\] | All Hints belonging to the requested Player. |
| \_read_slot_data_{slot} | any | slot_data belonging to the requested slot. |
### Set
Used to write data to the server's data storage, that data can then be shared across worlds or just saved for later. Values for keys in the data storage can be retrieved with a [Get](#Get) package, or monitored with a [SetNotify](#SetNotify) package.
#### Arguments
| Name | Type | Notes |
| ------ | ----- | ------ |
| key | str | The key to manipulate. |
| default | any | The default value to use in case the key has no value on the server. |
| want_reply | bool | If true, the server will send a [SetReply](#SetReply) response back to the client. |
| Name | Type | Notes |
|------------|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| key | str | The key to manipulate. Can never start with "_read". |
| default | any | The default value to use in case the key has no value on the server. |
| want_reply | bool | If true, the server will send a [SetReply](#SetReply) response back to the client. |
| operations | list\[[DataStorageOperation](#DataStorageOperation)\] | Operations to apply to the value, multiple operations can be present and they will be executed in order of appearance. |
Additional arguments sent in this package will also be added to the [SetReply](#SetReply) package it triggers.
@@ -591,6 +599,20 @@ class Permission(enum.IntEnum):
auto_enabled = 0b111 # 7, forces use after goal completion, allows manual use any time
```
### Hint
An object representing a Hint.
```python
import typing
class Hint(typing.NamedTuple):
receiving_player: int
finding_player: int
location: int
item: int
found: bool
entrance: str = ""
item_flags: int = 0
```
### Data Package Contents
A data package is a JSON object which may contain arbitrary metadata to enable a client to interact with the Archipelago server most easily. Currently, this package is used to send ID to name mappings so that clients need not maintain their own mappings.