Skip to content

Commit

Permalink
docs: improving docs on syncvar hooks
Browse files Browse the repository at this point in the history
  • Loading branch information
James-Frowen committed Jan 24, 2024
1 parent f84c578 commit 622d5ce
Show file tree
Hide file tree
Showing 7 changed files with 65 additions and 12 deletions.
2 changes: 1 addition & 1 deletion doc/docs/guides/sync/code-generation.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 6
sidebar_position: 7
---
# Code Generation

Expand Down
2 changes: 1 addition & 1 deletion doc/docs/guides/sync/custom-serialization.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 7
sidebar_position: 8
---
# Advanced Synchronization

Expand Down
2 changes: 1 addition & 1 deletion doc/docs/guides/sync/serialization-flow.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 5
sidebar_position: 6
---
## Serialization Flow

Expand Down
4 changes: 2 additions & 2 deletions doc/docs/guides/sync/sync-objects/_category_.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"label": "Sync Objects",
"position": 3
}
"position": 4
}
2 changes: 1 addition & 1 deletion doc/docs/guides/sync/sync-settings.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 4
sidebar_position: 5
---
# Sync Settings

Expand Down
57 changes: 57 additions & 0 deletions doc/docs/guides/sync/sync-var-hooks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
sidebar_position: 3
---
# Sync Var Hooks

`SyncVar` can have hooks that are invoked when the values changes.

Hooks are set using the `hook` option on the `SyncVar` attribute, the hook needs to be in the same class as the `SyncVar`

```cs
[SyncVar(hook = nameof(HookName))]
```


A hook can be a method or a event, when using an event it should use `System.Action`.

The hook can have 0, 1 or 2 args.



```cs
void hook0() { }

void hook1(int newValue) { }

void hook2(int oldValue, int newValue) { }

event Action event0;

event Action<int> event1;

event Action<int, int> event2;
```


## When is hook invoked?

The following is a list of rules that SyncVar hooks follows for when and where they are invoked:

- Hook only invoked if value is changed

- When settings SyncVar
- both flags false
- invokes if host (both Server AND client active)
- `invokeHookOnOwner` flag true
- invokes if owner
- `invokeHookOnServer` flag true
- invokes if server (includes host mode)
- both flags true
- invokes if owner OR server

- `DeserializeSyncVars` is never called on host sending update to itself, but is called when owner sends update to server

- hooks are invoked in `DeserializeSyncVars` if values changes
- always invokes if Only client (eg not host mode)
- `invokeHookOnServer`
- invokes on server (eg when an change is send from owner)
8 changes: 2 additions & 6 deletions doc/docs/guides/sync/sync-var.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,13 +72,9 @@ Both `Cat` and `Pet` should be in the same assembly. If they are in separate ass
:::

## SyncVar hook
The `hook` property of SyncVar can be used to specify a function to be called when the SyncVar changes value on the client and server.
The `hook` option of SyncVar attribute can be used to specify a function to be called when the SyncVar changes value on the client and server.

**Trivia:**
- The hook callback must have two parameters of the same type as the SyncVar property. One for the old value, one for the new value.
- The hook is always called after the SyncVar value is set. You don't need to set it yourself.
- The hook only fires for changed values, and changing a value in the inspector will not trigger an update.
- Hooks can be virtual methods and overridden in a derived class.
For more information on SyncVar hooks see [Sync Var Hooks](/docs/guides/sync/sync-var-hooks)

### Example Client Only
Below is a simple example of assigning a random color to each player when they're spawned on the server. All clients will see all players in the correct colors, even if they join later.
Expand Down

0 comments on commit 622d5ce

Please sign in to comment.