Skip to main content
Sakuya AC features a powerful plugin system that allows you to extend server functionality without modifying core code. Plugins can intercept and modify network packets, add custom commands, and implement game mechanics.

​
What Can Plugins Do?

Plugins in Sakuya AC can:
  • Hook into Events: Intercept and modify flight data, chat messages, join/unjoin events, and more
  • Add Commands: Register custom chat commands that players can use
  • Modify Packets: Change, block, or inject network packets between client and server
  • Implement Game Mechanics: Add features like damage systems, radar, chat filtering, and more

​
Plugin Architecture

The plugin system is managed by the PluginManager class located in lib/plugin_manager.py. It automatically discovers and loads plugins from the plugins/ directory.

​
Key Components

The PluginManager scans the plugins/ directory for:
  • Python files (.py) that are not private (__)
  • Subdirectories with __init__.py files
Each plugin file must have:
  • An ENABLED flag set to True
  • A Plugin class with a register() method
Hooks allow plugins to intercept events and data. When triggered:
  • Callbacks receive the data and can inspect/modify it
  • Returning False blocks the original data from being forwarded
  • Returning True allows the data to continue normally
Plugins can register chat commands that players trigger with /commandname:
  • Commands receive the full message, player object, and message queues
  • Can send responses to client or forward modified messages to server
  • Support aliases and help text for automatic /help generation

​
Available Hooks

The following hooks are available in the plugin system:
Hook NameDescriptionUse Case
on_flight_dataTriggered when flight data is received from clientMonitor aircraft state, enforce limits
on_flight_data_serverTriggered when flight data is sent to clientsModify position data, implement radar
on_chatTriggered when chat message is receivedFilter content, log messages
on_join_requestTriggered when player requests to joinValidate joins, setup player data
on_unjoinTriggered when player leavesCleanup player data
on_remove_airplane_serverTriggered when aircraft removal packet sentModify death behavior

​
Plugin Loading Process

# From lib/plugin_manager.py
for plugin in os.listdir(PLUGIN_DIR):
    if plugin.endswith('.py') and not plugin.startswith('__'):
        plugin_module = importlib.import_module(plugin_name)
        if hasattr(plugin_module, 'ENABLED') and plugin_module.ENABLED:
            if hasattr(plugin_module, 'Plugin'):
                plugin_instance = plugin_module.Plugin()
                self.register_plugin(plugin_instance)
Plugins are loaded at server startup. Changes to plugins require a server restart to take effect.

​
Example Use Cases

Over-G Damage

Monitor aircraft G-forces and apply damage when limits are exceeded

Radar System

Hide enemy aircraft positions based on IFF and distance

Chat Filter

Moderate inappropriate language in chat messages

Custom Commands

Add server commands like /refuel, /weather, /teleport

​
Next Steps

Get Started

Create your first plugin in minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us