GizmoBot Community Plugins

A collection of community-developed plugins for GizmoBot, designed to extend functionality while maintaining the bot's core architecture.

Available Plugins

Birthday Plugin

Automatically announce member birthdays with customizable messages and scheduling.

• Category: Fun
• Commands: /birthday, /birthday_remove
• Features: Scheduled announcements, age calculation, custom messages

Welcome Back Plugin

Restore previous roles when users rejoin your server after leaving.

• Category: Moderation
• Commands: None (automatic)
• Features: Role persistence, time limits, logging, DM notifications

Auto Roles Plugin

Automatically assign roles to new members when they join.

• Category: Utility
• Commands: /autorole_add, /autorole_remove, /autorole_list, /autorole_test
• Features: Multiple roles, delayed assignment, welcome DMs

Reaction Roles Plugin

Allow users to self-assign roles by reacting to messages.

• Category: Utility
• Commands: /reactrole_add, /reactrole_remove, /reactrole_list
• Features: Custom emojis, multiple messages, automatic sync

Installation

These plugins are designed to work with GizmoBot's Universal Plugin API. They can be:

1. Built-in (default): Included with GizmoBot installation
2. External: Loaded from this separate repository
3. Optional: Can be disabled if not needed

Prerequisites

• GizmoBot v2.0+ with Universal Plugin API
• Python 3.8+
• Discord.py 2.0+
• Appropriate Discord bot permissions for each plugin

Loading Plugins

Method 1: Built-in (Recommended)

These plugins come pre-installed with GizmoBot. Simply enable them in your server settings.

Method 2: External Repository

# Clone the core plugins repository
git clone https://git.puppygirl.io/maddi/gizmobot-plugins.git

# Configure GizmoBot to load external plugins
# In your bot configuration:
EXTERNAL_PLUGINS_REPO=https://git.puppygirl.io/maddi/gizmobot-plugins.git

Method 3: Manual Installation

1. Copy desired plugin folders to your bot/plugins/ directory
2. Restart GizmoBot
3. Enable plugins in server settings

Plugin Architecture

All core plugins follow GizmoBot's standardized architecture:

from bot.plugins.base import BasePlugin

class MyPlugin(BasePlugin):
    @property
    def name(self) -> str:
        return "my_plugin"
    
    # Plugin implementation...

Universal Plugin API Features

• Database Access: Isolated per-guild databases
• Configuration: Type-safe settings with validation
• Event System: Discord and plugin event handling
• Logging: Structured logging with context
• Metrics: Built-in analytics tracking
• Dashboard: Web dashboard integration
• Security: Permission checking and rate limiting

Security & Isolation

• Each plugin runs in isolation with controlled API access
• Database access is scoped per-guild and per-plugin
• Plugins cannot interfere with core bot functionality
• Configuration is validated and type-checked
• All plugin actions are logged and auditable

Contributing

Creating New Plugins

1. Fork this repository
2. Create plugin directory: your-plugin-name/
3. Implement plugin: Follow the BasePlugin pattern
4. Add documentation: Include comprehensive README.md
5. Test thoroughly: Ensure compatibility with GizmoBot API
6. Submit PR: Include description and testing details

NOTE

plugins that require extensive use of back end systems like the database, storage or compute resources will require additional approval

Plugin Structure

your-plugin-name/
├── plugin.py          # Main plugin implementation
├── README.md          # Documentation and usage guide
├── requirements.txt   # Additional dependencies (if needed)
└── tests/            # Unit tests (optional but recommended)

Development Guidelines

• API Compliance: Use only the Universal Plugin API
• Error Handling: Graceful degradation on failures
• Documentation: Clear README with examples
• Permissions: Minimal required Discord permissions
• Performance: Efficient database and API usage
• Testing: Test with multiple guilds and edge cases

Plugin Standards

Required Properties

• name: Unique plugin identifier
• display_name: User-friendly name
• description: Brief functionality description
• icon: Emoji icon for UI
• category: Plugin category

Optional Features

• Slash commands via get_commands()
• Event listeners via event handlers
• Background tasks via get_tasks()
• Configuration schema via settings_schema
• Dashboard integration via dashboard components

Support & Issues

Reporting Issues

1. Check existing issues in this repository
2. Provide details: Plugin name, error messages, steps to reproduce
3. Include context: Discord.py version, Python version, GizmoBot version
4. Test isolation: Verify issue occurs with only the problematic plugin enabled

Getting Help

• Documentation: Check plugin README files
• Discord Server: Join the Puppygirl Labs Discord
• GitHub Discussions: Use for questions and feature requests
• Issues: Use for bug reports only

License

This collection is distributed under the same license as GizmoBot. Individual plugins may have additional licensing terms - check each plugin's directory for details.