Vonix Server Utilities — Moderation System

Release Line: 2.0.2 Moderation EngineRace-Safe Persistence

VSU includes a robust, SQLite-backed moderation system featuring automated expiration sweeps, disconnect reason notifications, and race-safe mute hydration.

1. Duration Syntax Reference

Accepted by /tempban, /tempmute, and related duration arguments:

Unit Token	Duration Value	Example
s	Seconds	30s
m	Minutes	15m
h	Hours	2h
d	Days	7d
w	Weeks	2w
mo	Months (30 days)	1mo
y	Years (365 days)	1y
perm / permanent	Indefinite / No expiry	perm

Composition Rules

Concatenate units largest to smallest without whitespace:

• 1d12h — 1 day and 12 hours
• 7d6h30m — 7 days, 6 hours, and 30 minutes
• 2w3d — 2 weeks and 3 days

Tab-completion: In-game tab completion suggests standard intervals: 1h, 6h, 1d, 7d, 30d, perm.

---

2. Moderation Workflows & Commands

2.1 Temporary & Permanent Bans

• /tempban <player> <duration> [reason...] — Bans player for specified duration.
• /ban <player> [reason...] — Issues a permanent ban.
• /unban <player> — Revokes an active ban. (Note: Sets active = 0 in SQLite; historical record is retained for audit).
• /banlist [page] — Lists active bans (10 per page).

In-Flight Disconnect Notice

When an active player is banned, VSU sends a formatted tellraw message detailing the reason and expiration one second before disconnecting. Reconnect attempts are rejected while active = 1 and the current timestamp is less than expires_at.

/tempban Steve 7d griefing player builds near spawn

---

2.2 Temporary & Permanent Mutes

• /tempmute <player> <duration> [reason...] — Mutes player from chat and whispers. Works on offline players.
• /mute <player> [reason...] — Permanently silences player.
• /unmute <player> — Restores chat privileges.
• /mutelist [page] — Lists active mutes.

/tempmute Steve 1h repeated chat spam and caps

---

2.3 Warning Escalation Chain

• /warn <player> <reason...> — Issues an official warning recorded to the database.
• /warnings <player> [page] — Views complete disciplinary warning history.
• /clearwarnings <player> — Resolves active warnings (sets active = 0, preserves audit log).

# Progressive disciplinary example
/warn Steve Please use English in global chat
/warn Steve Second warning — repeated spam
/warnings Steve
/tempmute Steve 30m Third offense following warnings

---

3. TempMute Race Safety & Hydration (v1.7.1 / 2.0.2)

In high-concurrency environments, asynchronous database writes can introduce race conditions. VSU 2.0.2 incorporates the complete v1.7.1 hydration and race-safety architecture:

1. Pre-Persistence Application: Mute state is applied to the active player’s session memory before initiating the asynchronous SQLite write. This guarantees that rapid follow-up chat messages or commands cannot bypass enforcement during the write window.
2. Fail-Closed Hydration: If the server boots and SQLite active-mute hydration cannot be completed due to I/O contention, the moderation gate fails closed to prevent muted players from speaking during degraded states.
3. Pending Write Preservation: Pending database writes are safely flushed during server shutdown sweeps.
4. Reconciliation on Expiry: If a player holds overlapping punishments, the engine reconciles active records before clearing enforcement.

---

4. Background Expiry Sweeper

VSU runs a lightweight background daemon every 60 seconds:

• Scans punishments table for expired tempbans and tempmutes (active = 1 AND expires_at <= NOW()).
• Automatically updates active = 0 without requiring an operator command.
• If a muted player is online when their mute expires, their chat privileges are seamlessly restored with a chat notification.

---

5. Direct Database Audit Queries

All disciplinary actions are stored in config/vonix_server_utilities/data.db:

-- View recent punishments issued by staff
SELECT id, type, target_name, operator_name, reason,
       datetime(created_at/1000, 'unixepoch') AS issued_at,
       active
FROM punishments
ORDER BY created_at DESC
LIMIT 10;