Updated some docs

2025-08-27 23:48:24 +02:00
parent 8f9ae8c8fc
commit 3b0c54b870
9 changed files with 479 additions and 224 deletions

@@ -1,4 +1,4 @@
# Module.json Condition # Module config Condition
A condition is a way for a cue list to wait till a condition is met. There are two types of conditions: server or client. A condition is a way for a cue list to wait till a condition is met. There are two types of conditions: server or client.
@@ -24,4 +24,4 @@ Although these two types of conditions function differently you specify them the
| title | Visual title of the condition | | title | Visual title of the condition |
| description | Short description that explains what the condition does | | description | Short description that explains what the condition does |
View this in a [complete module.json example](./module.json). View [module.json](./ModuleJSON.md).

@@ -1,5 +1,7 @@
# Module.json Property # Module config Property
Each property consists of a property-type, some metadata and of course the value. Below is an example of what a basic property looks like. Each property consists of a property-type, some metadata and of course the value. Below is an example of what a basic property looks like.
```JSON ```JSON
{ {
"title": "Property 1", "title": "Property 1",
@@ -9,28 +11,34 @@ Each property consists of a property-type, some metadata and of course the value
} }
``` ```
|Property|Description|
|-|-| | Property | Description |
name | Name of the property, this will be visible in the scene editor. | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
type | Property type, see below. | name | Name of the property, this will be visible in the scene editor. |
description | A description what the property does, this will be shown when a user clicks the questionmark next to the property in the scene editor. | type | Property type, see below. |
value | The default value for the property. | description | A description what the property does, this will be shown when a user clicks the questionmark next to the property in the scene editor. |
| value | The default value for the property. |
## Property Types ## Property Types
The property type specifies how the property should behave in the editor. Some properties have additional parameters you must/can set. Below you can find all property types and additional parameters. The property type specifies how the property should behave in the editor. Some properties have additional parameters you must/can set. Below you can find all property types and additional parameters.
### text ### text
Text input field Text input field
|Parameter|Type|Description| |Parameter|Type|Description|
|-|-|-| |-|-|-|
|value|string|The default value for the property. |value|string|The default value for the property.
### textarea ### textarea
Multiline text input field Multiline text input field
|Parameter|Type|Description| |Parameter|Type|Description|
|-|-|-| |-|-|-|
|value|string|The default value for the property. |value|string|The default value for the property.
### number ### number
Number input field Number input field
|Parameter|Type|Description| |Parameter|Type|Description|
|-|-|-| |-|-|-|
@@ -40,6 +48,7 @@ Number input field
|step|number|The step to increase/decrease with. |step|number|The step to increase/decrease with.
### slider ### slider
Range slider Range slider
|Parameter|Type|Description| |Parameter|Type|Description|
|-|-|-| |-|-|-|
@@ -49,17 +58,20 @@ Range slider
|step|number|The step to increase/decrease with. |step|number|The step to increase/decrease with.
### color ### color
Color picker Color picker
|Parameter|Type|Description| |Parameter|Type|Description|
|-|-|-| |-|-|-|
|value|string|The default value for the property. |value|string|The default value for the property.
### checkbox ### checkbox
|Parameter|Type|Description|
|-|-|-| | Parameter | Type | Description |
|value|boolean|The default value for the property. | --------- | ------- | ----------------------------------- |
| value | boolean | The default value for the property. |
### select ### select
Dropdown select Dropdown select
|Parameter|Type|Description| |Parameter|Type|Description|
|-|-|-| |-|-|-|
@@ -67,6 +79,7 @@ Dropdown select
|allowedValues|{id:string, text:string}[]|The values that can be selected. |allowedValues|{id:string, text:string}[]|The values that can be selected.
### file ### file
Select file from filebrowser Select file from filebrowser
|Parameter|Type|Description| |Parameter|Type|Description|
|-|-|-| |-|-|-|
@@ -75,6 +88,7 @@ Select file from filebrowser
|allowedTypes|string[]|Selectable file types. Can be `image`, `video`, `audio`, `font`, `pdf`, `animation`, `vectorImage` |allowedTypes|string[]|Selectable file types. Can be `image`, `video`, `audio`, `font`, `pdf`, `animation`, `vectorImage`
### textstyling ### textstyling
Property that contains multiple text styling sub properties. Property that contains multiple text styling sub properties.
Select file from filebrowser Select file from filebrowser
@@ -84,27 +98,31 @@ Select file from filebrowser
|allowedTypes|string[]|Which sub properties to show. Can be `size`, `color`, `bold`, `italic`, `underlined`, `strikethrough`, `align` |allowedTypes|string[]|Which sub properties to show. Can be `size`, `color`, `bold`, `italic`, `underlined`, `strikethrough`, `align`
### time ### time
Time selector Time selector
|Parameter|Type|Description| |Parameter|Type|Description|
|-|-|-| |-|-|-|
|value|number|The default value (unix epoch seconds) for the property. |value|number|The default value (unix epoch seconds) for the property.
### date ### date
Date selector Date selector
|Parameter|Type|Description| |Parameter|Type|Description|
|-|-|-| |-|-|-|
|value|number|The default value (unix epoch seconds) for the property. |value|number|The default value (unix epoch seconds) for the property.
### datetime ### datetime
Date + Time selector Date + Time selector
|Parameter|Type|Description| |Parameter|Type|Description|
|-|-|-| |-|-|-|
|value|number|The default value (unix epoch seconds) for the property. |value|number|The default value (unix epoch seconds) for the property.
### giphy ### giphy
Grab animation from Giphy Grab animation from Giphy
|Parameter|Type|Description| |Parameter|Type|Description|
|-|-|-| |-|-|-|
|value|null| |value|null|
View this in a [complete module.json example](./module.json). View [module.json](./ModuleJSON.md).

@@ -1,4 +1,4 @@
# Module.json Trigger # Module config Trigger
A trigger is a way for a cue list to call the server side of a module. This way you can control the module behavior automatically. You can also specify parameters to input values. A basic trigger with no parameters will look like this: A trigger is a way for a cue list to call the server side of a module. This way you can control the module behavior automatically. You can also specify parameters to input values. A basic trigger with no parameters will look like this:
@@ -60,4 +60,4 @@ Scene select argument
} }
``` ```
View this in a [complete module.json example](./module.json). View [module.json](./ModuleJSON.md).

@@ -0,0 +1,3 @@
# Module Development - Introduction
TODO

@@ -1,57 +1,108 @@
# Module.json # Module.json
The module.json is the main file for every module. It contains metadata that tells Getiyo what it is and it contains the modules properties, triggers & conditions. The [GetiyoModuleTool](./GetiyoModuleTool) will set this file up for you, but if you wish to change/add properties/triggers/conditions see the documentation below. There is also a [complete module.json example](./module.json). The module.json file serves as the central configuration file for each module in Getiyo. It contains essential metadata that informs Getiyo about the module's identity, as well as the module's properties, triggers, and conditions. The [GetiyoModuleTool](./GetiyoModuleTool) can automatically generate this file for you, streamlining the setup process. However, if you want to modify or add properties, triggers, or conditions, you can refer to the documentation provided below.
The module.json file serves as the central configuration file for each module in Getiyo. It contains essential metadata that informs Getiyo about the module's identity, as well as the module's properties, triggers, and conditions. The [GetiyoModuleTool](./GetiyoModuleTool) can automatically generate this file for you, streamlining the setup process. However, if you want to modify or add properties, triggers, or conditions, you can refer to the documentation provided below. For a full example of a module.json file, see the [complete module.json example](./module.json).
## Structure ## Structure
```JSON ```JSON
{ {
"name": "DemoModule", "name": "DemoModule",
"author": "Mees van der Wijk",
"category": "Debug",
"description": "A simple demo module!",
"default_reference_properties": { "author": "Mees van der Wijk",
"propertyId": { property } "category": "Widget",
}, "description": "Showcase the module!",
"default_module_properties": { "default_reference_properties": {
"propertyId": { property } "text": {
}, "type": "text",
"title": "Text",
"description": "The text for the demo!",
"value": "Hello world!"
},
"color": {
"type": "color",
"title": "Color",
"description": "The color of the demo.",
"value": "#f44336"
},
"style": {
"type": "select",
"title": "Style",
"description": "The style of the demo",
"value": "cool",
"allowedValues": [
{
"id": "cool",
"text": "Cool Demo"
},
{
"id": "fast",
"text": "Fast Demo"
},
{
"id": "slow",
"text": "Slow Demo"
}
]
}
},
"triggers": { "default_module_properties": {},
"triggerId": { trigger }
},
"conditions": { "triggers": {
"client": { "setText": {
"conditionId": { condition } "title": "Set text",
}, "description": "Set the text of the demo.",
"server": { "arguments": [
"conditionId": { condition } {
} "type": "scenes",
}, "title": "In scenes",
"onlyContainingModule": true
},
{
"type": "text",
"title": "New text"
}
]
}
},
"defaultsize": { "width": 400, "height": 400 }, "conditions": {
"defaultlocation": { "x": 100, "y": 100 } "server": {
"textStop": {
"title": "Text Stop",
"description": "Will be met when the text stops."
}
},
"client": {
}
},
"default_size": {
"width": 300,
"height": 300
},
"default_location": {
"x": 100,
"y": 100
}
} }
``` ```
| Property | Description | Example | | Property | Description | Example |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| name | The property name, used internally for creating an ID. Changing this will break modules using the old name. | | name | The property name, used internally for creating an ID. Changing this will break modules using the old name. |
| author | The module author. | | author | The module author. |
| category | A fitting category for the module. | | category | A fitting category for the module. |
| description | A short module description. | | description | A short module description. |
| default_reference_properties | An object with property IDs as keys and property objects as values. Reference properties are unique for each scene a module is a part of. These are also the properties you edit in the scene editor. See [property](./ModuleJSONProperty) for all parameters. | `{ property1: { property }, property2: { property } }` | | default_reference_properties | An object with property IDs as keys and property objects as values. Reference properties are unique for each scene a module is a part of. These are also the properties you edit in the scene editor. See [property](./ModuleConfigProperty) for all parameters. | `{ property1: { property }, property2: { property } }` |
| default_module_properties | An object with property IDs as keys and property objects as values. Module properties are shared for the entire module instance. See [property](./ModuleJSONProperty) for all parameters. | `{ property1: { property }, property2: { property } }` | | default_module_properties | An object with property IDs as keys and property objects as values. Module properties are shared for the entire module instance. See [property](./ModuleConfigProperty) for all parameters. | `{ property1: { property }, property2: { property } }` |
| triggers | An object with trigger IDs as keys and trigger data as values. Triggers allow a cue list to call the server-side of a module, controlling module behavior automatically. See [trigger](./ModuleTrigger) for all parameters. | `{ trigger1: { trigger }, trigger1: { trigger } }` | | triggers | An object with trigger IDs as keys and trigger data as values. Triggers allow a cue list to call the server-side of a module, controlling module behavior automatically. See [trigger](./ModuleConfigTrigger) for all parameters. | `{ trigger1: { trigger }, trigger1: { trigger } }` |
| conditions.client | An object with condition IDs as keys and condition data as values. A condition is a way for a cue list to wait till a condition is met. These are client conditions, they can be met via the [ModuleClientAPI](./ModuleClientAPI). Because the ModuleClientAPI runs on the machines of viewers which you can not trust, Getiyo has a system that allows cue list makers to specify a minimum percentage of clients to have met the condition before continuing. The ModuleServerAPI can force a client condition. See [conditions](./ModuleCondition) for all parameters. | `{ condition1: { condition }, condition2: { condition } }` | | conditions.client | An object with condition IDs as keys and condition data as values. A condition is a way for a cue list to wait till a condition is met. These are client conditions, they can be met via the [ModuleClientAPI](./ModuleClientAPI). Because the ModuleClientAPI runs on the machines of viewers which you can not trust, Getiyo has a system that allows cue list makers to specify a minimum percentage of clients to have met the condition before continuing. The ModuleServerAPI can force a client condition. See [conditions](./ModuleConfigCondition) for all parameters. | `{ condition1: { condition }, condition2: { condition } }` |
| conditions.server | An object with condition IDs as keys and condition data as values. These are server conditions, they can be met via the [ModuleServerAPI](./ModuleServerAPI). The object is the same as `conditions.client`. | `{ condition1: { condition }, condition2: { condition } }` | | conditions.server | An object with condition IDs as keys and condition data as values. These are server conditions, they can be met via the [ModuleServerAPI](./ModuleServerAPI). The object is the same as `conditions.client`. | `{ condition1: { condition }, condition2: { condition } }` |
| defaultsize.width | The default width of the module. | | defaultsize.width | The default width of the module. |
| defaultsize.height | The default height of the module. | | defaultsize.height | The default height of the module. |
| defaultlocation.x | <span style="color:red">**Probably deprecated soon!**</span> Default x coordinate of the module. | | defaultlocation.x | <span style="color:red">**Probably deprecated soon!**</span> Default x coordinate of the module. |
| defaultlocation.y | <span style="color:red">**Probably deprecated soon!**</span> Default y coordinate of the module. | | defaultlocation.y | <span style="color:red">**Probably deprecated soon!**</span> Default y coordinate of the module. |

56
ModuleTS.md Normal file

@@ -0,0 +1,56 @@
# Module.json
The module.json file serves as the central configuration file for each module in Getiyo. It contains essential metadata that informs Getiyo about the module's identity, as well as the module's properties, triggers, and conditions. The [GetiyoModuleTool](./GetiyoModuleTool) can automatically generate this file for you, streamlining the setup process. However, if you want to modify or add properties, triggers, or conditions, you can refer to the documentation provided below. For a full example of a module.json file, see the [complete module.json example](./module.json).
## Structure
```JSON
{
"type": "normal",
"name": "DemoModule",
"author": "Mees van der Wijk",
"category": "Debug",
"description": "A simple demo module!",
"default_reference_properties": {
"propertyId": { property }
},
"default_module_properties": {
"propertyId": { property }
},
"triggers": {
"triggerId": { trigger }
},
"conditions": {
"client": {
"conditionId": { condition }
},
"server": {
"conditionId": { condition }
}
},
"defaultsize": { "width": 400, "height": 400 },
"defaultlocation": { "x": 100, "y": 100 }
}
```
| Property | Description | Example |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| name | The property name, used internally for creating an ID. Changing this will break modules using the old name. |
| author | The module author. |
| category | A fitting category for the module. |
| description | A short module description. |
| default_reference_properties | An object with property IDs as keys and property objects as values. Reference properties are unique for each scene a module is a part of. These are also the properties you edit in the scene editor. See [property](./ModuleConfigProperty) for all parameters. | `{ property1: { property }, property2: { property } }` |
| default_module_properties | An object with property IDs as keys and property objects as values. Module properties are shared for the entire module instance. See [property](./ModuleConfigProperty) for all parameters. | `{ property1: { property }, property2: { property } }` |
| triggers | An object with trigger IDs as keys and trigger data as values. Triggers allow a cue list to call the server-side of a module, controlling module behavior automatically. See [trigger](./ModuleConfigTrigger) for all parameters. | `{ trigger1: { trigger }, trigger1: { trigger } }` |
| conditions.client | An object with condition IDs as keys and condition data as values. A condition is a way for a cue list to wait till a condition is met. These are client conditions, they can be met via the [ModuleClientAPI](./ModuleClientAPI). Because the ModuleClientAPI runs on the machines of viewers which you can not trust, Getiyo has a system that allows cue list makers to specify a minimum percentage of clients to have met the condition before continuing. The ModuleServerAPI can force a client condition. See [conditions](./ModuleConfigCondition) for all parameters. | `{ condition1: { condition }, condition2: { condition } }` |
| conditions.server | An object with condition IDs as keys and condition data as values. These are server conditions, they can be met via the [ModuleServerAPI](./ModuleServerAPI). The object is the same as `conditions.client`. | `{ condition1: { condition }, condition2: { condition } }` |
| defaultsize.width | The default width of the module. |
| defaultsize.height | The default height of the module. |
| defaultlocation.x | <span style="color:red">**Probably deprecated soon!**</span> Default x coordinate of the module. |
| defaultlocation.y | <span style="color:red">**Probably deprecated soon!**</span> Default y coordinate of the module. |

@@ -1,4 +1,4 @@
# Module Structure # V1 Module Structure
Each module in Getiyo comprises four key components: module.json, a server-side script, a user page, and optionally a control/external page. The detailed structure of each component is outlined below. You can automatically set up this file structure by using the [GetiyoModuleTool](./GetiyoModuleTool), as described in the ["Setting up a development environment]"(./ModuleEnvironment) section of the documentation. Each module in Getiyo comprises four key components: module.json, a server-side script, a user page, and optionally a control/external page. The detailed structure of each component is outlined below. You can automatically set up this file structure by using the [GetiyoModuleTool](./GetiyoModuleTool), as described in the ["Setting up a development environment]"(./ModuleEnvironment) section of the documentation.

122
V2ModuleStructure.md Normal file

@@ -0,0 +1,122 @@
# V1 Module Structure
Each module in Getiyo comprises four key components: module.json, a server-side script, a user page, and optionally a control/external page. The detailed structure of each component is outlined below. You can automatically set up this file structure by using the [GetiyoModuleTool](./GetiyoModuleTool), as described in the ["Setting up a development environment]"(./ModuleEnvironment) section of the documentation.
## Module.json
The module.json file serves as the central configuration file for each module in Getiyo. It contains essential metadata that informs Getiyo about the module's identity, as well as the module's properties, triggers, and conditions. The [GetiyoModuleTool](./GetiyoModuleTool) can automatically generate this file for you, streamlining the setup process. However, if you want to modify or add properties, triggers, or conditions, you can refer to the module.json section in the documentation. To learn more about configuring the [module.json](./ModuleJSON) file and its various elements, consult the Module JSON section in the documentation.
## Server-Side
The server-side component of a Getiyo module is comprised of one or more TypeScript or JavaScript files, organized according to the structure outlined below. The server-side code utilizes the [ModuleServerAPI](./ModuleServerAPI), which facilitates communication with the ModuleClientAPI, file management, show control, and more. For a comprehensive overview of the ModuleServerAPI's features and capabilities, visit the [ModuleServerAPI](./ModuleServerAPI) section in the documentation. By familiarizing yourself with the API, you can better leverage its functionality to create powerful and versatile Getiyo modules.
```
Module Root
├── server
│ ├── **/*.ts
│ └── **/*.js
```
_See bottom of the page for a complete directory structure_
## Page
A page of a module consists of an HTML file, TypeScript (or JavaScript), and Sass (or CSS). The user page is **required** because it is shown as the module to a user. The other pages are outside the renderer and not required. The following representation illustrates the typical file structure for a module page:
```
Module Root
├── user
│ ├── ts (Required)
│ │ ├── ModuleClientAPI.d.ts
│ │ └── **/*.ts
│ ├── js (Optional)
│ │ └── **/*.js
│ ├── scss (Optional)
│ │ └── **/*.scss
│ ├── css (Optional)
│ │ └── **/*.css
│ ├── lib (Optional)
│ │ ├── **/*.ts
│ │ ├── **/*.js
│ │ ├── **/*.scss
│ │ └── **/*.css
│ └── index.html
```
_See bottom of the page for a complete directory structure_
The only required directory is ts, as it contains the type definitions for the API in ModuleClientAPI.d.ts. If you prefer using plain JavaScript, create a js folder, but do not remove the ts directory. If you want to include any libraries create a lib folder and add the TypeScript, Javascript, Sass or css files their. They will automatically be included infront of your own script/style. Each page has access to the ModuleClientAPI which will automatically be connected to its server-side ModuleServerAPI. For a comprehensive overview of the ModuleClientAPI's features and capabilities, visit the [ModuleClientAPI](./ModuleClientAPI). section in the documentation.
### Control Page
A control page is a specialized module page accessible only to moderators or admins of a Getiyo channel. This can be used to create a live control panel for your module. It can be opened directly or loaded into the broadcast view—a page where moderators or broadcasters can arrange a controller layout with control pages from different modules. The file structure for a control page is the same as that of a user page.
### External Page
An external page is a unique module page without Getiyo UI elements that can be accessed by anyone with the URL. Unlike user and control pages, external pages are not scaled or queued. The file structure for an external page is the same as that of a user page.
## Static Files
It is possible to add static files to a module build that can be used by the [ModuleServerAPI](./ModuleServerAPI) later. Simple create a `Static` directory in the root of the module environment and place files inside it to add them to the build.
You can include static files in a module build for later use with the [ModuleServerAPI](./ModuleServerAPI). To do so, create a `static` directory at the root of the module environment and place the files inside. This will ensure that they are added to the build. By following this approach, you can easily store and manage static assets, such as images, fonts, or other files, that your module may need for its functionality.
## Example complete file structure
```
Module Root
├── user
│ ├── ts (Required)
│ │ ├── ModuleClientAPI.d.ts
│ │ └── **/*.ts
│ ├── js (Optional)
│ │ └── **/*.js
│ ├── scss (Optional)
│ │ └── **/*.scss
│ ├── css (Optional)
│ │ └── **/*.css
│ ├── lib (Optional)
│ │ ├── **/*.ts
│ │ ├── **/*.js
│ │ ├── **/*.scss
│ │ └── **/*.css
│ └── index.html
├── control
│ ├── ts (Required)
│ │ ├── ModuleClientAPI.d.ts
│ │ └── **/*.ts
│ ├── js (Optional)
│ │ └── **/*.js
│ ├── scss (Optional)
│ │ └── **/*.scss
│ ├── css (Optional)
│ │ └── **/*.css
│ ├── lib (Optional)
│ │ ├── **/*.ts
│ │ ├── **/*.js
│ │ ├── **/*.scss
│ │ └── **/*.css
│ └── index.html
├── external
│ ├── ts (Required)
│ │ ├── ModuleClientAPI.d.ts
│ │ └── **/*.ts
│ ├── js (Optional)
│ │ └── **/*.js
│ ├── scss (Optional)
│ │ └── **/*.scss
│ ├── css (Optional)
│ │ └── **/*.css
│ ├── lib (Optional)
│ │ ├── **/*.ts
│ │ ├── **/*.js
│ │ ├── **/*.scss
│ │ └── **/*.css
│ └── index.html
├── server
│ ├── **/*.ts
│ └── **/*.js
├── static
│ └── **/*.*
├── .dist
└── module.json
```

@@ -5,15 +5,20 @@
- [Setting up server](./ServerSetup) - [Setting up server](./ServerSetup)
- [Config](./Config) - [Config](./Config)
### [Module Development](./ModuleStructure) ### [Module Development](./ModuleDevelopmentIntroduction)
- [Module Structure](./ModuleStructure) - [Introduction](./ModuleDevelopmentIntroduction)
- [Module.json](./ModuleJSON) - V2 Modules
- [Property](./ModuleJSONProperty) - [Module Structure](./V2ModuleStructure)
- [Trigger](./ModuleTrigger) - [Module.json](./ModuleTS)
- [Condition](./ModuleCondition) - V1 Modules
- [Complete Example](./module.json) - [Module Structure](./V1ModuleStructure)
- [Module.json](./ModuleJSON)
- [Development environment/Building](./ModuleEnvironment) - [Development environment/Building](./ModuleEnvironment)
- Module Config
- [Property](./ModuleConfigProperty)
- [Trigger](./ModuleConfigTrigger)
- [Condition](./ModuleConfigCondition)
- [Module Debugging](./ModuleDebugging) - [Module Debugging](./ModuleDebugging)
- [GetiyoModuleTool](./GetiyoModuleTool) - [GetiyoModuleTool](./GetiyoModuleTool)
- [ModuleStore](./ModuleStore) - [ModuleStore](./ModuleStore)