Clockwork Scheduler for Hytale v1.0

What is Clockwork?
Clockwork is a server-side automation plugin for Hytale that allows administrators to schedule and control automated tasks without writing Java code.

It lets you automate broadcast announcements and server commands using a single tasks.json file, with flexible scheduling, smart execution conditions, and live placeholders.

If you’ve ever needed:

• timed announcements,
• daily or weekly routines,
• events that only run during peak hours,
• or automated command execution,

Clockwork provides a clean, reliable solution designed for production servers.


Why you’ll want it

• One central automation system — replace scattered scripts and plugins.
• Easy to maintain — all tasks are defined in plain JSON files.
• Flexible scheduling — Interval, Daily, and Weekly execution.
• Smart conditions — player count limits, time windows, allowed days, and probability.
• Placeholders — inject live server data into messages and commands.
• Runtime admin controls — manage tasks without restarting the server.
• Safe by design — invalid tasks are skipped with clear logs, others continue running.
• Logging and optional webhooks — dedicated log file and optional Discord/webhook notifications with rate-limit handling.
• Localization — English and French included, easy to customize.

Core concept: Tasks
A Task is defined by:

• A unique Id
• An Enabled flag
• A ScheduleType (INTERVAL / DAILY / WEEKLY)
• Optional Conditions
• One or more Actions (BROADCAST / COMMAND)

All tasks are defined inside tasks.json as a JSON array.


Scheduling (3 types)

• INTERVAL — run every N seconds, minutes, or hours.
• DAILY — run once per day at a specific time.
• WEEKLY — run on selected weekdays at a specific time.

Timezones are supported using standard Java timezone IDs (for example: Europe/Paris, UTC).


Conditions (run only when it makes sense)
Each task may define a Conditions block:

• MinPlayers / MaxPlayers — only run when enough (or not too many) players are online.
• Probability — random chance between 0.0 and 1.0.
• TimeWindow — restrict execution to a time range such as 18:00-23:00.
• AllowedDays — restrict execution to specific weekdays.

All tasks are validated on load. Invalid configurations are reported clearly in logs and skipped safely, without affecting other tasks.


Actions and placeholders
Clockwork supports two action types:

• BROADCAST — send server-wide messages.
• COMMAND — execute server commands.

Available placeholders:

• {online} — online player count
• {player} — list of online player names
• {time} — current time (HH:mm)
• {date} — current date (yyyy-MM-dd)
• {weekday} — current weekday
• {server_name} — server name

Admin commands (in-game control)
Base command: /clockwork (aliases: /cw, /tasks)
Permission is configurable (default: clockwork.admin).

• /clockwork list — list all loaded tasks.
• /clockwork info <taskId> — show detailed task information.
• /clockwork enable <taskId> — enable a task at runtime.
• /clockwork disable <taskId> — disable a task at runtime.
• /clockwork run <taskId> — run a task now (respects schedule and conditions).
• /clockwork force <taskId> — force execution immediately.
• /clockwork reload — reload configuration, tasks, messages, and webhook settings.
• /clockwork status — display scheduler and task status.

Configuration files

• clockwork.json — global settings (tick interval, timezone, language, logs, webhook, permissions).
• tasks.json — scheduled task definitions.
• langs/messages_en.json and langs/messages_fr.json — translations.
• clockwork_state.json — internal execution state (auto-managed).

On first startup, Clockwork creates its default files in:


In-game preview
The screenshots below demonstrate:

• The /clockwork status command in-game
• Task listing and detailed task information
• Automated broadcast messages triggered by Clockwork
• Example task configuration and log output

Documentation included

• English documentation: doc-en.md
• Documentation française: doc-fr.md

Perfect for

• Automated server announcements and tips
• Daily or weekly routines
• Timed events limited to specific days or hours
• Command-based automation without additional scripts
• Servers that require clean configuration, safety, and reliable control

Support and troubleshooting
Clockwork is designed to make issues visible:

• Use /clockwork status to verify scheduler state
• Check the dedicated log file (clockwork.log)
• Review validation errors in tasks.json for incorrect formats