User:Anaminus/CmdUtl/doc/plugins

[ Incomplete ]

Plugins are additions to CmdUtl that have been written by users. Using the Plugin API, tools, commands, or entire menus can be added.

Plugins can be published by uploading them as a model to Roblox.

Since CmdUtl runs from Execute Script, it has a greater security context, allowing access to more things. For this reason, plugins have two modes: Safe and Unsafe Mode. Safe Mode limits the access of the plugin, preventing a user from doing malicious things. Unsafe Mode gives access to not only the API, but everything else, including potentially hazardous Roblox functions. Luckily, CmdUtl users can prevent Unsafe plugins from running by adjusting their config table.

Writting a Plugin

This section describes how to write the source code for a plugin. As an example, you will be shown how to create a basic rotation tool.

Initial Declarations

To start out, you need to define the name and type of the plugin. This can be done with the SetPluginName and SetPluginType functions. These should always be the first functions called in the plugin source.

SetPluginName("RotateSingle")
SetPluginType("tool")

The plugin's Name will be the primary identifier of that plugin. Make sure this name is unique, so it doesn't conflict with other plugins. However, the plugin name can only contain letters, numbers, and underscores (_). The first character in the name cannot be a number.

The plugin's Type can be "tool", "menu", or "command". While the tool type will create one single tool, the menu type will create an entire menu. The command type will create a new command function for the Command Line.

Note that you can call SetPluginName and SetPluginType only once.

Optionally, you can also set the safety mode of the plugin with SetPluginSafe.

SetPluginSafe(true)

Since the safety mode defaults to true, this function doesn't have to be called. However, it still can only be called once.

Also, you can add a resource value, which can be used later in your code.

AddResource("HandleColor", BrickColor.new("Bright green") )

This function can be called multiple times, so you can add as many resources as you need. Note that value types of function, thread, or nil cannot be added as a resource. If a string value added as a resource is found to be a Content reference (images, sound meshes, etc), the content will be preloaded.

Context Switches

When you call SetPluginType, more functions are enabled for you to use. Different functions are enabled depending on the plugin's type (that's why SetPluginType needs to be called first). Now you can start setting information specific to the plugin type you chose.

In the next example, we will set information for the "tool" plugin type.

SetButtonText("Single")
SetDescription("Rotates each selection by it's angle")
SetWarnings({"No parts selected"})

Be sure to check out the API section for a description of each function.

Before we define the functionality of the tool, we can set local variables, which can be used later as upvalues by the tool listener. Make sure they are local!

local axisnum = {
	[Enum.Axis.X] = 1;
	[Enum.Axis.Y] = 2;
	[Enum.Axis.Z] = 3;
}

Now we can define how the tool will work with the SetOnSelect function. The function passed to it is the one that will be called when the tool is selected (the listener).

SetOnSelect(function()
	local selection = GetFilteredSelection("BasePart")
	if #selection > 0 then
		OverlayArcHandles.Color = Resource("HandleColor")
		OverlayArcHandles.Visible = true
		WrapOverlay(selection[1])
		local origin = {}
		local ocf = GetOverlayCFrame()
		local inc = GetButtonValue("Inc")
		Connect(OverlayArcHandles.MouseButton1Down,function(axis)
			for _,part in pairs(selection) do
				origin[part] = part.CFrame
			end
			ocf = GetOverlayCFrame()
			inc = GetButtonValue("Inc")
			SetButtonValue("Delta",0)
		end)
		Connect(OverlayArcHandles.MouseDrag,function(axis,angle)
			local rdis = Round(math.deg(angle),inc)
			local input = {0;0;0}
			input[axisnum[axis]] = math.rad(rdis)
			local new = CFrame.Angles(unpack(input))
			for part,cframe in pairs(origin) do
				part.CFrame = cframe * new
			end
			SetOverlayCFrame(ocf * new)
			SetButtonValue("Delta",Round(math.abs(rdis),0.00001))
		end)
	else
		SetWarning()
	end
end)

Note all the variables used by this function. These variables are used for accessing values defined elsewhere in the plugin source, or for performing basic tasks that you might need for a tool. You can view descriptions for each variable in the Tool Listener Environment section.

Validation

Validation is the final part in running a plugin source. This will make sure that the source has provided the correct data for creating the plugin. The Validate function does all of this. Because of its nature, it should always be the last function called.

Validate()

Once this function has been called, it signals the end of the plugin source.

Debugging

The plugin API is rather strict when it comes to verification. Any time there's a problem, the source is aborted, and your plugin will simply not be created. Lucky for you, it also spits out the specific error that occurred, so you can easily fix it. You can view these errors in the Output Panel. They will be preceded by a LOG_ERROR:</syntaxhighlight> or LOG_WARNING:</syntaxhighlight> message. Note that while log errors will stop the source entirely, log warnings will only notify you about something, then continue running the source.

If you get an actual error (with red text), that is an error with CmdUtl, and you should let me know about it.

The plugins table allows you to reference a Script in the game. This is so you can debug your plugin more rapidly. Make sure you use it.

As with anything you create, make sure you've thoroughly debugged your plugin before releasing it into the world.

View the full Example Source.

Publishing a Plugin

CmdUtl accesses plugins through models that are uploaded to Roblox. A model contains one or more Script objects, each of which contains the source of one plugin. With this, multiple plugins can be loaded through one model. The following are acceptable structures of the uploaded model:
The model can consist of one or more Script objects.

Script
Script
...

The model can consist of one Model object, which contains one or more Script objects.

Model
Script
Script
...

Any models that do not follow any of these structures are considered invalid. Any stray objects that may be included in the model will invalidate the model, and its plugins will not be loaded. Make sure you've selected only the objects you intend to upload.
Names of the objects are ignored, and play no role in the loading of the plugins.

API

This section describes each function available in the Plugin API. These functions are held in various environments, and will be available to you depending on certain contexts.

Source Environment

This is the top environment. It contains the functions that will allow you to build your plugin.
The following standard global variables are available in the Source Environment:

Axes, BrickColor, CFrame, Color3, Enum, Faces, Ray, Region3, UDim, UDim2, Vector2, Vector3

Here are the available functions in the Source Environment:



Function

Description


SetPluginName ( string name )

This function sets the name of the Plugin. It can only be called once.


SetPluginType ( string type )

This function sets the type of the Plugin. type may only be "tool", "menu" or "command", but it is not case-sensitive. Once this is called, Context Type functions will be added to the Source Environment, depending on type. This should be one of the first functions called, and can only be called once.


SetPluginSafe ( bool isSafe )

This function sets whether the Plugin has Safe Mode enabled. Since Safe Mode defaults to true, this function may be called optionally. However, it still may only be called once.


AddResource ( string key, * value )

This function adds value a resource to be used by Tool Listeners or Command functions. The resource is indexed by key. value may be of any type except function, thread, or nil. This function may be called as many times as needed, but only once per key.


Validate ()

This function makes sure that the data generated can be successfully used to make the Plugin. It also indicates the end of Plugin creation, so it should be the last function called.

Context Type Environment

These functions are added to the Source Environment depending on what value is passed to the SetPluginType function.

Tool

This plugin type creates one single tool, without the need for creating an entire menu for it. These tools will be available under the "Plugin" menu on the Utility Panel.
Here are the available functions in the Tool Type Environment:



Function

Description


SetButtonText ( string text )

This function sets the text that will appear on the tool button. It must be called, and may only be called once.


SetOnToolSelect ( function hook )

This function sets the hook function that is called whenever the tool is selected. It must be called, and may only be called once.


SetOnToolDeselect ( function hook )

This function sets the hook function that is called whenever the tool is deselected. Because a tool may not need a deselect hook, this function may be called optionally, but still may only be called once.


SetToolDescription ( string desc )

This function sets a short description of the tool. It may be called optionally. If not called, a description will not appear for the tool. This function still may only be called once.


SetToolWarnings ( * warnings )

This function sets any warnings for the tool. This is for the Tool Hooks to use incase an error of some sort is encountered, and the user needs to be notified. warnings can be either a string (representing 1 warning) or a table (represent multiple warnings). If a table, it must be an array of strings. That is, the keys of the table may only be a sequence of integers, and the values may only be strings. This function can be called optionally, but may only be called once.

MenuCommandTool Listener Environment

Tool listeners are the functions called when a tool is selected or deselected. The environments of these listeners are separate from the Source Environment.

Standard Global Variables

Safe Mode: The following global variables are included in Safe Mode:

_VERSION
ipairs, next, pairs, pcall, print, select, tonumber, tostring, type, unpack, xpcall
coroutine, math, string, table
Delay, delay, printidentity, Spawn, tick, time, Version, version, Wait, wait
Axes, BrickColor, CFrame, Color3, Faces, Ray, Region3, UDim, UDim2, Vector2, Vector3
Enum

Unsafe Mode: Along with those in Safe Mode, the following global variables are included in Unsafe Mode:

assert, collectgarbage, dofile, error, gcinfo, getfenv, getmetatable,
load, loadfile, loadstring, newproxy, rawequal, rawget, rawset, setfenv, setmetatable
_G
crash__, LoadLibrary, LoadRobloxLibrary, settings, Stats, stats, UserSettings
game, Instance, shared

User:Anaminus/CmdUtl/doc/plugins

Contents

Writting a Plugin

Initial Declarations

Context Switches

Validation

Debugging

Publishing a Plugin

API

Source Environment

Context Type Environment

Tool

Menu

Command

Tool Listener Environment

Standard Global Variables

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Scripting Help

Legacy Client Help

Tools

Function	Description
SetPluginName ( string name )	This function sets the name of the Plugin. It can only be called once.
SetPluginType ( string type )	This function sets the type of the Plugin. type may only be "tool", "menu" or "command", but it is not case-sensitive. Once this is called, Context Type functions will be added to the Source Environment, depending on type. This should be one of the first functions called, and can only be called once.
SetPluginSafe ( bool isSafe )	This function sets whether the Plugin has Safe Mode enabled. Since Safe Mode defaults to true, this function may be called optionally. However, it still may only be called once.
AddResource ( string key, * value )	This function adds value a resource to be used by Tool Listeners or Command functions. The resource is indexed by key. value may be of any type except function, thread, or nil. This function may be called as many times as needed, but only once per key.
Validate ()	This function makes sure that the data generated can be successfully used to make the Plugin. It also indicates the end of Plugin creation, so it should be the last function called.

Function	Description
SetButtonText ( string text )	This function sets the text that will appear on the tool button. It must be called, and may only be called once.
SetOnToolSelect ( function hook )	This function sets the hook function that is called whenever the tool is selected. It must be called, and may only be called once.
SetOnToolDeselect ( function hook )	This function sets the hook function that is called whenever the tool is deselected. Because a tool may not need a deselect hook, this function may be called optionally, but still may only be called once.
SetToolDescription ( string desc )	This function sets a short description of the tool. It may be called optionally. If not called, a description will not appear for the tool. This function still may only be called once.
SetToolWarnings ( * warnings )	This function sets any warnings for the tool. This is for the Tool Hooks to use incase an error of some sort is encountered, and the user needs to be notified. warnings can be either a string (representing 1 warning) or a table (represent multiple warnings). If a table, it must be an array of strings. That is, the keys of the table may only be a sequence of integers, and the values may only be strings. This function can be called optionally, but may only be called once.