Skip to content

Latest commit

 

History

History
210 lines (146 loc) · 5.5 KB

README.md

File metadata and controls

210 lines (146 loc) · 5.5 KB

Server Commands Plugin

Essential server management commands for SocialPie chat servers.

Features

This plugin provides the core commands that every chat server needs:

User Commands

  • /help [command] - Display available commands or help for a specific command
  • /list - Show all currently online users
  • /me <action> - Send an action message (e.g., /me waves → * username waves)
  • /whisper <user> <message> - Send a private message to another user
    • Aliases: /w, /pm

Admin Commands (Require Permissions)

  • /kick <user> [reason] - Kick a user from the server
    • Requires permission: users.kick
  • /mute <user> <seconds> - Temporarily mute a user
    • Requires permission: users.mute
  • /broadcast <message> - Send a server-wide announcement
    • Alias: /announce
    • Requires permission: server.broadcast

Installation

This plugin is included in the official SocialPie plugins directory and will be auto-discovered if you have the official plugins path configured.

Manual Installation

  1. Copy the server_commands directory to your plugins folder
  2. Restart your SocialPie server or reload plugins
  3. The plugin will auto-enable on startup

Configuration

Edit plugin.yaml to customize behavior:

config:
  # Whisper settings
  whisper:
    show_sender: true      # Show sender's name in whispers
    max_length: 500        # Max whisper length (characters)
  
  # Kick settings
  kick:
    require_reason: true   # Require reason when kicking
    broadcast_kick: true   # Announce kicks to all users

Usage Examples

Basic User Commands

# Get help
/help

# Get help for specific command
/help whisper

# List online users
/list

# Send action message
/me is excited about SocialPie!
# Output: * alice is excited about SocialPie!

# Private message
/whisper bob Hey, how are you?
/w bob This is a whisper!
/pm bob Private message here

Admin Commands

# Kick a user
/kick alice Spamming messages
/kick bob  # Error: reason required (if require_reason: true)

# Mute a user for 60 seconds
/mute alice 60

# Server announcement
/broadcast Server will restart in 5 minutes
/announce Maintenance scheduled for tonight

Permissions

To use admin commands, users must have the appropriate permissions. Configure permissions in your server's user management system.

Required Permissions

  • users.whisper - Send private messages
  • users.kick - Kick users from server
  • users.mute - Temporarily mute users
  • server.broadcast - Send server-wide announcements

Features in Detail

Help System

The /help command dynamically shows available commands based on the user's permissions. Users without admin permissions will not see admin-only commands in the help output.

Private Messaging (/whisper)

  • Whispers are only visible to the sender and recipient
  • Sender's name is included by default (configurable)
  • Message length is limited to prevent abuse
  • Failed whispers (user not found) notify the sender privately

Action Messages (/me)

  • Creates narrative-style messages
  • Broadcast to all users
  • Commonly used for roleplay or expressing emotions
  • Example: /me laughs → * alice laughs

Kick Command

  • Immediately disconnects the user
  • Optionally requires a reason (recommended)
  • Can announce kicks to all users
  • Kicked user receives the disconnect reason

Mute Command

  • Prevents a user from sending messages
  • Duration specified in seconds
  • Note: Current implementation is basic; mutes persist until server restart

Broadcast Command

  • Sends highlighted server announcement
  • Includes admin's username
  • Useful for maintenance notifications, events, etc.

Development Notes

Future Improvements

  1. Timed Unmute: Implement automatic unmute after duration expires
  2. Mute Persistence: Store muted users in database
  3. Ban Command: Permanent removal with IP blocking
  4. Enhanced Help: Pull command info from plugin manager
  5. User Blocking: Allow users to block other users
  6. Command Aliases: More customizable command aliases

Architecture

This plugin demonstrates:

  • ✅ Command decorators (@command)
  • ✅ Permission decorators (@require_permission)
  • ✅ Server integration (broadcasts, user management)
  • ✅ Configuration-driven behavior
  • ✅ Error handling and user feedback

Troubleshooting

Command not working

Issue: /help or other commands don't respond

Solutions:

  • Ensure the plugin is enabled: check server logs for "server_commands_enabled"
  • Verify plugin loaded correctly: check for errors in startup logs
  • Check permissions: admin commands require specific permissions

Whisper not delivered

Issue: /whisper command says "sent" but user doesn't receive it

Solutions:

  • Verify target username spelling (case-sensitive)
  • Ensure target user is currently connected (/list to check)
  • Check server logs for delivery errors

Kick broadcasts to all users

Issue: Want to kick silently without announcement

Solution: Edit plugin.yaml and set broadcast_kick: false

License

MIT License - See main SocialPie LICENSE file

Support

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new features
  4. Submit a pull request

Version: 1.0.0
Author: SocialPie Team
Last Updated: 2026-01-25