🔧Streamer Configurable Settings

Intro

When making custom overlays, you as the developer have the ability to define Streamer-Customizable settings, that are able to be changed by the person using the overlay.

These settings will show up on the overlays edit page in the same style that settings show up on the built-in Pixel Chat overlays, and will also be available in the Quick-Edit mode in the scene editor.

These settings are defined in the JSON tab of the editor. Then, when an overlay is loaded, the settings will by automatically injected into the code in all your other files, they will replace any variable in the files with the format {{settingKey}} where settingKey is the key of the setting in your JSON file.

Best practices

There are a few best practices when using these injected variables depending on what file you are working with. Most of these best practices are in place to preserve the syntax highlighting of the editor, and to allow auto-complete to work properly.

JavaScript

When using the variables in your JavaScript file, it's best to wrap the variable in quotes, then convert it to the correct data type at run time. For example if you have a setting that is a type of number you might define it in your JavaScript file like so:

const numberSetting = Number("{{numberSetting}}");

Doing it in this way makes sure the editor doesn't get confused about the {{}} as that is not valid JavaScript syntax. You can do something similar for bool settings:

const boolSetting = "{{boolSetting}}" === "true";

Available settings types

Now you're probably wondering what settings types are able to you, well here is a JSON file containing every available setting!

{
  "text": {
    "type": "text",
    "value": "Some text!",
    "title": "This is a text input",
  },
  "color": {
    "type": "color",
    "value": { "a": 1, "b": 255, "g": 255, "r": 255 },
    "title": "This is a color input",
  },
  "number": {
    "type": "number",
    "value": 7,
    "min": 0,
    "max": 60,
    "title": "This is a number input",
  },
  "slider": {
    "type": "slider",
    "value": 5,
    "min": 0,
    "max": 100,
    "title": "This is a slider"
  },
  "toggle": {
    "type": "bool",
    "value": false,
    "title": "This is a toggle"
  },
  "dropdown": {
    "type": "drop",
    "value": "Item 1",
    "title": "This is a dropdown",
    "listitems": ["Item 1", "Item 2"]
  },
  "file": {
    "title": "A file upload",
    "type": "file",
    "fileType": "audio",
    "value": {
      "name": "Default Audio",
      "key": "customUploads/22f37dfc-c884-465a-996e-bebc023aee78.mp3"
    }
  }
}

Please note that when editing the JSON, if it is malformed Pixel Chat will prevent you from saving your code. This is to make sure there aren't any mistakes in the JSON, as having broken JSON will break not only the overlay you're making, but would also cause the standard overlay settings pages to fail to work properly.

File Upload Settings

File uploads work a bit differently than most of the other settings, they look like this:

"audio": {
    "title": "Audio",
    "type": "file",
    "fileType": "audio",
    "value": {
      "name": "Default Audio",
      "key": "customUploads/22f37dfc-c884-465a-996e-bebc023aee78.mp3"
    }
  }

As you can see, you specify a "fileType" this file type can be one of: audio, image. Based on this type, the user will be able to select a file that they have uploaded to their account or one of the public Pixel Chat files.

When you are setting up this selector, you have 2 options:

1: Include a default file

2: Don't include a default file

If you choose not to include a default file, please format the value like so:

"value": {
    "name": "none",
    "key": "none"
}

However if you want to include defaults, set the name to whatever you like, then drag and drop the file you wish to use as the default directly into the editor, this will upload the file to Pixel Chat, and place the CDN link wherever your cursor is in the editor.

When you first upload this file it will look something like this:

https://cdn.pixelchat.tv/customUploads/fhastagsfh.mp3

Please remove the domain completely so that your key looks like this:

"value": {
    "name": "Default Audio",
    "key": "customUploads/fhastagsfh.mp3"
}

Then if you wish to use this file in your code, you can just use the variable normally {{audio}} the system will automatically replace the variable with the FULL cdn link.

Congrats! You've now made a custom overlay, now it's time to publish it to the Plaza!

▫️pagePublishing Overlays