Merge pull request #10 from Tazmondo/main

Add docs for Shared Events

docs/.vitepress/config.ts

@@ -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' }
 				]
 			},
 			{
@@ -47,6 +48,8 @@ function sidebar() {
 						]
 					},
 					{ text: 'Function', link: '/2.0/Function' },
+					{ text: 'SharedEvent', link: '/2.0/SharedEvent' },
+					{ text: 'SharedSignalEvent', link: '/2.0/SharedSignalEvent' }
 				],
 			}
 		],

docs/2.0/Event/Client.md

@@ -24,7 +24,7 @@ Sets the event's listener.
 
 ```lua
 <T...>(
-	Listener: (...T...) -> (), -- The listener
+	Listener: (T...) -> (), -- The listener
 ) -> ()
 ```
 

docs/2.0/Event/Server.md

@@ -94,7 +94,7 @@ Sets the event's listener.
 
 ```lua
 <T...>(
-	Function: (...: T...) -> (), -- The function to connect
+	Listener: (T...) -> (), -- The function to connect
 ) -> ()
 ```
 

docs/2.0/Function.md

@@ -2,14 +2,14 @@
 
 Functions allow RemoteFunction-like behavior in Red for calling client -> server.
 
-## SetCallback
+## SetCallback <Badge type="tip" text="Server"></Badge>
 
 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.
@@ -22,24 +22,22 @@ Function:SetCallback(function(Player, Arg1, Arg2, Arg3)
 end)
 ```
 
-::: danger
-If the callback errors the client will never recieve any value and will yield forever. **Doing this is a memory leak!** Do not rely on erroring not sending back values.
-:::
-
-## Call
+## Call <Badge type="warning" text="Client"></Badge>
 
 Calls the function on the server.
 
 ```lua
 <A..., R...>(
 	...A: any -- The arguments to pass to the function.
-): Future<R...>
+) -> Future<boolean, R...> -- A success boolean followed by the returned values
 ```
 
-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.
+Functions can only be called from the client. The client must pass valid arguments to the function, and will be given back a [Future](https://util.redblox.dev/future) that completes with the returned values.
+
+It also returns a success boolean, similar to pcall, which is false if the server's callback function errored, and true if it was successful.
 
 ```lua
 local Function = require(Path.To.Function)
 
-local Ret1, Ret2, Ret3 = Function:Call(Arg1, Arg2, Arg3):Await()
+local Success, Ret1, Ret2, Ret3 = Function:Call(Arg1, Arg2, Arg3):Await()
 ```

docs/2.0/Red.md

@@ -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.
+:::

docs/2.0/SharedEvent.md

@@ -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!")
+```

docs/2.0/SharedSignalEvent.md

@@ -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!")
+```