Initial commit

0-index.md

@@ -0,0 +1,17 @@
+## OpenAction
+
+### Welcome!
+
+OpenAction is a platform-agnostic, language-agnostic, device-agnostic open WebSocket-based API for providing actions to an OpenAction server for execution on device events such as key presses or dial rotations.
+
+OpenAction is cross-compatible with the Stream Deck SDK, bringing a plethora of excellent plugins to the platform.
+
+This website contains documentation for developers of both plugins and servers.
+
+### Getting started
+
+1. [Architecture](1-architecture.md)
+2. [Manifest](2-manifest.md)
+3. [Registration](3-registration.md)
+4. [Clientbound events](4-clientbound.md)
+5. [Serverbound events](5-serverbound.md)

1-architecture.md

@@ -0,0 +1,13 @@
+## Architecture
+
+OpenAction is an event-driven API that communicates over WebSocket.
+
+Plugins provide actions, which can be instantiated by users on multiple profiles across multiple devices simultaneously. Each action instance is created from the properties specified in the plugin manifest, after which its states and settings can be mutated and these changes retained.
+
+Each action may also be accompanied by a property inspector, a user interface displayed when the action is selected, where the user may customise the behaviour of the action. The `setSettings`, `getSettings`, `setGlobalSettings`, and `getGlobalSettings` events may be used by both the plugin and property inspector.
+
+Users may also configure "Multi Actions", where multiple actions are executed in sequence.
+
+Events are represented in (stringified) JSON format, with a field to identify the event and an optional payload containing more information about the event, as well as an instance context if the event is instance-related in order to identify it.
+
+For more information about a specific event, consult the [clientbound events](4-clientbound.md) and [serverbound events](5-serverbound.md) pages.

2-manifest.md

@@ -0,0 +1,86 @@
+## Manifest
+
+Your plugin should contain a `manifest.json` file that supplies key information about your plugin to the OpenAction server. It should be present in the root of your plugin directory.
+
+```ts
+{
+	// The human-readable name of your plugin. Required
+	Name: string, // Required
+	// The user-facing author string (e.g. "ninjadev64"). Required
+	Author: string,
+	// The version of your plugin found in this directory. Required
+	Version: string,
+	// An icon to represent your plugin, relative to your plugin root. Required
+	// This icon should be provided in PNG format, without the ".png" suffix. You may also provide @2x versions of this image.
+	Icon: string,
+	// The category for your plugin's actions to appear under.
+	Category: string = "Custom",
+	// The default path to your actions' property inspector.
+	PropertyInspectorPath: string | null,
+	// The actions provided by your plugin. Required
+	Actions: [
+		{
+			// The name of this action. Required
+			Name: string,
+			// A unique identifier for this action. Required
+			UUID: string,
+			// A tooltip that sums up the purpose of this action.
+			Tooltip: string = "",
+			// An icon to represent this action, relative to your plugin root. Required if visible in action list
+			// This icon should be provided in PNG format, without the ".png" suffix. You may also provide @2x versions of this image.
+			Icon: string,
+			// Whether or not to automatically toggle the state of this action on key up. Only applies to actions with two states.
+			DisableAutomaticStates: boolean = false,
+			// Whether or not this action should be visible in the action list.
+			VisibleInActionsList: boolean = true,
+			// Whether or not this action should be supported in Multi Actions.
+			SupportedInMultiActions: boolean = true,
+			// The path to this action's property inspector, if different to your plugin's default.
+			PropertyInspectorPath: string = "<plugin default>",
+			// The controllers this action should be supported on. Supported controllers are "Keypad" and "Encoder" (dials/sliders).
+			Controllers: string[] = [ "Keypad" ],
+			// The states that are part of this action. Required
+			States: [
+				{
+					// The image of this state relative to your plugin root or "actionDefaultImage".
+					Image: string = "actionDefaultImage",
+					// The name of this state.
+					Name: string = "",
+					// The text to display on this state over the image.
+					Title: string = "",
+					// Whether or not to display the title over the image.
+					ShowTitle: boolean = true,
+					// The colour of the state title.
+					TitleColor: string = "<server dependent>",
+					// The vertical alignment of the state title, either "top", "middle", or "bottom".
+					TitleAlignment: string = "middle",
+					// The font style of the title, either "Regular", "Bold", "Italic", or "Bold Italic".
+					FontStyle: string = "Regular",
+					// The font size of the state title in pixels as rendered on a 72x72px state image.
+					FontSize: string = "16",
+					// Whether or not to underline the state title.
+					FontUnderline: boolean = false
+				}
+			]
+		}
+	],
+	// The operating systems your plugin is supported on. Required
+	OS: [
+		{
+			// The platform in question. Can be "windows", "mac", or "linux". Note that "linux" is not supported by Stream Deck. Required
+			Platform: string,
+			// The minimum supported version of the platform in question.
+			Version: string | null
+		}
+	],
+	// The default path to your plugin executable file, relative to your plugin root.
+	// HTML5 is supported if this value ends with the ".html" suffix, and Node.js if this value ends with either of the ".cjs" and ".mjs" suffixes.
+	CodePath: string | null,
+	// An override for CodePath on Windows.
+	CodePathWin: string | null,
+	// An override for CodePath on macOS.
+	CodePathMac: string | null,
+	// An override for CodePath on Linux.
+	CodePathLin: string | null
+}
+```

3-registration.md

@@ -0,0 +1,91 @@
+## Registration
+
+The OpenAction server will start your plugin with arguments specifying the means of initialising the WebSocket connection. If you use a plugin SDK, such as openaction-rs, you may be able to skip these steps.
+
+### Compiled plugin registration
+
+Your plugin will be called with the following command-line argument format.
+
+`yourplugin -port <port> -pluginUUID <uuid> -registerEvent <event> -info <info>`
+
+Your plugin should initiate a WebSocket connection to the WebSocket server running on the specified port and send a registration event containing the supplied registration event and plugin UUID, similar to the procedure outlined for HTML5 plugins described below.
+
+### HTML5 plugin registration
+
+Your plugin should provide a function similar to the below to register the plugin with the OpenAction server. This function will be called automatically by the OpenAction server.
+
+```js
+function connectOpenActionSocket(port, pluginUUID, registerEvent, info) {
+	const websocket = new WebSocket("ws://localhost" + port);
+
+	websocket.onopen = () => {
+		websocket.send(JSON.stringify({
+			"event": registerEvent,
+			"uuid": pluginUUID
+		}));
+	};
+
+	websocket.onmessage = (event) => {
+		// Handle inbound events from the OpenAction server here
+	};
+}
+
+// For Stream Deck compatibility
+const connectElgatoStreamDeckSocket = connectOpenActionSocket;
+```
+
+### Property inspector registration
+
+Your property inspectors should provide functions similar to the below to register themselves with the OpenAction server. These functions will be called automatically by the OpenAction server.
+
+```js
+function connectOpenActionSocket(port, propertyInspectorUUID, registerEvent, info) {
+	const websocket = new WebSocket("ws://localhost" + port);
+
+	websocket.onopen = () => {
+		websocket.send(JSON.stringify({
+			"event": registerEvent,
+			"uuid": propertyInspectorUUID
+		}));
+	};
+
+	websocket.onmessage = (event) => {
+		// Handle inbound events from the OpenAction server here
+	};
+}
+
+// For Stream Deck compatibility
+const connectElgatoStreamDeckSocket = connectOpenActionSocket;
+```
+
+### Info parameter
+
+The info parameter supplied to both plugins and property inspectors is in the below format.
+
+```ts
+{
+	application: {
+		font: string,
+		language: string, // e.g. "en"
+		platform: string, // e.g. "mac"
+		platformVersion: string, // e.g. "11.6.2"
+		version: string // e.g. "OpenDeck 2.0.0"
+	},
+	plugin: {
+		uuid: string, // e.g. "com.amansprojects.starterpack"
+		version: string // e.g. "1.0.0"
+	},
+	devices: [
+		{
+			id: string,
+			name: string,
+			size: {
+				rows: number,
+				columns: number
+			}
+		}
+	]
+}
+```
+
+The Stream Deck software supplies additional fields in this parameter, such as an integer to designate the model of Stream Deck in use.