[Docs] Datastorage (#333)
This commit is contained in:
Jarno Westhof
GitHub
parent
e4ab10fe92
commit
8599506497
|
|
@ -49,6 +49,8 @@ These packets are are sent from the multiworld server to the client. They are no
|
|||
* [DataPackage](#DataPackage)
|
||||
* [Bounced](#Bounced)
|
||||
* [InvalidPacket](#InvalidPacket)
|
||||
* [Retrieved](#Retrieved)
|
||||
* [SetReply](#SetReply)
|
||||
|
||||
### RoomInfo
|
||||
Sent to clients when they connect to an Archipelago server.
|
||||
|
|
@ -191,11 +193,26 @@ Sent to clients after a client requested this message be sent to them, more info
|
|||
### InvalidPacket
|
||||
Sent to clients if the server caught a problem with a packet. This only occurs for errors that are explicitly checked for.
|
||||
|
||||
### Retrieved
|
||||
Sent to clients as a response the a [Get](#Get) package
|
||||
#### Arguments
|
||||
| Name | Type | Notes |
|
||||
| ---- | ---- | ----- |
|
||||
| type | string | "cmd" if the Packet isn't available/allowed, "arguments" if the problem is with the package data. |
|
||||
| text | string | Error text explaining the caught error. |
|
||||
| original_cmd | string | Echoes the cmd it failed on. May be null if the cmd was not found.
|
||||
| keys | dict\[str\, any] | A key-value collection containing all the values for the keys requested in the [Get](#Get) package. |
|
||||
|
||||
Additional arguments added to the [Get](#Get) package that triggered this [Retrieved](#Retrieved) will also be passed along.
|
||||
|
||||
### 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. |
|
||||
|
||||
Additional arguments added to the [Set](#Set) package that triggered this [SetReply](#SetReply) will also be passed along.
|
||||
|
||||
## (Client -> Server)
|
||||
These packets are sent purely from client to server. They are not accepted by clients.
|
||||
|
||||
|
|
@ -207,6 +224,9 @@ These packets are sent purely from client to server. They are not accepted by cl
|
|||
* [Say](#Say)
|
||||
* [GetDataPackage](#GetDataPackage)
|
||||
* [Bounce](#Bounce)
|
||||
* [Get](#Get)
|
||||
* [Set](#Set)
|
||||
* [SetNotify](#SetNotify)
|
||||
|
||||
### Connect
|
||||
Sent by the client to initiate a connection to an Archipelago game session.
|
||||
|
|
@ -301,6 +321,58 @@ the server will forward the message to all those targets to which any one requir
|
|||
| tags | list\[str\] | Optional. Client tags that should receive this message |
|
||||
| data | dict | Any data you want to send |
|
||||
|
||||
### Get
|
||||
Used to request a single or multiple values from the server's data storage, see the [Set](#Set) package for how to write values to the data storage. A Get package will be answered with a [Retrieved](#Retrieved) package.
|
||||
#### Arguments
|
||||
| Name | Type | Notes |
|
||||
| ------ | ----- | ------ |
|
||||
| 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.
|
||||
|
||||
### 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. |
|
||||
| value | any | The new value for the key. |
|
||||
| default | any | The default value to use in case the key has no value on the server. |
|
||||
| want_reply | bool | If set, 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.
|
||||
|
||||
#### DataStorageOperation
|
||||
A DataStorageOperation manipulates or alters the value of a key in the data storage. If the operation transforms the value from one state to another then the current value of the key is used as the starting point otherwise the [Set](#Set)'s package `default` is used if the key does not exist on the server already.
|
||||
DataStorageOperations consist of an object containing both the operation to be applied, provided in the form of a string, as well as the value to be used for that operation, Example:
|
||||
```js
|
||||
{"operation": "add", "value": 12}
|
||||
```
|
||||
|
||||
The following operations can be applied to a datastorage key
|
||||
| Operation | Effect |
|
||||
| ------ | ----- |
|
||||
| replace | Sets the current value of the key to `value`. |
|
||||
| default | If the key has no value yet, sets the current value of the key to `default` of the [Set](#Set)'s package (`value` is ignored). |
|
||||
| add | Adds `value` to the current value of the key, if both the current value and `value` are arrays then `value` will be appended to the current value. |
|
||||
| mul | Multiplies the current value of the key by `value`. |
|
||||
| pow | Multiplies the current value of the key to the power of `value`. |
|
||||
| mod | Sets the current value of the key to the remainder after division by `value`. |
|
||||
| max | Sets the current value of the key to `value` if `value` is bigger. |
|
||||
| min | Sets the current value of the key to `value` if `value` is lower. |
|
||||
| and | Applies a bitwise AND to the current value of the key with `value`. |
|
||||
| or | Applies a bitwise OR to the current value of the key with `value`. |
|
||||
| xor | Applies a bitwise Exclusive OR to the current value of the key with `value`. |
|
||||
| left_shift | Applies a bitwise left-shift to the current value of the key by `value`. |
|
||||
| right_shift | Applies a bitwise right-shift to the current value of the key by `value`. |
|
||||
|
||||
### SetNotify
|
||||
Used to register your current session for receiving all [SetReply](#SetReply) packages of certain keys to allow your client to keep track of changes.
|
||||
#### Arguments
|
||||
| Name | Type | Notes |
|
||||
| ------ | ----- | ------ |
|
||||
| keys | list\[str\] | Keys to receive all [SetReply](#SetReply) packages for. |
|
||||
|
||||
## Appendix
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue