Skip to content

Commit

Permalink
Add docs for Shared Events
Browse files Browse the repository at this point in the history
  • Loading branch information
Tazmondo committed Jan 2, 2024
1 parent 8994ab5 commit 943c487
Show file tree
Hide file tree
Showing 9 changed files with 432 additions and 6 deletions.
3 changes: 3 additions & 0 deletions docs/.vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ function sidebar() {
{ text: 'Declaring Events', link: '/guide/events/declaring' },
{ text: 'Server Usage', link: '/guide/events/server' },
{ text: 'Client Usage', link: '/guide/events/client' },
{ text: 'Shared Events', link: '/guide/events/sharedevent' }
]
},
{
Expand All @@ -47,6 +48,8 @@ function sidebar() {
]
},
{ text: 'Function', link: '/2.0/Function' },
{ text: 'SharedEvent', link: '/2.0/SharedEvent' },
{ text: 'SharedSignalEvent', link: '/2.0/SharedSignalEvent' }
],
}
],
Expand Down
2 changes: 1 addition & 1 deletion docs/2.0/Event/Client.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Sets the event's listener.

```lua
<T...>(
Listener: (...T...) -> (), -- The listener
Listener: (T...) -> (), -- The listener
) -> ()
```

Expand Down
2 changes: 1 addition & 1 deletion docs/2.0/Event/Server.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ Sets the event's listener.

```lua
<T...>(
Function: (...: T...) -> (), -- The function to connect
Listener: (T...) -> (), -- The function to connect
) -> ()
```

Expand Down
4 changes: 2 additions & 2 deletions docs/2.0/Function.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Sets the function's callback.
```lua
<A..., R...>(
Callback: (Player, A...) -> R... -- The callback to set.
)
) -> ()
```

A singular callback must be set on the server to allow clients to call the function. This callback is given the arguments and must return the expected return values. This callback may only be set on the server, attempting to set it on the client will result in an error.
Expand All @@ -33,7 +33,7 @@ Calls the function on the server.
```lua
<A..., R...>(
...A: any -- The arguments to pass to the function.
): Future<R...>
) -> Future<R...>
```

A function is called on the client to call the function on the server. This method returns a [Future](https://util.redblox.dev/future) which can be used to await the return values or connect a function to be called when the return values are received.
Expand Down
62 changes: 62 additions & 0 deletions docs/2.0/Red.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,3 +72,65 @@ end)
::: tip
It is recommended to use [Guard](https://util.redblox.dev/guard) to typecheck as it also narrows types.
:::

## SharedEvent
Creates a new [SharedEvent](./SharedEvent) object.
```lua
<T...>(
Name: string | { Name: string, Unreliable: boolean? }, -- Event config
Validate: (...unknown) -> T... -- Validates event payloads
) -> SharedCallEvent<T...>
```
This will create a SharedEvent with the passed config.

If you pass a string, it will be used as the event name and the event will be reliable. If you pass a table you have the option to make the event unreliable.

::: danger
The name of the event must be unique, using the same name twice will result in an error.
:::

The validation function is used to validate the type of the payloads. The function has three rules:

1. The callback returns the arguments in the same order they were passed in.
2. The callback must error if the arguments are invalid.
3. The callback must narrow the types of the arguments.

```lua
return Red.SharedEvent("EventName", function(Number, String)
return Guard.Number(Number), Guard.String(String)
end)
```
::: tip
It is recommended to use [Guard](https://util.redblox.dev/guard) to typecheck as it also narrows types.
:::

## SharedSignalEvent
Creates a new [SharedSignalEvent](./SharedSignalEvent) object.
```lua
<T...>(
Name: string | { Name: string, Unreliable: boolean? }, -- Event config
Validate: (...unknown) -> T... -- Validates event payloads
) -> SharedSignalEvent<T...>
```
This will create a SharedSignalEvent with the passed config.

If you pass a string, it will be used as the event name and the event will be reliable. If you pass a table you have the option to make the event unreliable.

::: danger
The name of the event must be unique, using the same name twice will result in an error.
:::

The validation function is used to validate the type of the payloads. The function has three rules:

1. The callback returns the arguments in the same order they were passed in.
2. The callback must error if the arguments are invalid.
3. The callback must narrow the types of the arguments.

```lua
return Red.SharedSignalEvent("EventName", function(Number, String)
return Guard.Number(Number), Guard.String(String)
end)
```
::: tip
It is recommended to use [Guard](https://util.redblox.dev/guard) to typecheck as it also narrows types.
:::
110 changes: 110 additions & 0 deletions docs/2.0/SharedEvent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# SharedEvent
SharedEvents are built on the same backend networking as regular events. However, they do not require an explicit `:Server` or `:Client` call to use.

Unlike [SharedSignalEvents](SharedSignalEvent), only one listener may be set at any time. Setting a new listener will overwrite the previous one, if it existed.

## SetServerListener <Badge type="tip" text="Server"></Badge>
Sets the server callback.
```lua
<T...>(
Listener: (Player: Player, T...) -> () -- The listener to register
) -> ()
```
This method sets the server listener. Errors if called from the client.
```lua
MyEvent:SetServerListener(function(Player, Value)
print(Player, Value)
end)
```

## SetClientListener <Badge type="warning" text="Client"></Badge>
Sets the client callback.
```lua
<T...>(
Listener: (T...) -> () -- The listener to register
) -> ()
```
This method sets the client listener. Errors if called from the server.
```lua
MyEvent:SetClientListener(function(Value)
print(Value)
end)
```

## FireServer <Badge type="warning" text="Client"></Badge>
Fires the event to the server.
```lua
<T...>(
...: T... -- The event payload
) -> ()
```
This method fires the event to the server. Errors if called from the server.
```lua
MyEvent:FireServer("Hello, World!")
```

## FireClient <Badge type="tip" text="Server"></Badge>
Fires the event to a specific player.
```lua
<T...>(
Player: Player, -- The target player
...: T... -- The event payload
) -> ()
```
This method fires the event to a specific client. Errors if called from the client.
```lua
MyEvent:FireClient(player, "Hello, World!")
```

## FireAllClients <Badge type="tip" text="Server"></Badge>
Fires the event to all players.
```lua
<T...>(
...: T... -- The event payload
) -> ()
```
This method fires the event to all players. Errors if called from the client.
```lua
MyEvent:FireAllClients("Hello, World!")
```

## FireAllClientsExcept <Badge type="tip" text="Server"></Badge>
Fires the event to every player **except** one.
```lua
<T...>(
Player: Player, -- Player to be ignored
...: T... -- The event payload
)
```
This method fires the event to every player except one. Errors if called from the client.
```lua
MyEvent:FireAllClientsExcept(player, "Hello, World!")
```

## FireClients <Badge type="tip" text="Server"></Badge>
Fires the event to every player in the given list.
```lua
<T...>(
Players: { Player }, -- List of players to fire the event to
...: T... -- The event payload
) -> ()
```
This method fires the event to every player in the list. Errors if called from the client.
```lua
MyServer:FireClients({ player }, "Hello, World!")
```

## FireFilteredClients <Badge type="tip" text="Server"></Badge>
Fires the event to every player that passes the given filter function.
```lua
<T...>(
Filter: (Player) -> boolean -- Must return true for a player to receive the event.
...: T... -- The event payload
) -> ()
```
This method fires the event to every player that passes the filter. Errors if called from the client.
```lua
MyServer:FireFilteredClients(function(player)
return player.Name == "Player1"
end, "Hello, World!")
```
110 changes: 110 additions & 0 deletions docs/2.0/SharedSignalEvent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# SharedSignalEvent
SharedEvents are built on the same backend networking as regular events. However, they do not require an explicit `:Server` or `:Client` call to use.

Unlike [SharedEvents](SharedEvent), SharedSignalEvents may have any number of listeners set.

## OnServer <Badge type="tip" text="Server"></Badge>
Sets the server callback.
```lua
<T...>(
Listener: (Player: Player, T...) -> () -- The listener to register
) -> ()
```
This method sets the server callback. Errors if called from the client.
```lua
MyEvent:OnServer(function(Player, Argument)
print(Player, Argument)
end)
```

## OnClient <Badge type="warning" text="Client"></Badge>
Sets the client callback.
```lua
<T...>(
Listener: (T...) -> () -- The listener to register
) -> ()
```
This method sets the client callback. Errors if called from the server.
```lua
MyEvent:OnClient(function(Argument)
print(Argument)
end)
```

## FireServer <Badge type="warning" text="Client"></Badge>
Fires the event to the server.
```lua
<T...>(
...: T... -- The event payload
) -> ()
```
This method fires the event to the server. Errors if called from the server.
```lua
MyEvent:FireServer("Hello, World!")
```

## FireClient <Badge type="tip" text="Server"></Badge>
Fires the event to a specific player.
```lua
<T...>(
Player: Player, -- The target player
...: T... -- The event payload
) -> ()
```
This method fires the event to a specific client. Errors if called from the client.
```lua
MyEvent:FireClient(player, "Hello, World!")
```

## FireAllClients <Badge type="tip" text="Server"></Badge>
Fires the event to all players.
```lua
<T...>(
...: T... -- The event payload
) -> ()
```
This method fires the event to all players. Errors if called from the client.
```lua
MyEvent:FireAllClients("Hello, World!")
```

## FireAllClientsExcept <Badge type="tip" text="Server"></Badge>
Fires the event to every player **except** one.
```lua
<T...>(
Player: Player, -- Player to be ignored
...: T... -- The event payload
)
```
This method fires the event to every player except one. Errors if called from the client.
```lua
MyEvent:FireAllClientsExcept(player, "Hello, World!")
```

## FireClients <Badge type="tip" text="Server"></Badge>
Fires the event to every player in the given list.
```lua
<T...>(
Players: { Player }, -- List of players to fire the event to
...: T... -- The event payload
) -> ()
```
This method fires the event to every player in the list. Errors if called from the client.
```lua
MyServer:FireClients({ player }, "Hello, World!")
```

## FireFilteredClients <Badge type="tip" text="Server"></Badge>
Fires the event to every player that passes the given filter function.
```lua
<T...>(
Filter: (Player) -> boolean -- Must return true for a player to receive the event.
...: T... -- The event payload
) -> ()
```
This method fires the event to every player that passes the filter. Errors if called from the client.
```lua
MyServer:FireFilteredClients(function(player)
return player.Name == "Player1"
end, "Hello, World!")
```
Loading

0 comments on commit 943c487

Please sign in to comment.