roblox-opencode 1.0.0

package/vendor/rbxutil/comm/Server/RemoteProperty.luau

@@ -0,0 +1,295 @@
+-- RemoteProperty
+-- Stephen Leitnick
+-- December 20, 2021
+
+local Players = game:GetService("Players")
+
+local RemoteSignal = require(script.Parent.RemoteSignal)
+local Types = require(script.Parent.Parent.Types)
+local Util = require(script.Parent.Parent.Util)
+
+local None = Util.None
+
+--[=[
+	@class RemoteProperty
+	@server
+	Created via `ServerComm:CreateProperty()`.
+
+	Values set can be anything that can pass through a
+	[RemoteEvent](https://developer.roblox.com/en-us/articles/Remote-Functions-and-Events#parameter-limitations).
+
+	Here is a cheat-sheet for the below methods:
+	- Setting data
+		- `Set`: Set "top" value for all current and future players. Overrides any custom-set data per player.
+		- `SetTop`: Set the "top" value for all players, but does _not_ override any custom-set data per player.
+		- `SetFor`: Set custom data for the given player. Overrides the "top" value. (_Can be nil_)
+		- `SetForList`: Same as `SetFor`, but accepts a list of players.
+		- `SetFilter`: Accepts a predicate function which checks for which players to set.
+	- Clearing data
+		- `ClearFor`: Clears the custom data set for a given player. Player will start using the "top" level value instead.
+		- `ClearForList`: Same as `ClearFor`, but accepts a list of players.
+		- `ClearFilter`: Accepts a predicate function which checks for which players to clear.
+	- Getting data
+		- `Get`: Retrieves the "top" value
+		- `GetFor`: Gets the current value for the given player. If cleared, returns the top value.
+
+	:::caution Network
+	Calling any of the data setter methods (e.g. `Set()`) will
+	fire the underlying RemoteEvent to replicate data to the
+	clients. Therefore, setting data should only occur when it
+	is necessary to change the data that the clients receive.
+	:::
+
+	:::caution Tables
+	Tables _can_ be used with RemoteProperties. However, the
+	RemoteProperty object will _not_ watch for changes within
+	the table. Therefore, anytime changes are made to the table,
+	the data must be set again using one of the setter methods.
+	:::
+]=]
+local RemoteProperty = {}
+RemoteProperty.__index = RemoteProperty
+
+function RemoteProperty.new(
+	parent: Instance,
+	name: string,
+	initialValue: any,
+	inboundMiddleware: Types.ServerMiddleware?,
+	outboundMiddleware: Types.ServerMiddleware?
+)
+	local self = setmetatable({}, RemoteProperty)
+	self._rs = RemoteSignal.new(parent, name, false, inboundMiddleware, outboundMiddleware)
+	self._value = initialValue
+	self._perPlayer = {}
+	self._playerRemoving = Players.PlayerRemoving:Connect(function(player)
+		self._perPlayer[player] = nil
+	end)
+	self._rs:Connect(function(player)
+		local playerValue = self._perPlayer[player]
+		local value = if playerValue == nil then self._value elseif playerValue == None then nil else playerValue
+		self._rs:Fire(player, value)
+	end)
+	return self
+end
+
+--[=[
+	Sets the top-level value of all clients to the same value.
+	
+	:::note Override Per-Player Data
+	This will override any per-player data that was set using
+	`SetFor` or `SetFilter`. To avoid overriding this data,
+	`SetTop` can be used instead.
+	:::
+
+	```lua
+	-- Examples
+	remoteProperty:Set(10)
+	remoteProperty:Set({SomeData = 32})
+	remoteProperty:Set("HelloWorld")
+	```
+]=]
+function RemoteProperty:Set(value: any)
+	self._value = value
+	table.clear(self._perPlayer)
+	self._rs:FireAll(value)
+end
+
+--[=[
+	Set the top-level value of the property, but does not override
+	any per-player data (e.g. set with `SetFor` or `SetFilter`).
+	Any player without custom-set data will receive this new data.
+
+	This is useful if certain players have specific values that
+	should not be changed, but all other players should receive
+	the same new value.
+
+	```lua
+	-- Using just 'Set' overrides per-player data:
+	remoteProperty:SetFor(somePlayer, "CustomData")
+	remoteProperty:Set("Data")
+	print(remoteProperty:GetFor(somePlayer)) --> "Data"
+
+	-- Using 'SetTop' does not override:
+	remoteProperty:SetFor(somePlayer, "CustomData")
+	remoteProperty:SetTop("Data")
+	print(remoteProperty:GetFor(somePlayer)) --> "CustomData"
+	```
+]=]
+function RemoteProperty:SetTop(value: any)
+	self._value = value
+	for _, player in ipairs(Players:GetPlayers()) do
+		if self._perPlayer[player] == nil then
+			self._rs:Fire(player, value)
+		end
+	end
+end
+
+--[=[
+	@param value any -- Value to set for the clients (and to the predicate)
+	Sets the value for specific clients that pass the `predicate`
+	function test. This can be used to finely set the values
+	based on more control logic (e.g. setting certain values
+	per team).
+
+	```lua
+	-- Set the value of "NewValue" to players with a name longer than 10 characters:
+	remoteProperty:SetFilter(function(player)
+		return #player.Name > 10
+	end, "NewValue")
+	```
+]=]
+function RemoteProperty:SetFilter(predicate: (Player, any) -> boolean, value: any)
+	for _, player in ipairs(Players:GetPlayers()) do
+		if predicate(player, value) then
+			self:SetFor(player, value)
+		end
+	end
+end
+
+--[=[
+	Set the value of the property for a specific player. This
+	will override the value used by `Set` (and the initial value
+	set for the property when created).
+
+	This value _can_ be `nil`. In order to reset the value for a
+	given player and let the player use the top-level value held
+	by this property, either use `Set` to set all players' data,
+	or use `ClearFor`.
+
+	```lua
+	remoteProperty:SetFor(somePlayer, "CustomData")
+	```
+]=]
+function RemoteProperty:SetFor(player: Player, value: any)
+	if player.Parent then
+		self._perPlayer[player] = if value == nil then None else value
+	end
+	self._rs:Fire(player, value)
+end
+
+--[=[
+	Set the value of the property for specific players. This just
+	loops through the players given and calls `SetFor`.
+
+	```lua
+	local players = {player1, player2, player3}
+	remoteProperty:SetForList(players, "CustomData")
+	```
+]=]
+function RemoteProperty:SetForList(players: { Player }, value: any)
+	for _, player in ipairs(players) do
+		self:SetFor(player, value)
+	end
+end
+
+--[=[
+	Clears the custom property value for the given player. When
+	this occurs, the player will reset to use the top-level
+	value held by this property (either the value set when the
+	property was created, or the last value set by `Set`).
+
+	```lua
+	remoteProperty:Set("DATA")
+
+	remoteProperty:SetFor(somePlayer, "CUSTOM_DATA")
+	print(remoteProperty:GetFor(somePlayer)) --> "CUSTOM_DATA"
+
+	-- DOES NOT CLEAR, JUST SETS CUSTOM DATA TO NIL:
+	remoteProperty:SetFor(somePlayer, nil)
+	print(remoteProperty:GetFor(somePlayer)) --> nil
+
+	-- CLEAR:
+	remoteProperty:ClearFor(somePlayer)
+	print(remoteProperty:GetFor(somePlayer)) --> "DATA"
+	```
+]=]
+function RemoteProperty:ClearFor(player: Player)
+	if self._perPlayer[player] == nil then
+		return
+	end
+	self._perPlayer[player] = nil
+	self._rs:Fire(player, self._value)
+end
+
+--[=[
+	Clears the custom value for the given players. This
+	just loops through the list of players and calls
+	the `ClearFor` method for each player.
+]=]
+function RemoteProperty:ClearForList(players: { Player })
+	for _, player in ipairs(players) do
+		self:ClearFor(player)
+	end
+end
+
+--[=[
+	The same as `SetFiler`, except clears the custom value
+	for any player that passes the predicate.
+]=]
+function RemoteProperty:ClearFilter(predicate: (Player) -> boolean)
+	for _, player in ipairs(Players:GetPlayers()) do
+		if predicate(player) then
+			self:ClearFor(player)
+		end
+	end
+end
+
+--[=[
+	Returns the top-level value held by the property. This will
+	either be the initial value set, or the last value set
+	with `Set()`.
+
+	```lua
+	remoteProperty:Set("Data")
+	print(remoteProperty:Get()) --> "Data"
+	```
+]=]
+function RemoteProperty:Get(): any
+	return self._value
+end
+
+--[=[
+	Returns the current value for the given player. This value
+	will depend on if `SetFor` or `SetFilter` has affected the
+	custom value for the player. If so, that custom value will
+	be returned. Otherwise, the top-level value will be used
+	(e.g. value from `Set`).
+
+	```lua
+	-- Set top level data:
+	remoteProperty:Set("Data")
+	print(remoteProperty:GetFor(somePlayer)) --> "Data"
+
+	-- Set custom data:
+	remoteProperty:SetFor(somePlayer, "CustomData")
+	print(remoteProperty:GetFor(somePlayer)) --> "CustomData"
+
+	-- Set top level again, overriding custom data:
+	remoteProperty:Set("NewData")
+	print(remoteProperty:GetFor(somePlayer)) --> "NewData"
+
+	-- Set custom data again, and set top level without overriding:
+	remoteProperty:SetFor(somePlayer, "CustomData")
+	remoteProperty:SetTop("Data")
+	print(remoteProperty:GetFor(somePlayer)) --> "CustomData"
+
+	-- Clear custom data to use top level data:
+	remoteProperty:ClearFor(somePlayer)
+	print(remoteProperty:GetFor(somePlayer)) --> "Data"
+	```
+]=]
+function RemoteProperty:GetFor(player: Player): any
+	local playerValue = self._perPlayer[player]
+	local value = if playerValue == nil then self._value elseif playerValue == None then nil else playerValue
+	return value
+end
+
+--[=[
+	Destroys the RemoteProperty object.
+]=]
+function RemoteProperty:Destroy()
+	self._rs:Destroy()
+	self._playerRemoving:Disconnect()
+end
+
+return RemoteProperty

package/vendor/rbxutil/comm/Server/RemoteSignal.luau

@@ -0,0 +1,211 @@
+-- RemoteSignal
+-- Stephen Leitnick
+-- December 20, 2021
+
+local Players = game:GetService("Players")
+
+local Signal = require(script.Parent.Parent.Parent.Signal)
+local Types = require(script.Parent.Parent.Types)
+
+--[=[
+	@class RemoteSignal
+	@server
+	Created via `ServerComm:CreateSignal()`.
+]=]
+local RemoteSignal = {}
+RemoteSignal.__index = RemoteSignal
+
+--[=[
+	@within RemoteSignal
+	@interface Connection
+	.Disconnect () -> nil
+	.Connected boolean
+
+	Represents a connection.
+]=]
+
+function RemoteSignal.new(
+	parent: Instance,
+	name: string,
+	unreliable: boolean?,
+	inboundMiddleware: Types.ServerMiddleware?,
+	outboundMiddleware: Types.ServerMiddleware?
+)
+	local self = setmetatable({}, RemoteSignal)
+	self._re = if unreliable == true then Instance.new("UnreliableRemoteEvent") else Instance.new("RemoteEvent")
+	self._re.Name = name
+	self._re.Parent = parent
+	if outboundMiddleware and #outboundMiddleware > 0 then
+		self._hasOutbound = true
+		self._outbound = outboundMiddleware
+	else
+		self._hasOutbound = false
+	end
+	if inboundMiddleware and #inboundMiddleware > 0 then
+		self._directConnect = false
+		self._signal = Signal.new()
+		self._re.OnServerEvent:Connect(function(player, ...)
+			local args = table.pack(...)
+			for _, middlewareFunc in inboundMiddleware do
+				local middlewareResult = table.pack(middlewareFunc(player, args))
+				if not middlewareResult[1] then
+					return
+				end
+				args.n = #args
+			end
+			self._signal:Fire(player, table.unpack(args, 1, args.n))
+		end)
+	else
+		self._directConnect = true
+	end
+	return self
+end
+
+--[=[
+	@return boolean
+	Returns `true` if the underlying RemoteSignal is bound to an
+	UnreliableRemoteEvent object.
+]=]
+function RemoteSignal:IsUnreliable(): boolean
+	return self._re:IsA("UnreliableRemoteEvent")
+end
+
+--[=[
+	@param fn (player: Player, ...: any) -> nil -- The function to connect
+	@return Connection
+	Connect a function to the signal. Anytime a matching ClientRemoteSignal
+	on a client fires, the connected function will be invoked with the
+	arguments passed by the client.
+]=]
+function RemoteSignal:Connect(fn)
+	if self._directConnect then
+		return self._re.OnServerEvent:Connect(fn)
+	else
+		return self._signal:Connect(fn)
+	end
+end
+
+function RemoteSignal:_processOutboundMiddleware(player: Player?, ...: any)
+	if not self._hasOutbound then
+		return ...
+	end
+	local args = table.pack(...)
+	for _, middlewareFunc in self._outbound do
+		local middlewareResult = table.pack(middlewareFunc(player, args))
+		if not middlewareResult[1] then
+			return table.unpack(middlewareResult, 2, middlewareResult.n)
+		end
+		args.n = #args
+	end
+	return table.unpack(args, 1, args.n)
+end
+
+--[=[
+	@param player Player -- The target client
+	@param ... any -- Arguments passed to the client
+	Fires the signal at the specified client with any arguments.
+
+	:::note Outbound Middleware
+	All arguments pass through any outbound middleware (if any)
+	before being sent to the clients.
+	:::
+]=]
+function RemoteSignal:Fire(player: Player, ...: any)
+	self._re:FireClient(player, self:_processOutboundMiddleware(player, ...))
+end
+
+--[=[
+	@param ... any
+	Fires the signal at _all_ clients with any arguments.
+
+	:::note Outbound Middleware
+	All arguments pass through any outbound middleware (if any)
+	before being sent to the clients.
+	:::
+]=]
+function RemoteSignal:FireAll(...: any)
+	self._re:FireAllClients(self:_processOutboundMiddleware(nil, ...))
+end
+
+--[=[
+	@param ignorePlayer Player -- The client to ignore
+	@param ... any -- Arguments passed to the other clients
+	Fires the signal to all clients _except_ the specified
+	client.
+
+	:::note Outbound Middleware
+	All arguments pass through any outbound middleware (if any)
+	before being sent to the clients.
+	:::
+]=]
+function RemoteSignal:FireExcept(ignorePlayer: Player, ...: any)
+	self:FireFilter(function(plr)
+		return plr ~= ignorePlayer
+	end, ...)
+end
+
+--[=[
+	@param predicate (player: Player, argsFromFire: ...) -> boolean
+	@param ... any -- Arguments to pass to the clients (and to the predicate)
+	Fires the signal at any clients that pass the `predicate`
+	function test. This can be used to fire signals with much
+	more control logic.
+
+	:::note Outbound Middleware
+	All arguments pass through any outbound middleware (if any)
+	before being sent to the clients.
+	:::
+
+	:::caution Predicate Before Middleware
+	The arguments sent to the predicate are sent _before_ getting
+	transformed by any middleware.
+	:::
+
+	```lua
+	-- Fire signal to players of the same team:
+	remoteSignal:FireFilter(function(player)
+		return player.Team.Name == "Best Team"
+	end)
+	```
+]=]
+function RemoteSignal:FireFilter(predicate: (Player, ...any) -> boolean, ...: any)
+	for _, player in Players:GetPlayers() do
+		if predicate(player, ...) then
+			self._re:FireClient(player, self:_processOutboundMiddleware(nil, ...))
+		end
+	end
+end
+
+--[=[
+	Fires a signal at the clients within the `players` table. This is
+	useful when signals need to fire for a specific set of players.
+
+	For more complex firing, see `FireFilter`.
+
+	:::note Outbound Middleware
+	All arguments pass through any outbound middleware (if any)
+	before being sent to the clients.
+	:::
+
+	```lua
+	local players = {somePlayer1, somePlayer2, somePlayer3}
+	remoteSignal:FireFor(players, "Hello, players!")
+	```
+]=]
+function RemoteSignal:FireFor(players: { Player }, ...: any)
+	for _, player in players do
+		self._re:FireClient(player, self:_processOutboundMiddleware(nil, ...))
+	end
+end
+
+--[=[
+	Destroys the RemoteSignal object.
+]=]
+function RemoteSignal:Destroy()
+	self._re:Destroy()
+	if self._signal then
+		self._signal:Destroy()
+	end
+end
+
+return RemoteSignal

package/vendor/rbxutil/comm/Server/ServerComm.luau

@@ -0,0 +1,211 @@
+-- ServerComm
+-- Stephen Leitnick
+-- December 20, 2021
+
+local Comm = require(script.Parent)
+local Types = require(script.Parent.Parent.Types)
+local Util = require(script.Parent.Parent.Util)
+
+--[=[
+	@class ServerComm
+	@server
+]=]
+local ServerComm = {}
+ServerComm.__index = ServerComm
+
+--[=[
+	@within ServerComm
+	@type ServerMiddlewareFn (player: Player, args: {any}) -> (shouldContinue: boolean, ...: any)
+	The middleware function takes the client player and the arguments (as a table array), and should
+	return `true|false` to indicate if the process should continue.
+
+	If returning `false`, the optional varargs after the `false` are used as the new return values
+	to whatever was calling the middleware.
+]=]
+--[=[
+	@within ServerComm
+	@type ServerMiddleware {ServerMiddlewareFn}
+	Array of middleware functions.
+]=]
+
+--[=[
+	@return ServerComm
+	Constructs a ServerComm object. The `namespace` parameter is used
+	in cases where more than one ServerComm object may be bound
+	to the same object. Otherwise, a default namespace is used.
+
+	```lua
+	local serverComm = ServerComm.new(game:GetService("ReplicatedStorage"))
+
+	-- If many might exist in the given parent, use a unique namespace:
+	local serverComm = ServerComm.new(game:GetService("ReplicatedStorage"), "MyNamespace")
+	```
+]=]
+function ServerComm.new(parent: Instance, namespace: string?)
+	assert(Util.IsServer, "ServerComm must be constructed from the server")
+	assert(typeof(parent) == "Instance", "Parent must be of type Instance")
+	local ns = Util.DefaultCommFolderName
+	if namespace then
+		ns = namespace
+	end
+	assert(not parent:FindFirstChild(ns), "Parent already has another ServerComm bound to namespace " .. ns)
+	local self = setmetatable({}, ServerComm)
+	self._instancesFolder = Instance.new("Folder")
+	self._instancesFolder.Name = ns
+	self._instancesFolder.Parent = parent
+	return self
+end
+
+--[=[
+	@param name string
+	@param fn (player: Player, ...: any) -> ...: any
+	@param inboundMiddleware ServerMiddleware?
+	@param outboundMiddleware ServerMiddleware?
+	@return RemoteFunction
+	Creates a RemoteFunction and binds the given function to it. Inbound
+	and outbound middleware can be applied if desired.
+
+	```lua
+	local function GetSomething(player: Player)
+		return "Something"
+	end
+
+	serverComm:BindFunction("GetSomething", GetSomething)
+	```
+]=]
+function ServerComm:BindFunction(
+	name: string,
+	fn: Types.FnBind,
+	inboundMiddleware: Types.ServerMiddleware?,
+	outboundMiddleware: Types.ServerMiddleware?
+): RemoteFunction
+	return Comm.BindFunction(self._instancesFolder, name, fn, inboundMiddleware, outboundMiddleware)
+end
+
+--[=[
+	@param tbl table
+	@param name string
+	@param inboundMiddleware ServerMiddleware?
+	@param outboundMiddleware ServerMiddleware?
+	@return RemoteFunction
+
+	Binds a function to a table method. The name must match the
+	name of the method in the table. The same name will be used
+	on the client to access the given function.
+
+	```lua
+	local MyObject = {
+		_Data = 10,
+	}
+
+	function MyObject:GetData(player: Player)
+		return self._Data
+	end
+
+	serverComm:WrapMethod(MyObject, "GetData")
+	```
+]=]
+function ServerComm:WrapMethod(
+	tbl: {},
+	name: string,
+	inboundMiddleware: Types.ServerMiddleware?,
+	outboundMiddleware: Types.ServerMiddleware?
+): RemoteFunction
+	return Comm.WrapMethod(self._instancesFolder, tbl, name, inboundMiddleware, outboundMiddleware)
+end
+
+--[=[
+	@param name string
+	@param unreliable boolean?
+	@param inboundMiddleware ServerMiddleware?
+	@param outboundMiddleware ServerMiddleware?
+	@return RemoteSignal
+
+	Creates a signal that can be used to fire data to the clients
+	or receive data from the clients.
+
+	By default, signals use RemoteEvents internally. However, if
+	the `unreliable` argument is set to `true`, then an
+	UnreliableRemoteEvent will be used instead.
+
+	```lua
+	local mySignal = serverComm:CreateSignal("MySignal")
+
+	-- Examples of firing in different ways (see docs for RemoteSignal for further info):
+	mySignal:Fire(somePlayer, "Hello world")
+	mySignal:FireAll("Hi there")
+	mySignal:FireExcept(somePlayer, "Hello everyone except " .. somePlayer.Name)
+	mySignal:FireFilter(function(player) return player.Team == someCoolTeam end, "Hello cool team")
+
+	-- Example of listening for clients to send data:
+	mySignal:Connect(function(player, message)
+		print("Got a message from " .. player.Name .. ":", message)
+	end)
+	```
+]=]
+function ServerComm:CreateSignal(
+	name: string,
+	unreliable: boolean?,
+	inboundMiddleware: Types.ServerMiddleware?,
+	outboundMiddleware: Types.ServerMiddleware?
+)
+	return Comm.CreateSignal(self._instancesFolder, name, unreliable, inboundMiddleware, outboundMiddleware)
+end
+
+--[=[
+	@param name string
+	@param initialValue any
+	@param inboundMiddleware ServerMiddleware?
+	@param outboundMiddleware ServerMiddleware?
+	@return RemoteProperty
+
+	Create a property object which will replicate its property value to
+	the clients. Optionally, specific clients can be targeted with
+	different property values.
+
+	```lua
+	local comm = Comm.ServerComm.new(game:GetService("ReplicatedStorage"))
+
+	local mapInfo = comm:CreateProperty("MapInfo", {
+		MapName = "TheAwesomeMap",
+		MapDuration = 60,
+	})
+
+	-- Change the data:
+	mapInfo:Set({
+		MapName = "AnotherMap",
+		MapDuration = 30,
+	})
+
+	-- Change the data for one player:
+	mapInfo:SetFor(somePlayer, {
+		MapName = "ASpecialMapForYou",
+		MapDuration = 90,
+	})
+
+	-- Change data based on a predicate function:
+	mapInfo:SetFilter(function(player)
+		return player.Team == game.Teams.SomeSpecialTeam
+	end, {
+		MapName = "TeamMap",
+		MapDuration = 20,
+	})
+	```
+]=]
+function ServerComm:CreateProperty(
+	name: string,
+	initialValue: any,
+	inboundMiddleware: Types.ServerMiddleware?,
+	outboundMiddleware: Types.ServerMiddleware?
+)
+	return Comm.CreateProperty(self._instancesFolder, name, initialValue, inboundMiddleware, outboundMiddleware)
+end
+
+--[=[
+	Destroy the ServerComm object.
+]=]
+function ServerComm:Destroy()
+	self._instancesFolder:Destroy()
+end
+
+return ServerComm