From a097d31ed7b2742ce6f62b6cb778f191ac680fc5 Mon Sep 17 00:00:00 2001 From: James Frowen Date: Fri, 21 Jul 2023 13:49:05 +0100 Subject: [PATCH] docs: updating docs on Attributes in mirage --- doc/docs/guides/attributes.md | 69 +++++++++++++++++++++++++++++------ 1 file changed, 58 insertions(+), 11 deletions(-) diff --git a/doc/docs/guides/attributes.md b/doc/docs/guides/attributes.md index bdbf38979d3..a87a6863419 100644 --- a/doc/docs/guides/attributes.md +++ b/doc/docs/guides/attributes.md @@ -3,21 +3,23 @@ sidebar_position: 4 --- # Attributes -Networking attributes are added to member functions of [NetworkBehaviour](/docs/reference/Mirage/NetworkBehaviour) -scripts, to make them run on either the client or server. +Networking attributes are added to member of [NetworkBehaviour](/docs/reference/Mirage/ +NetworkBehaviour) scripts to tell Mirage to do different things. -These attributes can be used for Unity game loop methods like `Start` or `Update`, as well as other implemented methods. +There are 4 types of attributes that Mirage has: +- [Rpc Attributes](#RPC Attributes): Cause a method to send a network message so that the body of the method is invoked on a either server or client +- [Block methods invokes](#Block methods invokes): Blocks invokes of a method to stop them from being invoked in wrong place +- [SyncVar](/docs/guides/sync/sync-var): Add to Fields to cause their value to be automatically synced to clients. +- [Bit Packing](/docs/guides/bit-packing): These attributes modify how values are written, they are an easy way to tell mirage how to compress values before they are sent over network. They can be applied to Fields and method Parameters. + +## RPC Attributes + +Full details on RPC can be found on the [Remote Actions](/docs/guides/remote-actions) page. :::note When using abstract or virtual methods the attributes need to be applied to the override methods too. ::: -- **[ServerAttribute](/docs/reference/Mirage/ServerAttribute)** - Only a server can call the method (throws an error when called on a client unless you specify `error = false`). - -- **[ClientAttribute](/docs/reference/Mirage/ClientAttribute)** - Only a client can call the method (throws an error when called on the server unless you specify `error = false`). - - **[ClientRpcAttribute](/docs/reference/Mirage/ClientAttribute)** The server uses a Remote Procedure Call (RPC) to run that function on clients. It has a `target` option allowing you to specify in which clients it should be executed, along with a `channel` option. @@ -28,5 +30,50 @@ When using abstract or virtual methods the attributes need to be applied to the It's not possible to call this from a server. Use this as a wrapper around another function, if you want to call it from the server too. Note that you can also return value from it. See also: [ServerRpc](/docs/guides/remote-actions/server-rpc) -- **[SyncVar](/docs/guides/sync/sync-var)** - SyncVars are used to synchronize a variable from the server to all clients automatically. \ No newline at end of file + +## Block methods invokes + +These attributes can be added to methods to block them from being invoked in the wrong place. These attributes can only be used on `NetworkBehaviour` classes, and only work correctly if the object is spawned. otherwise flags like `IsServer` will be false. + +By default these methods will throw [MethodInvocationException](/docs/reference/Mirage/MethodInvocationException). You can add `error = false` to return instead of throw. + +:::note +When returning early the method will return default values for return value or for out param +::: + +These attributes can be used for Unity game loop methods like `Start` or `Update`, as well as other implemented methods. + + +- **[ServerAttribute](/docs/reference/Mirage/ServerAttribute)** + Methods can only be invoked on Server + +- **[ClientAttribute](/docs/reference/Mirage/ClientAttribute)** + Methods can only be invoked on Client + +- **[HasAuthorityAttribute](/docs/reference/Mirage/HasAuthorityAttribute)** + Methods can only be invoked on Client, when HasAuthority is true. See: [Authority](/docs/guides/authority) + +- **[LocalPlayerAttribute](/docs/reference/Mirage/LocalPlayerAttribute)** + Methods can only be invoked on Client, when IsLocalPlayer is true. See: [Authority](/docs/guides/game-objects/spawn-player) + +- **[NetworkMethodAttribute](/docs/reference/Mirage/NetworkMethodAttribute)** + Method can only be invoked based on the flags set in the attribute. For example `NetworkFlags.Server | NetworkFlags.HasAuthority` can only be called on Server **OR** on client with Authority. + +#### Examples: + +```cs +[Server] +void SpawnCoin() +{ + // only allowed to be invoked on server +} +``` + +```cs +[NetworkMethod(NetworkFlags.Server | NetworkFlags.NotActive)] +public void StartGame() +{ + // this methods will run in server or single player mode + // it will only be blocks if only client is active +} +```