Plugin System¶

Welcome to the Shiina-Web Plugin System documentation! Extend your server's functionality with custom plugins, routes, scheduled tasks, and more.

What Are Plugins?¶

Plugins allow you to extend Shiina-Web without modifying the core codebase. Add new features, create custom routes, integrate third-party services, and automate tasks — all through a clean, maintainable plugin architecture.

Plugin Development Guide¶

Creating Plugins

Learn the basics of plugin development, project structure, and building your first plugin
Working with Routes

Create custom web routes and API endpoints within your plugins
Scheduled Tasks

Implement automated tasks using the built-in cron system
Advanced Topics

Database access, authentication, frontend integration, and more

Quick Start¶

Ready to create your first plugin? Here's what you need to know:

Development Prerequisites

Java Development Kit — JDK 11 or higher
Apache Maven — For building plugins
IDE — IntelliJ IDEA, Eclipse, or VS Code recommended

Getting Started¶

Clone the plugin starter template

git clone https://github.com/osu-NoLimits/shiina-plugin/ myplugin/
cd myplugin/

Configure your plugin by editing plugin.yml
Build your plugin with Maven
```
mvn package
```
Deploy the generated JAR file to your Shiina-Web plugins directory

Full tutorial →

Plugin Capabilities¶

What You Can Build

Custom Web Pages — Add new routes and frontend pages
REST APIs — Create API endpoints for integrations
Database Access — Query and modify data safely
Scheduled Tasks — Automate recurring operations
Webhooks — Integrate with external services
Authentication — Access user sessions and permissions
Frontend Extensions — Add custom UI components

Plugin Lifecycle¶

Understanding the plugin lifecycle helps you write better plugins:

graph LR
    A[Plugin Loaded] --> B[onEnable Called]
    B --> C[Routes Registered]
    C --> D[Tasks Scheduled]
    D --> E[Plugin Active]
    E --> F[Server Shutdown]
    F --> G[onDisable Called]
    G --> H[Plugin Unloaded]

Lifecycle Methods

onEnable() — Called when your plugin starts (register routes, initialize resources)
onDisable() — Called when your plugin stops (cleanup, save data)

Best Practices¶

Plugin Development Tips

✅ Use meaningful names for plugins, routes, and tasks
✅ Handle errors gracefully with try-catch blocks
✅ Log important events for debugging and monitoring
✅ Clean up resources in the onDisable() method
✅ Test thoroughly before deploying to production
✅ Document your plugin with clear README files

Common Pitfalls

❌ Don't modify core Shiina-Web files
❌ Avoid blocking operations in request handlers
❌ Don't store sensitive data in plain text
❌ Never skip error handling
❌ Don't forget to update plugin.yml when renaming

Start building amazing plugins for your osu! server today!