Plugins

Shiina Plugin Development Guide

Table of Contents

• Introduction
• Getting Started
• Project Structure
• Creating Your First Plugin
  • Plugin Manifest
  • Main Plugin Class
• Features
  • Event System
  • Configuration System
  • Navbar Integration
  • Template System
• Examples

Introduction

Shiina's plugin system allows developers to extend the functionality of the server through a robust API. This guide will walk you through creating plugins for Shiina.

Getting Started

Prerequisites

• Java Development Kit (JDK) 21 or higher
• Maven or Gradle
• Basic understanding of Java

Dependencies

Add these dependencies to your build system:

<!-- Maven -->
<repositories>
	<repository>
		<id>jitpack.io</id>
		<url>https://jitpack.io</url>
	</repository>
</repositories>
<dependencies>
	<dependency>
		<groupId>com.github.osu-NoLimits</groupId>
		<artifactId>Shiina-Web</artifactId>
		<version>1906ecee69</version>
	</dependency>
</dependencies>
<build>
	<plugins>
		<!-- Maven Jar Plugin -->
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-jar-plugin</artifactId>
			<version>3.3.0</version>
			<configuration>
				<!-- Exclude dependencies -->
				<includeDependencies>false</includeDependencies>
				<!-- Output directory -->
				<outputDirectory>${project.basedir}/../builds</outputDirectory>
			</configuration>
		</plugin>
	</plugins>
</build>

Project Structure

A typical plugin project structure:

my-plugin/
├── src/
│   └── main/
│       ├── java/
│       │   └── com/example/plugin/
│       │       └── MyPlugin.java
│       └── resources/
│           ├── plugin.yml
│           └── modules/
│               └── myplugin/
│                   └── template.html
├── pom.xml
└── README.md

Creating Your First Plugin

Plugin Manifest

Create plugin.yml in your resources directory:

name: MyPlugin
main: com.example.plugin.MyPlugin

Main Plugin Class

Create your main plugin class:

package com.example.plugin;

import dev.osunolimits.plugins.ShiinaPlugin;
import dev.osunolimits.plugins.ShiinaEventListener;

public class MyPlugin extends ShiinaPlugin {
    @Override
    protected void onEnable(String pluginName) {
        // Plugin startup logic
    }

    @Override
    protected void onDisable(String pluginName) {
        // Plugin shutdown logic
    }
}

Features

Event System

Listen to server events by extending ShiinaEventListener:

public class MyEventListener extends ShiinaEventListener {
    @Override
    public void onRegisterEvent(OnRegisterEvent event) {
        // Handle user registration
    }

    @Override
    public void onUserJoinClanEvent(OnUserJoinClanEvent event) {
        // Handle clan join
    }
}

Register your listener in your plugin:

ShiinaRegistry.registerListener(new MyEventListener());

Configuration System

Create a configuration class:

public class MyConfig {
    private String setting1 = "default";
    private int setting2 = 42;
    
    // Getters and setters
}

Load configuration in your plugin:

public class MyPlugin extends ShiinaPlugin {
    private PluginConfig config;

    @Override
    protected void onEnable(String pluginName) {
        config = new PluginConfig(pluginName, MyConfig.class);
        config.loadConfig();
        
        MyConfig myConfig = (MyConfig) config.getConfig();
    }
}

Navbar Integration

Add custom navigation items:

NavbarRegister.register(new NavbarItem(
    "My Page",           // Name
    "custom-page"        // URL
));

Template System

Create FreeMarker templates in resources/modules/yourplugin/:

<!-- template.ftl -->
<div class="custom-content">
    <h1>${title}</h1>
    <p>${content}</p>
</div>

Examples

Complete Plugin Example

public class ExamplePlugin extends ShiinaPlugin {
    private PluginConfig config;

    @Override
    protected void onEnable(String pluginName) {
        // Load configuration
        config = new PluginConfig(pluginName, MyConfig.class);
        config.loadConfig();

        // Register event listener
        ShiinaRegistry.registerListener(new MyEventListener());

        // Add navbar item
        NavbarRegister.register(new NavbarItem(
            "Example",
            "example",
            NavbarRegister.getActNav()
        ));

        log.info("[" + pluginName + "] Plugin enabled successfully!");
    }

    @Override
    protected void onDisable(String pluginName) {
        log.info("[" + pluginName + "] Plugin disabled!");
    }
}

Event Listener Example

public class MyEventListener extends ShiinaEventListener {
    @Override
    public void onRegisterEvent(OnRegisterEvent event) {
        // Custom registration logic
        System.out.println("New user registered: " + event.getUsername());
    }

    @Override
    public void onUserJoinClanEvent(OnUserJoinClanEvent event) {
        // Custom clan join logic
        System.out.println("User joined clan: " + event.getClanName());
    }
}