> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erlc.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Scheduled, Manual, and Broadcast Triggers in Studio
> Use server-active, bot-online, manual, test-run, and broadcast triggers to start your erlc.dev Studio automations at exactly the right moment.
Not every automation needs to wait for a player action or a Discord interaction. Studio provides a set of time-based, lifecycle, and internal triggers that give you precise control over when your logic runs — from polling the server every few seconds while it's live, to initialising state the moment your bot comes online, to sending a test run during development. This page covers each of these trigger types and explains when to use them.
## Trigger Blocks at a Glance
Fires repeatedly while your ERLC server is running. Ideal for polling loops that check server state on a schedule.
Fires once when your Discord bot connects and becomes ready. Use it to run initialisation logic.
Triggered by you from the Studio dashboard. Great for one-off admin tasks that don't need automation.
Triggered by the **Test Run** button in Studio. For development and debugging only.
Fires when an AI model finishes generating its response. Chains cleanly after AI generation blocks.
Listens for a named internal broadcast sent from another automation in your project.
***
## Server-Active Trigger
**`erlc_when_server_active`** fires on a recurring basis for as long as your linked ERLC server reports as active. Think of it as a heartbeat — every time the trigger fires, your automation can check player counts, sync data, post status updates, or perform any repeating task.
Because this trigger fires continuously, you almost always want to pair it with an **`erlc_throttle`** block. Throttling limits how frequently the downstream logic actually executes, preventing your automation from hammering the ERLC API or Discord rate limits.
```json theme={null}
{
"trigger": {
"type": "erlc_when_server_active"
},
"actions": [
{
"type": "erlc_throttle",
"fields": {
"DURATION": 60,
"UNIT": "seconds"
}
},
{
"type": "erlc_set_variable",
"fields": {
"VAR": "player_count"
},
"value": {
"type": "erlc_player_count"
}
},
{
"type": "erlc_bot_send_message",
"fields": {
"CHANNEL_ID": "1234567890",
"MESSAGE": "📡 Server update: {{player_count}} players currently online."
}
}
]
}
```
Do **not** use `erlc_when_server_active` without a throttle block on the critical path. Without it, your automation will execute as fast as Studio can process events and will quickly exhaust both ERLC API and Discord API rate limits.
Set your throttle duration based on how fresh the data needs to be. A player-count display can tolerate a 60-second interval; a PD alert might need 10 seconds. When in doubt, start at 30 seconds and tune from there.
***
## Bot-Online Trigger
**`erlc_when_bot_online`** fires exactly once each time your Discord bot establishes its gateway connection and becomes ready. Use this trigger to perform initialisation steps that should run before any other automation handles an event.
Common uses include:
* Setting the bot's status message or activity
* Posting a "bot is online" notice to a staff channel
* Loading persistent data from a storage block
* Registering slash commands programmatically
This trigger fires again whenever the bot reconnects after a disconnect. Design your initialisation logic to be idempotent — running it twice should not cause duplicate messages or corrupted state.
***
## Manual Trigger
**`erlc_when_manual`** has no automatic conditions. It fires only when you click **Run** next to the automation in the Studio dashboard. This is the right choice for:
* Bulk operations you need to run occasionally (e.g. syncing a roster)
* Maintenance tasks that are too risky to automate fully
* Utilities you want to share with other admin team members who can click Run without editing the automation itself
***
## Test Run Trigger
**`erlc_when_test_run`** fires when you press the **Test Run** button inside the Studio block editor. It is functionally identical to `erlc_when_manual` but is reserved exclusively for development and debugging workflows.
Remove or disable automations using `erlc_when_test_run` before sharing your project with other admins or moving to production. This trigger fires every time anyone presses Test Run, which can produce unintended side effects in a live environment.
Use `erlc_when_test_run` to:
* Verify that your block logic executes without errors
* Inspect variable values using a log or message block
* Test action blocks (Discord messages, ERLC commands) with known inputs before wiring up a real trigger
***
## AI Response Trigger
**`erlc_when_ai_responds`** fires after an AI generation block completes and the model returns its output. Use it to chain post-processing logic onto AI responses — for example, forwarding the generated text to a Discord channel or storing it in a variable.
The **MODEL** dropdown currently supports:
| Model | Description |
| - | - |
| `qwen2.5:1.5b` | Lightweight, fast model suited for short-form responses and classification tasks |
AI generation is asynchronous. The `erlc_when_ai_responds` trigger ensures your downstream actions only run after the model has fully completed its output — you do not need to add delays or polling logic yourself.
***
## Broadcasts
Broadcasts let your automations communicate with each other inside Studio. One automation sends a named broadcast; other automations listening for that broadcast name fire in response. This is the primary mechanism for decoupling complex multi-automation workflows.
### `erlc_when_broadcast`
Set the **MESSAGE** field to the broadcast name you want this automation to listen for. When another automation sends a broadcast with that exact name, this trigger fires.
### Reading Broadcast Payloads
Use the following blocks to access data that was passed along with the broadcast:
| Block | Description |
| - | - |
| `erlc_received_message_name` | Returns the name of the broadcast that fired this trigger |
| `erlc_received_message_value` | Returns the value/payload attached to the broadcast |
```json theme={null}
{
"trigger": {
"type": "erlc_when_broadcast",
"fields": {
"MESSAGE": "player_verified"
}
},
"actions": [
{
"type": "erlc_received_message_value",
"output_variable": "verified_player_name"
},
{
"type": "erlc_bot_send_message",
"fields": {
"CHANNEL_ID": "9876543210",
"MESSAGE": "✅ {{verified_player_name}} has been verified and added to the roster."
}
}
]
}
```
Use broadcasts to split large automations into smaller, focused blocks. For example, one automation handles a slash command and sends a `player_verified` broadcast; a separate automation listens for that broadcast and updates a spreadsheet. This keeps each automation readable and testable independently.
***
## Choosing the Right Trigger
Use **`erlc_when_server_active`** with an **`erlc_throttle`** block. The throttle controls the effective interval without requiring a cron-style scheduler.
Use **`erlc_when_bot_online`**. It fires before any interactions arrive, giving you a clean window to initialise variables, post status messages, or load stored data.
Use **`erlc_when_manual`** for production one-off tasks. Reserve **`erlc_when_test_run`** strictly for development — never leave it active in a production project.
Use **`erlc_when_broadcast`** as the receiving trigger, and send the broadcast from whichever automation produces the relevant event. Read the payload with `erlc_received_message_value`.
Use **`erlc_when_ai_responds`** to chain cleanly onto the output without polling or delays.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.