diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index e99b142..77827a9 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -9,7 +9,8 @@ function nav() { { text: 'API Reference', items: [ - { text: '1.0', link: '/api/1.0/warp' } + { text: '1.0', link: '/api/1.0/warp' }, + { text: '1.1', link: '/api/1.1/warp' } ] } ] @@ -17,6 +18,27 @@ function nav() { function side() { return { + '/api/1.1': [ + { + text: 'API Reference', + items: [ + { text: 'Warp', link: '/api/1.1/warp' }, + { + text: 'Event', + items: [ + { text: 'Server', link: '/api/1.1/server' }, + { text: 'Client', link: '/api/1.1/client' }, + ] + }, + { + text: 'Utilities', + items: [ + { text: 'Buffer', link: '/api/1.1/buffer' }, + ] + }, + ] + } + ], '/api/1.0': [ { text: 'API Reference', diff --git a/docs/api/1.1/buffer.md b/docs/api/1.1/buffer.md new file mode 100644 index 0000000..5d9bc7f --- /dev/null +++ b/docs/api/1.1/buffer.md @@ -0,0 +1,147 @@ +# Buffer + +For efficient data serialization and schema definition with optimized packing. + +## Getting the Buffer Object + +```lua +local Buffer = Warp.Buffer() +``` + +## Schema System + +Define strict data schemas for optimized serialization and type safety. + +### Available Schema Types + +```lua +{ + -- Basic types + "boolean", + "string", + "nil", + + -- Numeric types + "uint8", + "uint16", + "uint32", + "int8", + "int16", + "int32", + "float32", + "float64", + + -- Roblox types + "buffer" + "Vector2", + "Vector3", + "CFrame", + "Color3", + "BrickColor", + "Instance", + "EnumItem", + "Enum", + "UDim2", + "UDim", + "Rect", + "NumberRange", + "Ray", + "ColorSequence", + "NumberSequence", +} +``` + +## Writer and Reader Functions + +### `.createWriter` + +Create a new buffer writer for serializing data. + +::: code-group +```lua [Variable] +( + capacity: number? -- Optional initial capacity (default: 64) +): Writer +``` + +```lua [Example] +local Buffer = Warp.Buffer() +local writer = Buffer.createWriter(256) -- Pre-allocate 256 bytes +``` +::: + +### `.build` + +Build the final buffer for transmission. + +::: code-group +```lua [Variable] +( + writer: Writer +): buffer -- Returns buffer +``` + +```lua [Example] +local Buffer = Warp.Buffer() +local writer = Buffer.createWriter() + +-- Write some data +Buffer.packValue(writer, "Hello World") +Buffer.packValue(writer, 12345) + +-- Build final buffer +local finalBuffer = Buffer.build(writer) +print(buffer.len(finalBuffer)) +``` +::: + +### `.buildWithRefs` + +Build the final buffer with instance references for transmission. + +::: code-group +```lua [Variable] +( + writer: Writer +): (buffer, { Instance }?) -- Returns buffer and optional instance references +``` + +```lua [Example] +local Buffer = Warp.Buffer() +local writer = Buffer.createWriter() + +-- Write some data with instances +Buffer.packValue(writer, workspace.Part) +Buffer.packValue(writer, game.Players.LocalPlayer) + +-- Build final buffer +local finalBuffer, refs = Buffer.buildWithRefs(writer) +print(buffer.len(finalBuffer), refs) +``` +::: + +### `.reset` + +Reset a writer for reuse, clearing all data. + +::: code-group +```lua [Variable] +( + writer: Writer +) +``` + +```lua [Example] +local Buffer = Warp.Buffer() +local writer = Buffer.createWriter() + +-- Use writer for first batch +Buffer.writeEvents(writer, events1) +local buffer1 = Buffer.build(writer) + +-- Reset and reuse for second batch +Buffer.reset(writer) +Buffer.writeEvents(writer, events2) +local buffer2 = Buffer.build(writer) +``` +::: diff --git a/docs/api/1.1/client.md b/docs/api/1.1/client.md new file mode 100644 index 0000000..d0e508e --- /dev/null +++ b/docs/api/1.1/client.md @@ -0,0 +1,214 @@ +# Client + +For Client-sided operations. + +## Getting the Client Object + +```lua +local Client = Warp.Client() +``` + +## `.Connect` + +Connect to an event to receive incoming data from the server. + +::: code-group +```lua [Variable] +( + remoteName: string, + fn: (...any) -> ...any +) -> Connection +``` + +```lua [Example] +local connection = Client.Connect("ServerNotify", function(message, sender) + print(`Server message from {sender}: {message}`) +end) +print(connection.Connected) +``` +::: + +## `.Once` + +Similar to `:Connect` but automatically disconnects after the first firing. + +::: code-group +```lua [Variable] +( + remoteName: string, + fn: (...any) -> ...any +) -> Connection +``` + +```lua [Example] +Client.Once("WelcomeMessage", function(welcomeText) + print(`Welcome: {welcomeText}`) +end) +``` +::: + +## `.Wait` + +Wait for an event to be triggered. + +::: code-group +```lua [Variable] +( + remoteName: string +) -> (number, ...any) +``` + +```lua [Example] +local elapsed, message = Client.Wait("ServerMessage") +print(`Received message after {elapsed} seconds: {message}`) +``` +::: + +## `.Disconnect` + +Disconnect the event connection. + +::: code-group +```lua [Variable] +() +``` + +```lua [Example] +local connection = Client.Connect("ServerNotify", function(message, sender) + print(`Server message from {sender}: {message}`) + -- Disconnect the connection + connection:Disconnect() +end) +print(Connection.Connected) +``` +::: + +## `.DisconnectAll` + +Disconnect all connections for a specific event. + +::: code-group +```lua [Variable] +( + remoteName: string +) +``` + +```lua [Example] +Client.DisconnectAll("ServerNotify") +``` +::: + +## `.Destroy` + +Disconnect all connections and remove the event. + +::: code-group +```lua [Variable] +( + remoteName: string +) +``` + +```lua [Example] +Client.Destroy("ServerNotify") +``` +::: + +## `.Fire` + +Fire an event to the server. + +::: code-group +```lua [Variable] +( + remoteName: string, + reliable: boolean, + ...: any +) +``` + +```lua [Example] +-- (TCP) Reliable event (guaranteed delivery) +Client.Fire("PlayerAction", true, "jump", playerPosition) + +-- (UDP) Unreliable event (faster but not guaranteed) +Client.Fire("PositionUpdate", false, currentPosition) +``` +::: + +## `.Invoke` + +Invoke the server with timeout support. + +::: code-group +```lua [Variable] +( + remoteName: string, + timeout: number?, + ...: any +) -> ...any +``` + +```lua [Example] +local Client = Warp.Client() +local response = Client.Invoke("RequestData", 3, "playerStats") +if response then + print("Server responded:", response) +else + print("Request timed out") +end +``` +::: + +::: warning +This function is yielded. Returns `nil` if timeout occurs. +::: + +## `.useSchema` + +Define a schema for strict data packing on a specific event. + +::: code-group +```lua [Variable] +( + remoteName: string, + schema: Buffer.SchemaType +) +``` + +```lua [Example] +local Client = Warp.Client() + +-- Define a schema for position updates +local positionSchema = Client.Schema.struct({ + x = Client.Schema.f32, + y = Client.Schema.f32, + z = Client.Schema.f32, + timestamp = Client.Schema.u32 +}) +-- Define a schema for data updates +local dataSchema = Client.Schema.struct({ + Coins = Client.Schema.u32, + Level = Client.Schema.u8, + Inventory = Client.Schema.array(Client.Schema.u32), + Settings = Client.Schema.struct({ + VFX = Client.Schema.boolean, + Volume = Client.Schema.f32, + Language = Client.Schema.string, + }) +}) + +-- Now this event will use the schema +Client.useSchema("DataReplication", dataSchema) +Client.useSchema("PositionUpdate", positionSchema) +Client.Connect("PositionUpdate", function(x, y, z, timestamp) + -- Data is automatically deserialized according to schema + updatePlayerPosition(x, y, z) +end) +``` +::: + +## `.Schema` + +Access to Buffer.Schema for creating data schemas. diff --git a/docs/api/1.1/server.md b/docs/api/1.1/server.md new file mode 100644 index 0000000..a8a12ac --- /dev/null +++ b/docs/api/1.1/server.md @@ -0,0 +1,216 @@ +# Server + +For Server-sided operations. + +## Getting the Server Object + +```lua +local Server = Warp.Server() +``` + +## `.Connect` + +Connect to an event to receive incoming data from clients. + +::: code-group +```lua [Variable] +( + remoteName: string, + fn: (player: Player, ...any) -> ...any +) -> Connection +``` + +```lua [Example] +local connection = Server.Connect("ServerNotify", function(player, message) + print(`Client message from {player}: {message}`) +end) +print(connection.Connected) +``` +::: + +## `.Once` + +Similar to `:Connect` but automatically disconnects after the first firing. + +::: code-group +```lua [Variable] +( + remoteName: string, + fn: (player: Player, ...any) -> ...any +) -> Connection +``` + +```lua [Example] +Server.Once("WelcomeMessage", function(welcomeText) + print(`Welcome: {welcomeText}`) +end) +``` +::: + +## `.Wait` + +Wait for an event to be triggered. + +::: code-group +```lua [Variable] +( + remoteName: string +) -> (number, ...any) +``` + +```lua [Example] +local elapsed, message = Server.Wait("ServerMessage") +print(`Received message after {elapsed} seconds: {message}`) +``` +::: + +## `.DisconnectAll` + +Disconnect all connections for a specific event. + +::: code-group +```lua [Variable] +( + remoteName: string +) +``` + +```lua [Example] +Server.DisconnectAll("ServerNotify") +``` +::: + +## `.Destroy` + +Disconnect all connections and remove the event. + +::: code-group +```lua [Variable] +( + remoteName: string +) +``` + +```lua [Example] +Server.Destroy("ServerNotify") +``` +::: + +## `.Fire` + +Fire an event to a specific player. + +::: code-group +```lua [Variable] +( + remoteName: string, + reliable: boolean, + player: Player, + ...: any +) +``` + +```lua [Example] +Server.Fire("ServerNotify", true, player, "Hello from server!") +``` +::: + +## `.Fires` + +Fire an event to all connected players. + +::: code-group +```lua [Variable] +( + remoteName: string, + reliable: boolean, + ...: any +) +``` + +```lua [Example] +Server.Fires("Broadcast", true, "Server announcement!") +``` +::: + +## `.FireExcept` + +Fire an event to all players except specified ones. + +::: code-group +```lua [Variable] +( + remoteName: string, + reliable: boolean, + except: { Player }, + ...: any +) +``` + +```lua [Example] +local excludedPlayers = { player1, player2 } +Server.FireExcept("Update", true, excludedPlayers, "Game update") +``` +::: + +## `.Invoke` + +Invoke a client with timeout support. + +::: code-group +```lua [Variable] +( + remoteName: string, + player: Player, + timeout: number?, + ...: any +) -> ...any +``` + +```lua [Example] +local response = Server.Invoke("RequestData", player, 3, "userInfo") +if response then + print("Client responded:", response) +else + print("Request timed out") +end +``` +::: + +::: warning +This function is yielded. Returns `nil` if timeout occurs. +::: + +## `.useSchema` + +Define a schema for strict data packing on a specific event. + +::: code-group +```lua [Variable] +( + remoteName: string, + schema: Buffer.SchemaType +) +``` + +```lua [Example] +local Server = Warp.Server() + +local dataSchema = Server.Schema.struct({ + Coins = Server.Schema.u32, + Level = Server.Schema.u8, + Inventory = Server.Schema.array(Server.Schema.u32), + Settings = Server.Schema.struct({ + VFX = Server.Schema.boolean, + Volume = Server.Schema.f32, + Language = Server.Schema.string, + }) +}) + +Server.useSchema("DataReplication", dataSchema) +``` +::: + +## `.Schema` + +Access to Buffer.Schema for creating data schemas. diff --git a/docs/api/1.1/warp.md b/docs/api/1.1/warp.md new file mode 100644 index 0000000..6365022 --- /dev/null +++ b/docs/api/1.1/warp.md @@ -0,0 +1,34 @@ +# Warp + +The public main of the Warp library. +::: warning +This version (1.1.x) are not backward compatible with 1.0.x. +::: + +## `.Server` + +Get the Server operation for server-side. + +```lua +-- Server +local Server = Warp.Server() +``` + +## `.Client` + +Get the Client operation for client-side. + +```lua +-- Client +local Client = Warp.Client() +``` + +## `.Buffer` + +Get the Buffer util for schema definition. + +```lua +-- Universal (Server & Client) +local Buffer = Warp.Buffer() +local schema = Buffer.Schema +``` \ No newline at end of file diff --git a/docs/guide/example.md b/docs/guide/example.md index 1f49fc3..bc24563 100644 --- a/docs/guide/example.md +++ b/docs/guide/example.md @@ -1,4 +1,4 @@ -# Example +# Example Let's try and play something with Warp! diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index c7534fb..5d67d15 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -1,4 +1,4 @@ -# Getting Started +# Getting Started ### `Step 1:` First, you have to require the Warp module.