Updated Scripting (markdown)

2026-04-26 00:01:13 -05:00 · 2024-08-17 20:16:32 +02:00 · 2024-08-17 20:16:32 +02:00 · 13c37a5175
commit 13c37a5175
parent ee971f57bd
1 changed files with 183 additions and 11 deletions
--- a/Scripting.md
+++ b/Scripting.md
@ -5,7 +5,17 @@ The API is not limited to scripts or Python, but the examples showcased here wil

 ## Custom macro condition

-This examples shows how to register a new condition type which will randomly evaluate to `true` based on provided user input percentage in the range from 0 to 100:  
+This examples shows how to register a new condition type which will randomly evaluate to `true` based on provided user input percentage in the range from 0 to 100.  
+
+### What it looks like
+
+This is the custom condition type we will define with this script in action:  
+
+![RandomCondition](https://github.com/user-attachments/assets/8d0d9d02-2bd4-4b71-89e4-162a050f9adc)
+
+As you can see the frequency at which this condition returns true depends on the provided input value, just as we expect it to.  
+
+### The code

 ```
 import obspython as obs
@ -70,21 +80,183 @@ def script_unload():


 ###############################################################################
-########################### boilerplate code below ############################
-###############################################################################
+
+# Advanced Scene Switcher helper functions below:
+# Omitted on this wiki page for brevity!
 ```

-This is the custom condition type we defined with this script in action:  

-![RandomCondition](https://github.com/user-attachments/assets/8d0d9d02-2bd4-4b71-89e4-162a050f9adc)
-
-As you can see the frequency at which this condition returns true depends on the provided input value, just as we expect it to.  
-
-Registering an action would be identical to the example above, but instead of passing a function which returns a boolean value to `advss_register_condition`, you would pass a function performing your desired actions to `advss_register_action`.  
-
-The boilerplate code mentioned above can be found here for [Python](https://github.com/WarmUpTill/SceneSwitcher/blob/master/scripting/examples.py#L115-L305) and [Lua](https://github.com/WarmUpTill/SceneSwitcher/blob/master/scripting/examples.lua#L111-L283).  
+The `Advanced Scene Switcher helper functions` boilerplate code mentioned above can be found here for [Python](https://github.com/WarmUpTill/SceneSwitcher/blob/master/scripting/examples.py#L115-L305) and [Lua](https://github.com/WarmUpTill/SceneSwitcher/blob/master/scripting/examples.lua#L111-L283).  
 Usually you can just copy it directly into your script without any modifications.

+## Discord chat bot action
+
+The following example will add an action which will allow you to send discord message to specified channels.  
+As the process is very similar to the example above the descriptions will be a bit more limited in detail.  
+
+### What it looks like
+
+The bot credentials can be configured in the scripts menu:  
+![](https://github.com/user-attachments/assets/34bf56ed-37d6-49b7-b867-23d7115902eb)
+
+The action itself will allow you to configure the message to send and the channel to send it to.  
+
+![](https://github.com/user-attachments/assets/011944a3-de02-48f6-9af8-b2ef487e5e02)
+
+### The code
+
+```
+import obspython as obs
+import threading  # Required by advss helpers
+
+import discord
+from discord.ext import commands
+import asyncio
+
+action_name = "Discord action"
+token = None
+loop = None
+bot = None
+bot_thread = None
+
+
+###############################################################################
+# Discord functions
+###############################################################################
+
+
+def create_bot():
+    global bot
+    intents = discord.Intents.default()
+    bot = commands.Bot(command_prefix="!", intents=intents)
+
+    @bot.event
+    async def on_ready():
+        obs.script_log(obs.LOG_WARNING, f"Logged in as {bot.user.name}!")
+
+    return bot
+
+
+async def send_message(channel_id, content):
+    channel = bot.get_channel(channel_id)
+    if channel:
+        await channel.send(content)
+
+
+def start_bot():
+    global loop, bot
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    bot = create_bot()
+    loop.create_task(bot.start(token))
+    loop.run_forever()
+
+
+async def stop_bot():
+    await bot.close()
+
+
+def restart_bot():
+    global token, bot_thread
+
+    if loop and bot.is_closed() == False:
+        asyncio.run_coroutine_threadsafe(stop_bot(), loop).result()
+
+    bot_thread = threading.Thread(target=start_bot)
+    bot_thread.start()
+
+
+###############################################################################
+# Macro action functions
+###############################################################################
+
+
+def run_action(data):
+    message = obs.obs_data_get_string(data, "message")
+    channel_id_string = obs.obs_data_get_string(data, "channel_id")
+    try:
+        channel_id = int(channel_id_string)
+    except ValueError:
+        obs.script_log(
+            obs.LOG_WARNING, f"Invalid channel ID string {channel_id_string}!"
+        )
+        return
+    asyncio.run_coroutine_threadsafe(send_message(channel_id, message), loop)
+
+
+def get_action_properties():
+    props = obs.obs_properties_create()
+    obs.obs_properties_add_text(props, "message", "Message", obs.OBS_TEXT_DEFAULT)
+    obs.obs_properties_add_text(props, "channel_id", "Channel ID", obs.OBS_TEXT_DEFAULT)
+    return props
+
+
+def get_action_defaults():
+    default_settings = obs.obs_data_create()
+    obs.obs_data_set_default_string(default_settings, "message", "Your message here!")
+    obs.obs_data_set_default_string(default_settings, "channel_id", "0")
+    return default_settings
+
+
+###############################################################################
+# Script settings and description
+###############################################################################
+
+
+def script_description():
+    return f'Adds the macro action "{action_name}" for the advanced scene switcher'
+
+
+def script_update(settings):
+    global token
+    token = obs.obs_data_get_string(settings, "token")
+
+
+def script_defaults(settings):
+    obs.obs_data_set_default_string(settings, "token", "enter your bot token here")
+
+
+def restart_pressed(props, prop):
+    restart_bot()
+
+
+def script_properties():
+    props = obs.obs_properties_create()
+    obs.obs_properties_add_text(props, "token", "Bot Token", obs.OBS_TEXT_DEFAULT)
+    obs.obs_properties_add_button(props, "button", "Restart bot", restart_pressed)
+    return props
+
+
+###############################################################################
+# Main script entry point
+###############################################################################
+
+
+def script_load(settings):
+    global action_name
+    advss_register_action(
+        action_name,
+        run_action,
+        get_action_properties,
+        get_action_defaults(),
+    )
+    bot_thread = threading.Thread(target=start_bot)
+    bot_thread.start()
+
+
+def script_unload():
+    global action_name
+    advss_deregister_action(action_name)
+
+
+###############################################################################
+
+# Advanced Scene Switcher helper functions below:
+# Omitted on this wiki page for brevity!
+```
+
+# General remarks
+
 Note that if you should choose to unload the scripts, which define custom macro segments, while custom macro segments are still in use, the plugin will no longer be able to query settings of those custom macro segments.  
 If such a state should be saved (e.g. because OBS was closed with the script no longer being loaded) the plugin will instead replace the custom macro segments with macro segments of type `Unknown`.  
 Even if you should choose to reload the script at a later point in time the settings for those `Unknown` macro segments will be lost and you will have to reconfigure them.