Plugins

Plugins are the core component of Starlight, this page will show you how to create your first plugin!

All plugins must be placed in the plugins folder

It is recommended that you take a look at the code for the included plugins! This can help significantly with creating your own custom plugins.

Basic Plugin

Make sure to double check if functions are sync or async!

plugins/myplugin.py

import asyncio

from fastapi import Request
from utils.plugin import OSCPlugin

class MyPlugin(OSCPlugin):
    def __init__(self, app):
        self.app = app
        self.osc_listen = {"/avatar/parameters/...": self.osc_event}  # OSC Event Listeners
        self.background_tasks = {"task_name": self.bg_task}  # Background tasks
        self.routes = {"/mypage": (self.route, ["GET", "POST"])}  # Web Pages

        self.counter = 0

    def osc_event(self, address, *args):
        self.app.logger.info(f"OSC Event at {address}!")

    async def bg_task(self):
        while True:
            self.counter += 1
            await asyncio.sleep(1)

    async def route(self, request: Request):  # Can be either sync/async
        return "Hello, World!"

    def render(self, *args, **kwargs):
        return f"Count: {self.counter}"

def setup(app):
    """
    This function should always return the plugin class
    """
    return MyPlugin(app)

Plugin Configs

Config files are automatically generated when a plugin first runs. These config files are editable by users and values will be loaded upon plugin initialization.

plugins/myplugin.py

import asyncio

from fastapi import Request

from utils import PluginConfig
from utils.plugin import OSCPlugin

class Config(PluginConfig):
    MAX_COUNT: int = 10  # Maximum count for the counter variable

class MyPlugin(OSCPlugin):
    def __init__(self, app):
        self.app = app
        self.background_tasks = {"counter_task": self.bg_task}  # Background tasks

        self.counter = 0
        self.config = Config  # Plugin config

    async def bg_task(self):
        while True:
            self.counter += 1
            if self.counter > self.config.MAX_COUNT:  # Reset counter
                self.counter = 0
            await asyncio.sleep(1)

    def render(self, *args, **kwargs):
        return f"Count: {self.counter}"

def setup(app):
    """
    This function should always return the plugin class
    """
    return MyPlugin(app)

Referencing Starlight variables

Using plugins you can call from the main Starlight application. This is a small list of different variables and functions:

To access Starlight variables or functions, use self.app.xxx (replacing xxx with the variable or function name)

Make sure that the self.app variable is set in your plugin's __init__ function!

Variables

msg: str  # The current chatbox message
config: Config # config.json
cpu_info: dict # CPU info (https://github.com/workhorsy/py-cpuinfo#fields)
plugins: dict # Dict of loaded plugins
plugin_tasks: dict # Dict of running plugin background tasks
loop: asyncio.ProactorEventLoop # The current async event loop
logger: logging.Logger # The application logger

Functions

async def get_msg()  # Render current template as string

def queue_osc_message(address: str, value: Any) # Queue OSC message to address (recommended)

def send_osc_message(address: str, value: Any) # Immediately send message to OSC address