-
-
Notifications
You must be signed in to change notification settings - Fork 2
Addons
OC+ provides an API for users to create custom addons.
This page documents how to use such API and example usecases.
local RS = game:GetService("RunService")
return {
id = "coolexample",
title = "Cool Example Addon",
description = "A very cool addon which does absolutely nothing.",
version = 1.0,
author = 304346361,
github = "https://raw.githubusercontent.com/Gabe616/OCPlus/main/addons/example.lua",
icon = "11176073563",
settings = {
{
name = "Be Cool",
id = "cool",
type = "toggle",
description = "Makes the addon 200% cooler."
},
{
name = "Do Cool Thing",
id = "coolkb",
type = "keybind",
description = "The key to press to do cool thing."
},
{
name = "Cool Type",
id = "coolsw",
type = "choose",
description = "Type of coolness",
choose = {"Meh", "Very Cool"}
},
},
data = {
cool = false,
coolkb = "Return", -- Keybinds are saved as strings so they can be saved to a JSON file
coolsw = "Meh"
},
run = {
start = function(Util)
Util.log("Enabled!")
Util.run.update(Util)
end,
input = function(Util, input)
if input.KeyCode.Name == Util.data.coolkb then
Util.log("Pressed the swag key!")
end
end,
update = function(Util, key)
if key then -- Called by addon manager
Util.log(("%s has been changed to %s!"):format(key, tostring(Util.data[key])))
end
Util.removeEvent("coolness") -- Unregisters the coolness event
if Util.data.cool then
-- Registers coolness event again only if cool is set to true
Util.addEvent("coolness", RS.RenderStepped:Connect(function()
Util.log(("Coolness currently set to: %s"):format(Util.data.coolsw))
-- This is just an example, do NOT do this! It will clog up the console
end))
end
end,
stop = function(Util)
Util.log("Shutting down!")
-- RenderStepped is automatically unregistered
end
},
}For more addons, see the addons directory
To create an Addon, use the boilerplate code below:
local RS = game:GetService("RunService")
return {
title = "Hello World!",
description = "An example addon.",
version = 1.0,
author = 304346361
}When your Addon gets accepted, a github parameter will be automatically added for updating, just like so:
-- Everything must be in the return {...}
github = "https://raw.githubusercontent.com/Gabe616/OCPlus/main/addons/helloworld.lua"To add settings, add the settings table to the return function:
-- Everything must be in the return {...}
settings = {
{
name = "Toggle Example",
id = "toggle",
type = "toggle",
description = "An example of a toggle!"
},
{
name = "Number Example",
id = "number",
type = "number",
description = "An example of a number value!"
},
{
name = "Keybind Example",
id = "key",
type = "keybind",
description = "An example of a keybind!"
},
}To use those settings, add the data table.
-- Everything must be in the return {...}
data = { -- This is required in order to use these settings in your script
toggle = false,
key = "Return", -- Keybinds are saved as strings so they can be saved to a JSON file
number = 118118
},Finally, the run table contains the addon code.
-- Everything must be in the return {...}
run = {
start = function(Util)
Util.log("Enabled!")
Util.run.update(Util)
end,
input = function(Util, input)
if input.KeyCode.Name == Util.data.coolkb then
Util.log("Pressed the swag key!")
end
end
update = function(Util, key)
if key then -- Called by addon manager
Util.log(("%s has been changed to %s!"):format(key, Util.data[key]))
end
Util.removeEvent("coolness") -- Unregisters the coolness event
if Util.data.cool then
-- Registers coolness event again only if cool is set to true
Util.addEvent("coolness", RS.RenderStepped:Connect(function()
Util.log(("Coolness currently set to: %s"):format(Util.data.coolsw))
-- This is just an example, do NOT do this! It will clog up the console
end))
end
end,
stop = function(Util)
Util.log("Shutting down!")
-- RenderStepped is automatically unregistered
end
}The Addon object.
The Addon's custom ID.
The Addon's visible title
The Addon's description
The Addon's version
The Addon's author user ID
Link to a raw github URL to your Addon
(optional) ID of an image used as the icon of the Addon
Array of Setting objects
The Setting object
Visual name of the setting
Hidden ID of the setting
The type of the setting Can be:
-
toggle— checkbox -
choose— dropdown -
string— text -
number— number -
keybind— keybind
(optional) If Setting.type is set to number, then it's the minimum value; otherwise it's the minimum length for string
Defaults to 0 for string and -999999999 for number.
(optional) If Setting.type is set to number, then it's the maximum value; otherwise it's the maximum length for string
Defaults to 999999999 for string and 999999999 for number.
The description of the setting
(optional) Available options for the setting.
(Only used for the setting type choose)
An object of the Addon's save data (must be JSON friendly!)
Dictionary containing the Addon's runner functions
The Runner object. All runner functions are surrounded by pcall() and errors logged with Util.error.
The function that gets ran when the addon is enabled. This function is not required, but will throw a warning if not provided.
Passed arguments:
- Util — The Addon's Util object
(optional) The function that gets ran when a setting is changed.
Passed arguments:
- Util — The Addon's Util object
- key — The Setting's ID that was changed.
(optional) The function that gets ran when a key is pressed.
Passed arguments:
- Util — The Addon's Util object
- input — The InputObject
The function that gets ran when the addon is disabled or the script is reloaded. This function is not required, but will throw a warning if not provided.
Passed arguments:
- Util — The Addon's Util object
The Util object
The Addon.data object
The Addon.run object
Whether the player can enable/disable the addon or change a setting.
Disables the addon. Automatically runs Util.removeAllEvents and Runner.stop
Logs a message to the console with the addon's name prepended.
Warns a message to the console with the addon's name prepended.
Errors a message to the console with the addon's name prepended.
Used for safely registering addon-only events
Removes an addon-only event and returns it
Removes all of the addon-only events.
If you want to test your Addon, simply navigate to your executor's workspace folder. There, you will find a folder called ocplus. If there isn't such folder, execute the OC+ script and look again. Then, navigate to ocplus/addons and create a file called YOUR_ADDON.lua and paste your addon into it.
Do you feel like something is missing, or just want to help out? Create an issue/pull request!