Automations
An automation makes your server do something on its own: restart every night at 03:00, post a kill feed to Discord, pay a wage every Monday, switch a PvP zone on for the weekend and off again afterwards.
Every automation is made of the same three parts:
- When it runs — on something that happens in the game (an event), on a schedule, or only when you start it by hand.
- What it does — exactly one action: one of dzbot's built-in operations, an action from the marketplace, or your own code.
- Its settings — the values that action asks for, plus an optional Discord message after every run.
Automations replace the former Scheduler and Actions pages. Everything you had there was carried over — see Coming from the scheduler.
Navigation path
Server Admin->Automations
The automations page
The page has one list per view:
- Overview — on a wide screen in two columns: on the left By schedule, sorted by the next run, together with the upcoming events that have automations (folded into one line each, opening the event), and below it By hand; on the right On event, grouped by the event that starts them. Paused automations come last in each list.
- By schedule — automations that run at set times.
- On event — automations that react to something in the game.
- By hand — automations that only run when somebody clicks Run now.
- Marketplace — ready-made actions you can install.
Each row shows the automation's label — "Purge start" — with the action it runs underneath. The automations of your events are edited on the event.
Every list has a search field and filters, for example by kind (built-in, marketplace, own code), by event, active or paused, and whether the last run failed.
Creating an automation
+ Automation opens a drawer with three steps.
- What — the built-in operations, grouped by what they touch (server, mods, automations, Discord), a marketplace action, or Own code. Picking a marketplace action folds the list to that action; Choose another opens it again.
- When — what you can choose depends on the action: an action built for certain events starts only on them, and
only an operation that can be undone offers a duration.
- On a schedule — once at a date and time, or recurring: hourly, daily (one or several times a day), weekly (on chosen weekdays, optionally every few weeks), monthly on a day of the month, or monthly on a weekday (for example the first Monday). A recurring schedule can start at a later date. Optionally give it a duration: the automation then runs over a time range and puts back what it changed when the range is over.
- On event — one or more game events, such as a kill, a login or a base part being built. An optional filter narrows it down (only inside certain zones, a distance, a weapon, kill flags, factions, groups or player variables). dzbot checks the filter before the action starts, so events that do not match cost nothing.
- By hand — no trigger; the automation runs only when somebody clicks Run now.
- Settings — the action's settings and an optional label that tells several automations of the same action apart; it is shown instead of the action's name. For a marketplace action, What it may do lists its permissions.
The times are your server's time zone from the settings. If run times look off, check the time zone first.
What an automation can do
Built-in operations
| Operation | What it does | Can run over a time range |
|---|---|---|
| Server restart | Restarts the game server, optionally with countdown messages in the game beforehand. | No |
| Change server settings | Changes the server settings you pick. | Yes |
| Install or uninstall mods | Switches mods on or off. Takes effect with the next restart. A mod that is no longer installed is skipped: the others still run, and the run counts as partly failed. | Yes |
| Change mod configuration | Changes fields of a mod's configuration. Takes effect with the next restart. | Yes |
| Vehicle wipe | Removes vehicles from the server. Also wipe ordered vehicles (off by default) includes the vehicles players bought as a spawn subscription. To wipe once right now, use Wipe vehicles on the Settings page. | No |
| Switch a zone on or off | Activates or deactivates zones. | Yes |
| Send a Discord message | Posts a message to a Discord channel or sends it as a direct message to players, with placeholders. | No |
| Switch an automation on or off | Pauses or resumes other automations — for example a safe-zone autoban during a boxing event. | Yes |
| Change an automation's settings | Changes settings of another automation. | Yes |
Each operation needs the right you would need to do the same thing by hand — see Access rights.
Marketplace actions
Ready-made actions written by dzbot and by creators: kill feeds, rewards, autobans, review automations and more. The Actions reference describes the ready-made ones. Some listen to fixed game events; others run on demand — on a schedule or by hand — and may suggest a schedule, which is filled in when you install them (for example Group Wage, every Monday at 18:00).
A marketplace action that is marked as installable only once can run only once on a server. Others can be installed several times, each with its own settings and label (Zone Kill Autoban · Safezone, Trader).
Installing shows what the action may do — see Permissions.
Actions written by creators can also be browsed without logging in on dzbot.de, see The public marketplace.
Own code
With the right to edit code you can write your own Lua script. Choose its trigger like any other automation: game events, a schedule, or by hand. The script, the Lua functions and the configuration fields are described in the Actions reference.
Time ranges
An automation with a duration runs at its start, and when the duration is over it puts back what was there before — the previous settings, the previous zone state, the previous mods. A value somebody changed in between (an admin, another automation, an event) is left as it is; the automation shows Not restored then.
Only operations that can be undone run over a time range. A restart, a vehicle wipe or a message only run at a point in time. A range that is running cannot be changed or deleted until it is over. If putting back fails, dzbot keeps trying.
For an evening with a start and an end — a purge, a casino night — an event without rounds is often the better fit: its automations hang on the event's start and end, and ending it early puts everything back.
Restarts in the restart plan
The shop's delivery times, the next charge of a spawn subscription and the restart times on the server page come from the server's restart plan: every active automation on a schedule that may restart the server — the Server restart operation, or a marketplace action or own code with the permission Server restart. An action that only restarts under a condition still counts, as a paid restart; whether subscriptions are free is only known for the Server restart operation.
Running, pausing, copying
An automation's page has the tabs Settings (when it runs, the action's settings, the Discord message and what it may do — saved together), Code for own code, and Runs. Its header shows the next and the last run.
- Run now runs the automation once, outside its trigger (right
automations.run). It is not offered for automations over a time range. - Pause stops it until you resume it. A paused recurring automation keeps its schedule and skips its runs.
- Duplicate creates a paused copy with the same settings. A copy of own code gets its own copy of the code. An action that may only be installed once cannot be duplicated.
- Delete removes the automation — own code goes with it.
- A recurring automation moves on to its next time even when a run failed. The error stays on it until a run succeeds. A one-off automation whose run failed or only partly ran stays marked that way.
- When the server's dzbot Pro ends, automations are skipped and resume when Pro is back.
Runs and Discord notifications
The Runs tab lists every run: when, whether it worked, how long it took, what the script printed and which operations it ran. Below it, the automation's recent states (started, restored, skipped …).
Under Notification, pick a Discord channel and write a message dzbot posts after every run — or only after successful runs with Only on success. The Discord bot has to be installed.
Permissions
An action says what it may do beyond reading. dzbot reads these permissions from the action's code:
| Permission | What it allows | Level |
|---|---|---|
| Discord messages | Post in channels and send direct messages | normal |
| Player variables | Store values on players | normal |
| Tickets | Open tickets | normal |
| Balance bookings | Pay out or take money, place or cancel bounties | elevated |
| Discord roles | Give and take Discord roles | elevated |
| Moderation | Ban players, exempt them from zones, close reviews | elevated |
| Zones | Switch zones on or off | elevated |
| Other automations | Pause, resume or change other automations | elevated |
| Server restart | Restart the server | critical |
| Vehicle wipe | Wipe the vehicles | elevated |
| Server settings | Change server settings | critical |
| Mods | Install, uninstall and configure mods | critical |
| External web addresses | Send data to and fetch data from other websites | critical |
- Installing a marketplace action lists its permissions, and you confirm them. An action that is not verified and asks for an elevated or critical permission shows a warning first.
- You can only grant what you could do yourself. Granting Balance bookings needs the right to change player money, Moderation the right to create restrictions, Server restart the right to restart the server, Vehicle wipe the right to wipe vehicles, and so on.
- Updates: when a creator updates an action, your automations run the new version right away — unless it asks for a permission you have not granted. Then they keep running the version you approved, and the automation shows Update needs new permissions until somebody with the right to manage the marketplace approves it.
- Built-in operations and your own code count as granted by saving them.
Until dzbot switches the check on for all servers, a call outside the granted permissions is not refused yet but noted
in the run log as [PERMISSION] would be refused.
Access rights
admin.automations.view— see the automations page.admin.automations.edit— create and change automations, pause and resume them.admin.automations.run— Run now.admin.automations.delete— delete automations.admin.automations.edit_code— write and change own code.admin.automations.manage_marketplace— install marketplace actions and approve their updates.
These rights replace the former scheduler rights (admin.scheduler.*) and action rights (admin.actions.*); every
group kept what it had.
What an automation changes also needs the right to do it by hand: a restart server.restart, a vehicle wipe
server.vehicle_wipe, installing or uninstalling mods the matching mod rights, a mod's configuration
mods.edit_config, a zone zones.edit, a server setting the right for that setting, another automation
automations.edit. Somebody without that right can still pause the automation or change its label.
Coming from the scheduler
Everything was moved over with the same times, labels and Discord notifications:
- Every scheduler task became an automation on a schedule with the matching built-in operation.
- A Custom Action task became own code on the same schedule.
- A Run action task became the schedule of the action it ran. Actions that only ran from the scheduler no longer need the Scheduled trigger.
- Event automations stayed on their event and are edited there.