From cdc3e5cd5314fd31ee92330c0260809ab059ff02 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Wed, 4 Jan 2023 19:55:05 -0500 Subject: [PATCH 01/20] Add initial docs --- docs/headless-api.md | 92 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 docs/headless-api.md diff --git a/docs/headless-api.md b/docs/headless-api.md new file mode 100644 index 00000000..9ae1e66e --- /dev/null +++ b/docs/headless-api.md @@ -0,0 +1,92 @@ +--- +title: Rojo Plugin APIs +sidebar_position: 7 +--- + +The Rojo Studio plugin exposes a headless API into `_G`, which is very valuable to the Rojo ecosystem. This allows you to make companion plugins that interact with Rojo! + +### Accessing the API +```Lua +local Rojo = _G.Rojo +``` +Plugins and command bar all share the same _G which allows us to put our interface in. Using the key `"Rojo"` is easy to remember and follows branding. + +### API Documentation + +**Functions:** + +```Lua +Rojo:RequestAccess(apis: {string}): {[string]: boolean} +``` +In order to use any of these headless APIs, you must first explicitly request them. Users will be prompted to allow/deny each API your plugin aims to use, and it will return a dictionary of the APIs to a boolean of whether it was granted or not. This must be the first thing your plugin calls when using this headless API feature. This keeps our users secure and protected from malicious plugins. + +The only exceptions to this are `Rojo.Version` and `Rojo.ProtocolVersion`, since those are useful in checking compatibility before anything else is done. + +```Lua +Rojo:ConnectAsync(host: string?, port: string?): void +``` +Attempts to connect Rojo to the given host & port. Same behavior as the user clicking the Connect button (sync locking, etc, all behave the same). + +```Lua +Rojo:DisconnectAsync(): void +``` +Attempts to disconnect any active sync session. + +```Lua +Rojo:GetSetting(setting: string): any +``` +Returns the value of the given setting. + +```Lua +Rojo:SetSetting(setting: string, value: any): void +``` +Sets the value of the given setting to the given value. + +```Lua +Rojo:Notify(msg: string, timeout: number?): void +``` +Sends a Rojo notification. Will indicate on it that it comes from a third party plugin. + +```Lua +Rojo:GetHostAndPort(): (string, string) +``` +Returns the user's chosen host and port. + +```Lua +Rojo:CreateApiContext(baseUrl: string): ApiContext +``` +Returns a new ApiContext using the given baseUrl. + +**Properties:** *(All read-only)* + +```Lua +Rojo.Version: {number} +``` +The Rojo plugin version. (Example: `{7, 2, 1}`) + +```Lua +Rojo.ProtocolVersion: number +``` +The Rojo plugin's protocol version. + +```Lua +Rojo.Connected: boolean +``` +Whether Rojo is currently connected to a serve session. + +```Lua +Rojo.Address: string? +``` +When `Rojo.Connected` is `true`, this is set to the address of the connected session. + +```Lua +Rojo.ProjectName: string? +``` +When `Rojo.Connected` is `true`, this is set to the project name of the connected session. + +**Events:** + +```Lua +Rojo.Changed: RbxScriptSignal (changedProperty: string, newValue: any?, oldValue: any?) +``` +Fires when a property changes with the name of the changed property and the values. From e4a1648240972f33824470571941707b6cfeed72 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Thu, 5 Jan 2023 19:54:34 -0500 Subject: [PATCH 02/20] Fix _G text formatting --- docs/headless-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 9ae1e66e..d771d7dd 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -9,7 +9,7 @@ The Rojo Studio plugin exposes a headless API into `_G`, which is very valuable ```Lua local Rojo = _G.Rojo ``` -Plugins and command bar all share the same _G which allows us to put our interface in. Using the key `"Rojo"` is easy to remember and follows branding. +Plugins and command bar all share the same `_G` which allows us to put our interface in. Using the key `"Rojo"` is easy to remember and follows branding. ### API Documentation From fcd880c0282faf3518f4b5f243171686e5a048f0 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Thu, 5 Jan 2023 19:56:08 -0500 Subject: [PATCH 03/20] Clarify API access --- docs/headless-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index d771d7dd..72d47f58 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -9,7 +9,7 @@ The Rojo Studio plugin exposes a headless API into `_G`, which is very valuable ```Lua local Rojo = _G.Rojo ``` -Plugins and command bar all share the same `_G` which allows us to put our interface in. Using the key `"Rojo"` is easy to remember and follows branding. +Plugins and command bar all share the same environment, which allows us to expose the API through `_G`. Using the key `"Rojo"` is easy to remember and follows branding. ### API Documentation From d1716a1204466ae8b0b0db4fccc4cc8b2491040d Mon Sep 17 00:00:00 2001 From: boatbomber Date: Thu, 5 Jan 2023 20:13:10 -0500 Subject: [PATCH 04/20] Clarify and example RequestAccess --- docs/headless-api.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 72d47f58..ec5117b8 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -18,9 +18,24 @@ Plugins and command bar all share the same environment, which allows us to expos ```Lua Rojo:RequestAccess(apis: {string}): {[string]: boolean} ``` -In order to use any of these headless APIs, you must first explicitly request them. Users will be prompted to allow/deny each API your plugin aims to use, and it will return a dictionary of the APIs to a boolean of whether it was granted or not. This must be the first thing your plugin calls when using this headless API feature. This keeps our users secure and protected from malicious plugins. +In order to use any of the Rojo APIs, you must first explicitly request them with this function. Users will be prompted to allow/deny each API, (this function will yield until the user responds) and then the function will return a dictionary where the keys are the requested APIs and the values are booleans which represent the access status (whether or not access was granted). + +**This must be the first function your plugin calls when using the Rojo API. This keeps our users secure and protected from malicious plugins.** The only exceptions to this are `Rojo.Version` and `Rojo.ProtocolVersion`, since those are useful in checking compatibility before anything else is done. + +Example Plugin: +```Lua +local granted = Rojo:RequestAccess({ "Connected", "ConnectAsync" }) +--[[ +granted = { + Connected = true, -- User granted access + ConnectAsync = false, -- User denied access +} +--]] +``` + +![image](https://user-images.githubusercontent.com/40185666/210909337-3caf5af4-0829-447c-9781-da3996c71284.png) + -The only exceptions to this are `Rojo.Version` and `Rojo.ProtocolVersion`, since those are useful in checking compatibility before anything else is done. ```Lua Rojo:ConnectAsync(host: string?, port: string?): void From 11c0032570d335e3f0ff4c33b2dd477dac3387da Mon Sep 17 00:00:00 2001 From: boatbomber Date: Thu, 5 Jan 2023 20:15:28 -0500 Subject: [PATCH 05/20] Concise language for RequestAccess security info --- docs/headless-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index ec5117b8..795db0de 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -20,7 +20,7 @@ Rojo:RequestAccess(apis: {string}): {[string]: boolean} ``` In order to use any of the Rojo APIs, you must first explicitly request them with this function. Users will be prompted to allow/deny each API, (this function will yield until the user responds) and then the function will return a dictionary where the keys are the requested APIs and the values are booleans which represent the access status (whether or not access was granted). -**This must be the first function your plugin calls when using the Rojo API. This keeps our users secure and protected from malicious plugins.** The only exceptions to this are `Rojo.Version` and `Rojo.ProtocolVersion`, since those are useful in checking compatibility before anything else is done. +**In order to keep our users safe from malicious plugins, RequestAccess must be the first function your plugin calls when using the Rojo API.** Attempting to use an API without requesting it beforehand will throw an error. The only exceptions to this are `Rojo.Version` and `Rojo.ProtocolVersion`, since those are useful in checking compatibility before anything else is done. Example Plugin: ```Lua From e9cc9669608942adceea4a72c601190a6a105cd9 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Thu, 5 Jan 2023 20:16:25 -0500 Subject: [PATCH 06/20] Use word instead of ampersand --- docs/headless-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 795db0de..876cc29f 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -40,7 +40,7 @@ granted = { ```Lua Rojo:ConnectAsync(host: string?, port: string?): void ``` -Attempts to connect Rojo to the given host & port. Same behavior as the user clicking the Connect button (sync locking, etc, all behave the same). +Attempts to connect Rojo to the given host and port. Same behavior as the user clicking the Connect button (sync locking, etc., all behave the same). ```Lua Rojo:DisconnectAsync(): void From 20c3cd0c4bda557f8ba9996794ccdd9151909be4 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Thu, 5 Jan 2023 20:18:06 -0500 Subject: [PATCH 07/20] Less redudant wording for SetSetting --- docs/headless-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 876cc29f..2c915825 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -55,7 +55,7 @@ Returns the value of the given setting. ```Lua Rojo:SetSetting(setting: string, value: any): void ``` -Sets the value of the given setting to the given value. +Sets the value of the given setting. ```Lua Rojo:Notify(msg: string, timeout: number?): void From e0a846471cf8260d44d281ec68f3c7a964ace321 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Thu, 5 Jan 2023 20:20:59 -0500 Subject: [PATCH 08/20] Concise and example for Notify --- docs/headless-api.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 2c915825..2bdb0659 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -60,7 +60,10 @@ Sets the value of the given setting. ```Lua Rojo:Notify(msg: string, timeout: number?): void ``` -Sends a Rojo notification. Will indicate on it that it comes from a third party plugin. +Sends a Rojo notification that indicates it comes from a third-party plugin. + +![image](https://user-images.githubusercontent.com/40185666/210910275-c8e5e754-0769-4b39-acfe-04342b25c96d.png) + ```Lua Rojo:GetHostAndPort(): (string, string) From 340e0bdc7bcfd5a8c9616689061fc729ea0fdc6e Mon Sep 17 00:00:00 2001 From: boatbomber Date: Thu, 5 Jan 2023 20:22:08 -0500 Subject: [PATCH 09/20] Clearer wording for Address and ProjectName --- docs/headless-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 2bdb0659..3889cdad 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -95,12 +95,12 @@ Whether Rojo is currently connected to a serve session. ```Lua Rojo.Address: string? ``` -When `Rojo.Connected` is `true`, this is set to the address of the connected session. +When `Rojo.Connected` is `true`, this contains the address of the connected session. ```Lua Rojo.ProjectName: string? ``` -When `Rojo.Connected` is `true`, this is set to the project name of the connected session. +When `Rojo.Connected` is `true`, this contains the project name of the connected session. **Events:** From 45392d867f9af6af86207a2562853356b788ef0c Mon Sep 17 00:00:00 2001 From: boatbomber Date: Thu, 5 Jan 2023 20:23:23 -0500 Subject: [PATCH 10/20] Clearer wording for Changed --- docs/headless-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 3889cdad..20818014 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -107,4 +107,4 @@ When `Rojo.Connected` is `true`, this contains the project name of the connected ```Lua Rojo.Changed: RbxScriptSignal (changedProperty: string, newValue: any?, oldValue: any?) ``` -Fires when a property changes with the name of the changed property and the values. +Fires when any property changes. Passes the name of the changed property and its new and old values. From ccca3fba1efd1fd69e3f8dc5aae640bba478c9b8 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Thu, 5 Jan 2023 20:25:00 -0500 Subject: [PATCH 11/20] Better headings --- docs/headless-api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 20818014..3eed42ae 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -5,15 +5,15 @@ sidebar_position: 7 The Rojo Studio plugin exposes a headless API into `_G`, which is very valuable to the Rojo ecosystem. This allows you to make companion plugins that interact with Rojo! -### Accessing the API +## Accessing the API ```Lua local Rojo = _G.Rojo ``` Plugins and command bar all share the same environment, which allows us to expose the API through `_G`. Using the key `"Rojo"` is easy to remember and follows branding. -### API Documentation +## API Documentation -**Functions:** +### Functions ```Lua Rojo:RequestAccess(apis: {string}): {[string]: boolean} @@ -75,7 +75,7 @@ Rojo:CreateApiContext(baseUrl: string): ApiContext ``` Returns a new ApiContext using the given baseUrl. -**Properties:** *(All read-only)* +### Properties *(All read-only)* ```Lua Rojo.Version: {number} @@ -102,7 +102,7 @@ Rojo.ProjectName: string? ``` When `Rojo.Connected` is `true`, this contains the project name of the connected session. -**Events:** +### Events ```Lua Rojo.Changed: RbxScriptSignal (changedProperty: string, newValue: any?, oldValue: any?) From 69f43e5fdc3b37a81ee9cfe68fe79aae062c5185 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Sat, 7 Jan 2023 16:50:36 -0500 Subject: [PATCH 12/20] Explain how to access the API safely --- docs/headless-api.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 3eed42ae..4f57be0d 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -6,10 +6,27 @@ sidebar_position: 7 The Rojo Studio plugin exposes a headless API into `_G`, which is very valuable to the Rojo ecosystem. This allows you to make companion plugins that interact with Rojo! ## Accessing the API + +Plugins and command bar all share the same environment, which allows us to expose the API through `_G`. Using the key `"Rojo"` is easy to remember and follows branding. + ```Lua local Rojo = _G.Rojo ``` -Plugins and command bar all share the same environment, which allows us to expose the API through `_G`. Using the key `"Rojo"` is easy to remember and follows branding. + +However, plugins load in random order which means that your plugin might load before Rojo does. Therefore, the safe way to access is: + +```Lua +local function GetRojo() + local api = _G.Rojo + while not api do + task.wait() + api = _G.Rojo + end + return api +end + +local Rojo = GetRojo() +``` ## API Documentation From 0c0fe3876308c2ecb12a80a4ba9113157c837556 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Tue, 4 Jul 2023 15:08:19 -0700 Subject: [PATCH 13/20] Update notify docs --- docs/headless-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 4f57be0d..1fd77ae9 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -75,11 +75,11 @@ Rojo:SetSetting(setting: string, value: any): void Sets the value of the given setting. ```Lua -Rojo:Notify(msg: string, timeout: number?): void +function Rojo:Notify(msg: string, timeout: number?, actions: { [string]: {text: string, style: string, layoutOrder: number, onClick: (any) -> ()} }?): () -> () ``` -Sends a Rojo notification that indicates it comes from a third-party plugin. +Sends a Rojo notification that indicates it comes from a third-party plugin. Returns a function that dismisses the notification. -![image](https://user-images.githubusercontent.com/40185666/210910275-c8e5e754-0769-4b39-acfe-04342b25c96d.png) +![image](https://github.com/boatbomber/rojo.space/assets/40185666/c3f31715-dcdd-4c9d-b947-8dceee606b61) ```Lua From 63ac53d01548bfd50b85c53b3d7663b2281531bc Mon Sep 17 00:00:00 2001 From: boatbomber Date: Tue, 4 Jul 2023 19:26:52 -0700 Subject: [PATCH 14/20] Add plugin arg to RequestAccess docs --- docs/headless-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 1fd77ae9..0896f3cf 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -33,15 +33,15 @@ local Rojo = GetRojo() ### Functions ```Lua -Rojo:RequestAccess(apis: {string}): {[string]: boolean} +Rojo:RequestAccess(plugin: Plugin, apis: {string}): {[string]: boolean} ``` -In order to use any of the Rojo APIs, you must first explicitly request them with this function. Users will be prompted to allow/deny each API, (this function will yield until the user responds) and then the function will return a dictionary where the keys are the requested APIs and the values are booleans which represent the access status (whether or not access was granted). +In order to use any of the Rojo APIs, you must first explicitly request them with this function. Users will be prompted to allow/deny each API, (this function will yield until the user responds) and then the function will return a dictionary where the keys are the requested APIs and the values are booleans which represent the access status (whether or not access was granted). The first argument must be your `plugin` object for security and reliability purposes, and the second argument is a list of APIs you're requesting access to. **In order to keep our users safe from malicious plugins, RequestAccess must be the first function your plugin calls when using the Rojo API.** Attempting to use an API without requesting it beforehand will throw an error. The only exceptions to this are `Rojo.Version` and `Rojo.ProtocolVersion`, since those are useful in checking compatibility before anything else is done. Example Plugin: ```Lua -local granted = Rojo:RequestAccess({ "Connected", "ConnectAsync" }) +local granted = Rojo:RequestAccess(plugin, { "Connected", "ConnectAsync" }) --[[ granted = { Connected = true, -- User granted access From 70b60ae79a25986f6d6748f16a209cf674b9e71c Mon Sep 17 00:00:00 2001 From: boatbomber Date: Mon, 4 Sep 2023 08:54:16 -0700 Subject: [PATCH 15/20] Update docs to match new modulescript behavior --- docs/headless-api.md | 55 +++++++++++++++++++------------------------- 1 file changed, 24 insertions(+), 31 deletions(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 0896f3cf..bb37e5f9 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -3,29 +3,22 @@ title: Rojo Plugin APIs sidebar_position: 7 --- -The Rojo Studio plugin exposes a headless API into `_G`, which is very valuable to the Rojo ecosystem. This allows you to make companion plugins that interact with Rojo! +The Rojo Studio plugin exposes a headless API into `game.Rojo`, which is very valuable to the Rojo ecosystem. This allows you to make companion plugins that interact with Rojo! ## Accessing the API -Plugins and command bar all share the same environment, which allows us to expose the API through `_G`. Using the key `"Rojo"` is easy to remember and follows branding. +Plugins and command bar all share the same environment, which allows us to expose the API through a ModuleScript located at `game.Rojo`. Using the name `"Rojo"` is easy to remember and follows branding. Once you've required Rojo, the API will be located at `Rojo.API`. For example: ```Lua -local Rojo = _G.Rojo +local Rojo = require(game.Rojo) +print(Rojo.API.Version) ``` However, plugins load in random order which means that your plugin might load before Rojo does. Therefore, the safe way to access is: ```Lua -local function GetRojo() - local api = _G.Rojo - while not api do - task.wait() - api = _G.Rojo - end - return api -end - -local Rojo = GetRojo() +local Rojo = require(game:WaitForChild("Rojo", math.huge)) +print(Rojo.API.Version) ``` ## API Documentation @@ -33,15 +26,15 @@ local Rojo = GetRojo() ### Functions ```Lua -Rojo:RequestAccess(plugin: Plugin, apis: {string}): {[string]: boolean} +Rojo.API:RequestAccess(plugin: Plugin, apis: {string}): {[string]: boolean} ``` In order to use any of the Rojo APIs, you must first explicitly request them with this function. Users will be prompted to allow/deny each API, (this function will yield until the user responds) and then the function will return a dictionary where the keys are the requested APIs and the values are booleans which represent the access status (whether or not access was granted). The first argument must be your `plugin` object for security and reliability purposes, and the second argument is a list of APIs you're requesting access to. -**In order to keep our users safe from malicious plugins, RequestAccess must be the first function your plugin calls when using the Rojo API.** Attempting to use an API without requesting it beforehand will throw an error. The only exceptions to this are `Rojo.Version` and `Rojo.ProtocolVersion`, since those are useful in checking compatibility before anything else is done. +**In order to keep our users safe from malicious plugins, RequestAccess must be the first function your plugin calls when using the Rojo API.** Attempting to use an API without requesting it beforehand will throw an error. The only exceptions to this are `Rojo.API.Version` and `Rojo.API.ProtocolVersion`, since those are useful in checking compatibility before anything else is done. Example Plugin: ```Lua -local granted = Rojo:RequestAccess(plugin, { "Connected", "ConnectAsync" }) +local granted = Rojo.API:RequestAccess(plugin, { "Connected", "ConnectAsync" }) --[[ granted = { Connected = true, -- User granted access @@ -55,27 +48,27 @@ granted = { ```Lua -Rojo:ConnectAsync(host: string?, port: string?): void +Rojo.API:ConnectAsync(host: string?, port: string?): void ``` Attempts to connect Rojo to the given host and port. Same behavior as the user clicking the Connect button (sync locking, etc., all behave the same). ```Lua -Rojo:DisconnectAsync(): void +Rojo.API:DisconnectAsync(): void ``` Attempts to disconnect any active sync session. ```Lua -Rojo:GetSetting(setting: string): any +Rojo.API:GetSetting(setting: string): any ``` Returns the value of the given setting. ```Lua -Rojo:SetSetting(setting: string, value: any): void +Rojo.API:SetSetting(setting: string, value: any): void ``` Sets the value of the given setting. ```Lua -function Rojo:Notify(msg: string, timeout: number?, actions: { [string]: {text: string, style: string, layoutOrder: number, onClick: (any) -> ()} }?): () -> () +function Rojo.API:Notify(msg: string, timeout: number?, actions: { [string]: {text: string, style: string, layoutOrder: number, onClick: (any) -> ()} }?): () -> () ``` Sends a Rojo notification that indicates it comes from a third-party plugin. Returns a function that dismisses the notification. @@ -83,45 +76,45 @@ Sends a Rojo notification that indicates it comes from a third-party plugin. Ret ```Lua -Rojo:GetHostAndPort(): (string, string) +Rojo.API:GetHostAndPort(): (string, string) ``` Returns the user's chosen host and port. ```Lua -Rojo:CreateApiContext(baseUrl: string): ApiContext +Rojo.API:CreateApiContext(baseUrl: string): ApiContext ``` Returns a new ApiContext using the given baseUrl. ### Properties *(All read-only)* ```Lua -Rojo.Version: {number} +Rojo.API.Version: {number} ``` The Rojo plugin version. (Example: `{7, 2, 1}`) ```Lua -Rojo.ProtocolVersion: number +Rojo.API.ProtocolVersion: number ``` The Rojo plugin's protocol version. ```Lua -Rojo.Connected: boolean +Rojo.API.Connected: boolean ``` Whether Rojo is currently connected to a serve session. ```Lua -Rojo.Address: string? +Rojo.API.Address: string? ``` -When `Rojo.Connected` is `true`, this contains the address of the connected session. +When `Rojo.API.Connected` is `true`, this contains the address of the connected session. ```Lua -Rojo.ProjectName: string? +Rojo.API.ProjectName: string? ``` -When `Rojo.Connected` is `true`, this contains the project name of the connected session. +When `Rojo.API.Connected` is `true`, this contains the project name of the connected session. ### Events ```Lua -Rojo.Changed: RbxScriptSignal (changedProperty: string, newValue: any?, oldValue: any?) +Rojo.API.Changed: RbxScriptSignal (changedProperty: string, newValue: any?, oldValue: any?) ``` Fires when any property changes. Passes the name of the changed property and its new and old values. From a68b7a2e949e4bc3feb88a0ed33c55d2c0b1461f Mon Sep 17 00:00:00 2001 From: boatbomber Date: Mon, 4 Sep 2023 08:57:05 -0700 Subject: [PATCH 16/20] Update env to module cache for specificity --- docs/headless-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index bb37e5f9..134b0673 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -7,7 +7,7 @@ The Rojo Studio plugin exposes a headless API into `game.Rojo`, which is very va ## Accessing the API -Plugins and command bar all share the same environment, which allows us to expose the API through a ModuleScript located at `game.Rojo`. Using the name `"Rojo"` is easy to remember and follows branding. Once you've required Rojo, the API will be located at `Rojo.API`. For example: +Plugins and command bar all share the same module cache, which allows us to expose the API through a ModuleScript located at `game.Rojo`. Using the name `"Rojo"` is easy to remember and follows branding. Once you've required Rojo, the API will be located at `Rojo.API`. For example: ```Lua local Rojo = require(game.Rojo) From d84569c02942fa183508380dbe616e2cccf5fd49 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Tue, 13 Feb 2024 01:15:18 -0800 Subject: [PATCH 17/20] Update docs to reflect latest headless api --- docs/headless-api.md | 38 ++++++++++++++++++++++---------------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 134b0673..dad36a0e 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -26,24 +26,30 @@ print(Rojo.API.Version) ### Functions ```Lua -Rojo.API:RequestAccess(plugin: Plugin, apis: {string}): {[string]: boolean} +Rojo.API:RequestAccess(plugin: Plugin, apis: {string}): boolean ``` -In order to use any of the Rojo APIs, you must first explicitly request them with this function. Users will be prompted to allow/deny each API, (this function will yield until the user responds) and then the function will return a dictionary where the keys are the requested APIs and the values are booleans which represent the access status (whether or not access was granted). The first argument must be your `plugin` object for security and reliability purposes, and the second argument is a list of APIs you're requesting access to. +In order to use any of the Rojo APIs, you must first explicitly request them with this function. Users will be prompted to allow/deny access to the headless API, (this function will yield until the user responds) and then the function will return a boolean which represents whether or not access was granted. -**In order to keep our users safe from malicious plugins, RequestAccess must be the first function your plugin calls when using the Rojo API.** Attempting to use an API without requesting it beforehand will throw an error. The only exceptions to this are `Rojo.API.Version` and `Rojo.API.ProtocolVersion`, since those are useful in checking compatibility before anything else is done. +The first argument must be your `plugin` object for security and reliability purposes, and the second argument is a list of API members you're requesting access to. -Example Plugin: +**In order to keep our users safe from malicious plugins, RequestAccess must be the first function your plugin calls when using the Rojo API.** Attempting to use an API without requesting it beforehand will throw an error. The only exceptions to this are `Rojo.API.Version` and `Rojo.API.ProtocolVersion`, since those are useful in checking compatibility before any work is done. + +Example Usage: ```Lua -local granted = Rojo.API:RequestAccess(plugin, { "Connected", "ConnectAsync" }) ---[[ -granted = { - Connected = true, -- User granted access - ConnectAsync = false, -- User denied access -} ---]] +local granted = Rojo.API:RequestAccess(plugin, { + "ProjectName", + "Address", + "Connected", + "Changed", + "CreateApiContext", + "DisconnectAsync", + "Notify", + "ConnectAsync", + "GetHostAndPort", +}) ``` -![image](https://user-images.githubusercontent.com/40185666/210909337-3caf5af4-0829-447c-9781-da3996c71284.png) +![requestPrompt](https://github.com/boatbomber/rojo.space/assets/40185666/ef9d0bcd-e39a-46ee-aec6-656c85699d5e) @@ -68,7 +74,7 @@ Rojo.API:SetSetting(setting: string, value: any): void Sets the value of the given setting. ```Lua -function Rojo.API:Notify(msg: string, timeout: number?, actions: { [string]: {text: string, style: string, layoutOrder: number, onClick: (any) -> ()} }?): () -> () +Rojo.API:Notify(msg: string, timeout: number?, actions: { [string]: {text: string, style: string, layoutOrder: number, onClick: () -> ()} }?): () -> () ``` Sends a Rojo notification that indicates it comes from a third-party plugin. Returns a function that dismisses the notification. @@ -78,12 +84,12 @@ Sends a Rojo notification that indicates it comes from a third-party plugin. Ret ```Lua Rojo.API:GetHostAndPort(): (string, string) ``` -Returns the user's chosen host and port. +Returns the user's chosen host and port, even if not actively connected to it. ```Lua Rojo.API:CreateApiContext(baseUrl: string): ApiContext ``` -Returns a new ApiContext using the given baseUrl. +Returns a new ApiContext using the given baseUrl. Useful for complex use cases that directly interface with Rojo endpoints. ### Properties *(All read-only)* @@ -117,4 +123,4 @@ When `Rojo.API.Connected` is `true`, this contains the project name of the conne ```Lua Rojo.API.Changed: RbxScriptSignal (changedProperty: string, newValue: any?, oldValue: any?) ``` -Fires when any property changes. Passes the name of the changed property and its new and old values. +Fires when a property of the headless API changes. Passes the name of the changed property and its new and old values. From fd81448a913258b2a2c84fee95643a947c1aa900 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Tue, 13 Feb 2024 01:17:46 -0800 Subject: [PATCH 18/20] Document `Rojo.API:Test(...)` --- docs/headless-api.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/headless-api.md b/docs/headless-api.md index dad36a0e..53d9bbad 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -91,6 +91,11 @@ Rojo.API:CreateApiContext(baseUrl: string): ApiContext ``` Returns a new ApiContext using the given baseUrl. Useful for complex use cases that directly interface with Rojo endpoints. +```Lua +Rojo.API:Test(...) +``` +Prints the given arguments to the console. Useful during development for testing purposes. + ### Properties *(All read-only)* ```Lua From 03a5856fd19add07a97f01bbe1f11d88cea4459b Mon Sep 17 00:00:00 2001 From: boatbomber Date: Tue, 13 Feb 2024 18:32:23 -0800 Subject: [PATCH 19/20] Remove SetSettings --- docs/headless-api.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 53d9bbad..4cd46e68 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -68,11 +68,6 @@ Rojo.API:GetSetting(setting: string): any ``` Returns the value of the given setting. -```Lua -Rojo.API:SetSetting(setting: string, value: any): void -``` -Sets the value of the given setting. - ```Lua Rojo.API:Notify(msg: string, timeout: number?, actions: { [string]: {text: string, style: string, layoutOrder: number, onClick: () -> ()} }?): () -> () ``` From 9531e5b972c5fa6e60356b3ea3aa334396689fb7 Mon Sep 17 00:00:00 2001 From: boatbomber Date: Tue, 24 Dec 2024 01:12:10 -0800 Subject: [PATCH 20/20] Update notif example image --- docs/headless-api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/headless-api.md b/docs/headless-api.md index 4cd46e68..c6e60736 100644 --- a/docs/headless-api.md +++ b/docs/headless-api.md @@ -73,8 +73,7 @@ Rojo.API:Notify(msg: string, timeout: number?, actions: { [string]: {text: strin ``` Sends a Rojo notification that indicates it comes from a third-party plugin. Returns a function that dismisses the notification. -![image](https://github.com/boatbomber/rojo.space/assets/40185666/c3f31715-dcdd-4c9d-b947-8dceee606b61) - +![exampleNotif](https://github.com/user-attachments/assets/ebae8c2f-ab9b-4088-8479-068d036a4243) ```Lua Rojo.API:GetHostAndPort(): (string, string)