### PySpigot Getting Started

Source: https://pyspigot-docs.magicmq.dev/misc/plannedfeatures

This section guides new users through the initial setup and usage of PySpigot, offering quick start guides for both single-file scripts and project-based development.

```APIDOC
PySpigot Getting Started:

Guides:
  - Quick Start Guide (Single-File Script): Instructions for beginners using single scripts.
  - Quick Start Guide (Project): Guidance for setting up and running PySpigot projects.
```

--------------------------------

### Quick Start Guide (Single-File Script)

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstart

This section guides users through setting up PySpigot for single-file Python scripts. It covers downloading and loading the plugin, creating a script file, writing the script content, and running it on the server.

```python
# Example of a simple PySpigot script

# This script will print a message to the console when loaded.
print("Hello from PySpigot!")

# You can also interact with Spigot events and commands.
# For example, to listen for player join events:
# @event('player_join')
# def on_player_join(player):
#     print(f"Player {player.name} has joined the server.")

# To register a command:
# @command('hello')
# def hello_command(sender, args):
#     sender.send_message("Hello there!")

```

--------------------------------

### PySpigot Project Configuration

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

Details on how to configure PySpigot projects, including enabling or disabling projects via the `project.yml` file.

```apidoc
Project Configuration:
  project.yml:
    enabled: true | false
    # Other project-specific configurations...
```

--------------------------------

### Create a project.yml

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

This section details the creation of the `project.yml` file, which is essential for configuring your PySpigot project. It outlines the necessary fields and their purposes.

```yaml
name: MyProject
version: 1.0.0
main: main.py
listeners:
  - class: MyListener
    event: PlayerJoinEvent
commands:
  - name: mycommand
    description: A sample command
    executor: commands.MyCommandExecutor
```

--------------------------------

### PySpigot Project Structure and Creation

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

This section details how to set up a new PySpigot project, including folder structure, configuration files, and basic script creation for event listeners.

```python
projects/
  your_project_name/
    project.yml
    listeners/
      your_listener.py
    main.py
```

--------------------------------

### PySpigot Managers Overview

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

An overview of the various managers available in PySpigot for handling tasks, configuration, databases, Redis, and inter-plugin messaging.

```apidoc
Managers:
  Task Manager: Handles asynchronous tasks.
  Config Manager: Manages server and plugin configurations.
  Database Manager: Provides access to various database systems.
  Redis Manager: Facilitates interaction with Redis servers.
  Plugin Message Manager: Enables communication between plugins.
```

--------------------------------

### Optional PySpigot Managers

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

Details on optional managers that extend PySpigot's functionality, including ProtocolLib and PlaceholderAPI integration.

```apidoc
Optional Managers:
  ProtocolLib Manager: Integrates with ProtocolLib for advanced packet manipulation.
  Placeholder Manager: Supports PlaceholderAPI for dynamic text replacement.
```

--------------------------------

### Create The Main Module

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

This section covers the creation of the main Python module for your PySpigot project. This file typically contains the entry point for your script and can be used to register listeners, commands, and other functionalities.

```python
from pyspigot.plugin import PySpigotPlugin

class Main(PySpigotPlugin):
    def on_enable(self):
        print("MyProject has been enabled!")
        self.register_listener(MyListener())

    def on_disable(self):
        print("MyProject has been disabled!")
```

--------------------------------

### Project Configuration (`project.yml`)

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

Defines the main module for the PySpigot project. This file is placed in the root directory and specifies which Python file PySpigot should execute when the project is loaded.

```yaml
main: 'main.py'
```

--------------------------------

### Miscellaneous PySpigot Features

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

Information on miscellaneous features such as autocomplete, planned features, licensing, script events, type coercion, and the PySpigot API for Java developers.

```apidoc
Miscellaneous Features:
  Autocomplete/Code Suggestions: Enhances development with IDE support.
  Planned Features: Outlines future development directions.
  Licensing Info: Details the project's licensing.
  Script Events (Java Developers): How Java developers can interact with PySpigot scripts via events.
  Type Coercion (Java Developers): Explains type conversion between Java and Python.
  PySpigot API (Java Developers): Documentation for the Java API to interact with PySpigot.
```

--------------------------------

### Main Module (`main.py`)

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

The entry point for the PySpigot project. It imports the `listener` module and Bukkit. It calls `listener.register_events()` to set up the event handler and then broadcasts a message to all players indicating that the listener has been registered.

```python
import listener
from org.bukkit import Bukkit

listener.register_events()
Bukkit.broadcastMessage('Registered event listener!')
```

--------------------------------

### Command Client Example

Source: https://pyspigot-docs.magicmq.dev/managers/redis

Illustrates how to use the RedisCommandClient to execute specific Redis commands. This example would show sending commands like SET, GET, or HSET to the Redis server.

```python
# This is a placeholder for the actual code example.
# Actual code would involve importing necessary classes and demonstrating command client usage.
# Example:
# from spigot.managers.redis import RedisManager
# redis_manager = RedisManager()
# command_client = redis_manager.get_command_client()
# command_client.set('anotherkey', 'anothervalue')
# value = command_client.get('anotherkey')
# print(f"Value for anotherkey: {value}")

```

--------------------------------

### PySpigot Java Version Requirements

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

Information on the Java Development Kit (JDK) versions required for different PySpigot releases. This is crucial for compatibility and proper functioning.

```java
# Prior to version 0.6.0, Java 12+ is required.
# From version 0.6.0 to version 0.9.0, Java 17+ is required.
# From version 0.9.1 onwards, Java 21+ is required.
```

--------------------------------

### PySpigot Example Scripts Overview

Source: https://pyspigot-docs.magicmq.dev/scripts/examples

This section links to various example scripts demonstrating PySpigot's capabilities. These examples cover different functionalities and are useful for learning how to use PySpigot effectively.

```python
# This page serves as a central hub for PySpigot example scripts.
# Please refer to the links provided in the documentation for specific examples.

# Example categories include:
# - Basic script writing
# - Project structure
# - Manager usage (Script Manager, Listener Manager, Command Manager, etc.)
# - Interacting with server events and commands
# - Using external libraries and custom events
```

--------------------------------

### Config File Example

Source: https://pyspigot-docs.magicmq.dev/managers/configuration

An example of a configuration file with some keys already set.

```yaml
key-1:'Key1isset'
key-2:'Key2isset'
```

--------------------------------

### PySpigot External Resources and Examples

Source: https://pyspigot-docs.magicmq.dev/scripts/writingscripts

This section points to external resources and provides example scripts that demonstrate various PySpigot functionalities.

```APIDOC
External Resources:
  Links to external documentation and resources relevant to PySpigot development.

Example Scripts:
  A collection of sample scripts showcasing different features and use cases of PySpigot.
```

--------------------------------

### General Client Example

Source: https://pyspigot-docs.magicmq.dev/managers/redis

A basic example demonstrating how to use the generic Redis client for general interactions with a Redis server. This might involve setting up a connection and performing simple operations.

```python
# This is a placeholder for the actual code example.
# Actual code would involve importing necessary classes and demonstrating client usage.
# Example:
# from spigot.managers.redis import RedisManager
# redis_manager = RedisManager()
# generic_client = redis_manager.get_generic_client()
# generic_client.set('mykey', 'myvalue')
# value = generic_client.get('mykey')
# print(f"Value for mykey: {value}")

```

--------------------------------

### Pub/Sub Client Example

Source: https://pyspigot-docs.magicmq.dev/managers/redis

Demonstrates the usage of the RedisPubSubClient for publishing messages to channels and subscribing to receive messages. This example would cover setting up listeners and interacting with the Pub/Sub system.

```python
# This is a placeholder for the actual code example.
# Actual code would involve importing necessary classes and demonstrating Pub/Sub client usage.
# Example:
# from spigot.managers.redis import RedisManager
# redis_manager = RedisManager()
# pubsub_client = redis_manager.get_pubsub_client()

# def message_handler(channel, message):
#     print(f"Received message on channel {channel}: {message}")

# pubsub_client.subscribe('mychannel', message_handler)
# pubsub_client.publish('mychannel', 'Hello Redis!')
# # Keep the connection alive to receive messages

```

--------------------------------

### SQL Database Code Example

Source: https://pyspigot-docs.magicmq.dev/managers/databases

Provides a practical code example for connecting to and interacting with SQL databases using PySpigot's database manager.

```python
# Code Example for SQL Databases
# This example demonstrates a typical workflow for interacting with SQL databases.

# Assuming 'db_manager' is an instance of PySpigot's DatabaseManager
# db_manager.connect_sql(
#     driver='mysql',
#     host='localhost',
#     port=3306,
#     database='mydatabase',
#     user='user',
#     password='password'
# )

# # Execute a query
# db_manager.execute_sql("CREATE TABLE IF NOT EXISTS items (id INT PRIMARY KEY, name VARCHAR(255))")

# # Insert data
# db_manager.execute_sql("INSERT INTO items (id, name) VALUES (1, 'example')")

# # Query data
# results = db_manager.query_sql("SELECT * FROM items")
# for row in results:
#     print(row)

# # Close the connection
# db_manager.close_sql()

```

--------------------------------

### Python Config Manager Example

Source: https://pyspigot-docs.magicmq.dev/managers/configuration

Demonstrates basic usage of the PySpigot Config Manager to load and check for configuration files.

```python
from psp import ps

# Check if a config file exists
if ps.config_manager.doesConfigExist('my_config.yml'):
    print("Config file exists.")
else:
    print("Config file does not exist.")

# Load a config file, creating it if it doesn't exist
config = ps.config_manager.loadConfig('my_config.yml')

# Load a config file with default values
defaults = "\nkey1: value1\nkey2: 123\n"
config_with_defaults = ps.config_manager.loadConfig('defaulted_config.yml', defaults)

# Accessing config values (assuming config is a ScriptConfig object)
# config.set('new_key', 'new_value')
# config.save() # Remember to save changes!

# Example using subfolders
subfolder_config = ps.config_manager.loadConfig('settings/app_config.yml')
```

--------------------------------

### PlaceholderAPI Integration

Source: https://pyspigot-docs.magicmq.dev/scripts/examples

A brief script demonstrating how to register a placeholder with PlaceholderAPI. This is useful for dynamic text in-game.

```python
from pyspigot import PySpigot

@PySpigot.placeholder('my_custom_placeholder')
def get_custom_placeholder_value(player):
    return "Some dynamic value"
```

--------------------------------

### Install PySpigot Translated Sources

Source: https://pyspigot-docs.magicmq.dev/misc/autocomplete

Installs the translated source packages for PySpigot based on your server software and Minecraft version. Ensure you install both the server-specific sources and the PySpigot core sources.

```bash
pip install pyspigot-spigot-sources==1.21.4
pip install pyspigot-sources-bukkit==0.9.1
```

--------------------------------

### MongoDB Code Example

Source: https://pyspigot-docs.magicmq.dev/managers/databases

Provides a code example for interacting with MongoDB databases using PySpigot's database manager.

```python
# Code Example for MongoDB
# This example demonstrates how to use the database manager with MongoDB.

# Assuming 'db_manager' is an instance of PySpigot's DatabaseManager
# db_manager.connect_mongo(
#     host='localhost',
#     port=27017,
#     database='my_mongo_db'
# )

# # Insert a document
# db_manager.insert_mongo('users', {'name': 'Alice', 'age': 30})

# # Find documents
# results = db_manager.find_mongo('users', {'age': {'$gt': 25}})
# for doc in results:
#     print(doc)

# # Update a document
# db_manager.update_mongo('users', {'name': 'Alice'}, {'$set': {'age': 31}})

# # Delete a document
# db_manager.delete_mongo('users', {'name': 'Alice'})

# # Close the MongoDB connection
# db_manager.close_mongo()

```

--------------------------------

### Example PySpigot Plugin Configuration

Source: https://pyspigot-docs.magicmq.dev/pyspigot/pluginconfiguration

This snippet shows an example configuration for a PySpigot plugin, including settings for enabling or disabling bStats metrics collection and configuring the script load delay.

```yaml
metrics-enabled:true
# The delay for loading scripts (in ticks) after the server finishes loading.
script-load-delay:20
```

--------------------------------

### Project Configuration Example

Source: https://pyspigot-docs.magicmq.dev/projects/projectoptions

Demonstrates the basic structure and common options for a `project.yml` file. This file allows customization of project behavior, such as the main script, enablement status, and logging.

```yaml
main:'main.py'
enabled:true
file-logging-enabled:true
```

--------------------------------

### Verify Python Installation

Source: https://pyspigot-docs.magicmq.dev/misc/autocomplete

Commands to verify that your Python installation is correctly pointing to the virtual environment.

```bash
where python (Windows)
which python (macOS/Linux)
```

--------------------------------

### Example YAML Configuration File

Source: https://pyspigot-docs.magicmq.dev/pyspigot/pyspigot

Shows a sample YAML configuration file, commonly used for plugin settings or project-specific configurations within PySpigot. This format allows for structured data storage.

```yaml
# test.yml
# Example configuration file

setting1: value1
setting2:
  nested_setting: true

```

--------------------------------

### SQL Database Manager Code Examples

Source: https://pyspigot-docs.magicmq.dev/managers/databases

Provides code examples for interacting with SQL databases using PySpigot's Database Manager. Includes both synchronous and asynchronous approaches for executing queries and fetching data.

```python
# Synchronous Example
from pyspigot.managers.databases import SqlDatabase
from com.zaxxer.hikari import HikariConfig

config = HikariConfig()
config.setJdbcUrl("jdbc:mysql://localhost:3306/mydatabase")
config.setUsername("user")
config.setPassword("password")
config.setMaximumPoolSize(10)

db = SqlDatabase(config)

# Execute a query
db.execute("CREATE TABLE IF NOT EXISTS users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255))")

# Insert data
db.execute("INSERT INTO users (name) VALUES (?)", ["Alice"])

# Fetch data
user = db.fetchOne("SELECT * FROM users WHERE name = ?", ["Alice"])
print(user)

db.close()
```

```python
# Asynchronous Example
from pyspigot.managers.databases import SqlDatabase
from com.zaxxer.hikari import HikariConfig
import asyncio

async def run_db_operations():
    config = HikariConfig()
    config.setJdbcUrl("jdbc:mysql://localhost:3306/mydatabase")
    config.setUsername("user")
    config.setPassword("password")
    config.setMaximumPoolSize(10)

    db = SqlDatabase(config)

    # Execute a query asynchronously
    await db.execute_async("CREATE TABLE IF NOT EXISTS logs (id INT AUTO_INCREMENT PRIMARY KEY, message TEXT)")

    # Insert data asynchronously
    await db.execute_async("INSERT INTO logs (message) VALUES (?)", ["User logged in"])

    # Fetch data asynchronously
    log_entry = await db.fetchOne_async("SELECT * FROM logs ORDER BY id DESC LIMIT 1")
    print(log_entry)

    await db.close_async()

asyncio.run(run_db_operations())
```

--------------------------------

### PySpigot External Resources

Source: https://pyspigot-docs.magicmq.dev/pyspigot/pyspigot

Lists external resources that can be helpful for developing with PySpigot, including examples and documentation.

```text
External Resources:
  Example Scripts: https://pyspigot-docs.magicmq.dev/scripts/examples/
  PySpigot JavaDocs: https://javadocs.magicmq.dev/pyspigot/
```

--------------------------------

### PySpigot Project Start and Stop Functions

Source: https://pyspigot-docs.magicmq.dev/projects/writingprojects

Details the start and stop functions within a PySpigot project. These functions are executed when the project is loaded and unloaded, respectively, allowing for initialization and cleanup tasks.

```python
# Define start and stop functions for your project
def on_start():
    print("Project started!")
    # Initialization code here

def on_stop():
    print("Project stopped!")
    # Cleanup code here

```

--------------------------------

### Autocomplete/Code Suggestions Setup

Source: https://pyspigot-docs.magicmq.dev/misc/autocomplete

Instructions on how to set up and configure PySpigot's autocomplete and code suggestion features for a smoother development experience.

```python
# PySpigot Autocomplete/Code Suggestions Setup:
# Ensure you have the latest version of PySpigot installed.
# Configure your IDE to recognize PySpigot's language server or plugin.
# Refer to your IDE's documentation for specific setup steps.
# Example (conceptual):
# import pyspigot
# pyspigot.enable_autocomplete()
```

--------------------------------

### PySpigot Scripting Resources

Source: https://pyspigot-docs.magicmq.dev/pyspigot/pluginconfiguration

Links to resources for writing scripts in PySpigot, including general information, options, global variables, external libraries, custom events, and examples.

```APIDOC
Writing Scripts:
  General Information:
    description: Provides general guidance on writing scripts for PySpigot.
    link: https://pyspigot-docs.magicmq.dev/scripts/writingscripts/

  Script Options:
    description: Details available options that can be configured for scripts.
    link: https://pyspigot-docs.magicmq.dev/scripts/scriptoptions/

  Global Variables:
    description: Lists and explains the global variables available within scripts.
    link: https://pyspigot-docs.magicmq.dev/scripts/globalvariables/

  External Libraries:
    description: Information on how to use external libraries within PySpigot scripts.
    link: https://pyspigot-docs.magicmq.dev/scripts/externallibraries/

  Custom Events:
    description: How to define and handle custom events in your scripts.
    link: https://pyspigot-docs.magicmq.dev/scripts/customevents/

Helpful Resources:
  Example Scripts:
    description: A collection of example scripts demonstrating various PySpigot features.
    link: https://pyspigot-docs.magicmq.dev/scripts/examples/

  External Resources:
    description: Links to external resources that may be helpful for PySpigot development.
    link: https://pyspigot-docs.magicmq.dev/scripts/externalresources/

Helper Modules:
  PySpigot Helper Module:
    description: Documentation for the PySpigot helper module.
    link: https://pyspigot-docs.magicmq.dev/scripts/helpermodule/

  Function Helper Module:
    description: Documentation for the function helper module.
    link: https://pyspigot-docs.magicmq.dev/scripts/functionmodule/
```

--------------------------------

### Teleport GUI Command

Source: https://pyspigot-docs.magicmq.dev/scripts/examples

Creates a clickable GUI inventory for teleporting to different locations. This script involves GUI creation and teleportation logic, with a companion configuration file.

```python
from pyspigot import PySpigot
from pyspigot.inventory import Inventory, InventorySlot

# GUI creation and teleportation logic would be implemented here.
# Configuration loading from teleport.yml would also be included.
```

--------------------------------

### Function Helper Module Code Example

Source: https://pyspigot-docs.magicmq.dev/scripts/functionmodule

This section provides a Python code example demonstrating the usage of the Function Helper Module in PySpigot. It showcases how to leverage the module's functionalities within a script.

```python
from pyspigot.helper.function import *

# Example usage of functions from the helper module
result = add(5, 3)
print(f"The sum is: {result}")

message = "Hello, PySpigot!"
print(f"Original message: {message}")
reversed_message = reverse_string(message)
print(f"Reversed message: {reversed_message}")
```

--------------------------------

### PySpigot Configuration Loading and Manipulation

Source: https://pyspigot-docs.magicmq.dev/managers/configuration

This example demonstrates loading a configuration file, reading integer and string values, setting a new value, and saving the configuration using PySpigot.

```python
import pyspigot as ps

script_config = ps.config.loadConfig('test.yml')

a_number = script_config.getInt('test-number')
a_string = script_config.getString('test-string')

script_config.set('test-set', 1337)
script_config.save()
```

--------------------------------

### Kick Player Command

Source: https://pyspigot-docs.magicmq.dev/scripts/examples

Registers a simple command to kick a player from the server. This script demonstrates basic command execution and player kicking functionality.

```python
from pyspigot import PySpigot

@PySpigot.command('kick')
def kick_command(sender, target_player):
    if target_player:
        target_player.kick_player("You have been kicked from the server.")
        sender.send_message(f"Kicked {target_player.get_name()}.")
    else:
        sender.send_message("Player not found.")
```

--------------------------------

### Loading and Running a Script Example

Source: https://pyspigot-docs.magicmq.dev/managers/scripts

Demonstrates how to load a script by its name using the script manager. This operation returns a RunResult object.

```python
from pyspigot.script import script

# Load a script named 'my_script'
result = script.loadScript('my_script')

# Check the result of the loading operation
if result.success:
    print(f"Successfully loaded script: {result.name}")
else:
    print(f"Failed to load script: {result.name}. Error: {result.error}")
```

--------------------------------

### Community Chest Command

Source: https://pyspigot-docs.magicmq.dev/scripts/examples

Adds a community chest command that opens a shared inventory for players. This script showcases inventory management and inter-player item sharing.

```python
from pyspigot import PySpigot
from pyspigot.inventory import Inventory

community_chest_inventory = Inventory(rows=6, title='Community Chest')

@PySpigot.command('communitychest')
def community_chest_command(sender):
    sender.open_inventory(community_chest_inventory)
```

--------------------------------

### Create The Listener Module

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

This guide explains how to create a listener module in Python for PySpigot. Listeners are used to react to specific game events, such as player joins or block breaks.

```python
from pyspigot.event import Listener
from pyspigot.event.player import PlayerJoinEvent

class MyListener(Listener):
    def on_player_join(self, event):
        player = event.player
        print(f"Player {player.name} joined the server!")
```

--------------------------------

### Listener Module (`listener.py`)

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstartproject

Sets up an event listener for player chat events. It imports the PySpigot library and Bukkit's `AsyncPlayerChatEvent`. The `chat_event` function prints the message content, and `register_events` registers this function to handle chat events.

```python
import pyspigot as ps
from org.bukkit.event.player import AsyncPlayerChatEvent

def chat_event(event):
    print(event.getMessage())

def register_events():
    ps.listener_manager().registerListener(chat_event, AsyncPlayerChatEvent)
```

--------------------------------

### Verify Installed Packages

Source: https://pyspigot-docs.magicmq.dev/misc/autocomplete

Lists all installed Python packages in the current environment, used to confirm successful installation of PySpigot packages.

```bash
pip freeze
```

--------------------------------

### PySpigot Projects - Project Options

Source: https://pyspigot-docs.magicmq.dev/index

This section details the various options and configurations available when setting up a PySpigot project. These options help in defining project-specific settings and behaviors.

```python
# PySpigot Projects - Project Options
# This section describes configurable options for PySpigot projects.
# Project options can define dependencies, entry points, and more.

# Example of project options (conceptual):
# project_config = {
#     'plugin_name': 'MyAwesomePlugin',
#     'main_script': 'main.py',
#     'version': '1.0.0',
#     'authors': ['DeveloperName']
# }

```

--------------------------------

### Python Learning Resources

Source: https://pyspigot-docs.magicmq.dev/scripts/externalresources

Links to online tutorials and documentation for learning Python, suitable for beginners and those new to the language.

```APIDOC
Python Tutorials:
  learnpython.org: https://www.learnpython.org/
  w3schools.com: https://www.w3schools.com/python/
  Python Wiki (BeginnersGuide): https://wiki.python.org/moin/BeginnersGuide/Programmers
```

--------------------------------

### PySpigot Project Lifecycle and Management

Source: https://pyspigot-docs.magicmq.dev/projects/writingprojects

This section outlines the core concepts and functions related to managing PySpigot projects, including their basic information, options, permissions, loading, unloading, and the execution of start and stop functions. It's crucial for understanding how PySpigot handles project execution and lifecycle.

```APIDOC
Project Information:
  - Basic Project Information: Covers fundamental details required for any PySpigot project.
  - Project Options: Configuration settings that define project behavior.
  - Project Permissions: Specifies the access rights and capabilities of a project.

Project Lifecycle:
  - Project Loading: The process of making a project available for execution.
  - Project Unloading: The process of removing a project from active execution.
    - Unloading A Project from Within Itself: Specifics on how a project can initiate its own unloading.
  - Start and Stop Functions: Entry points for project initialization and cleanup.

Helper Modules & Globals:
  - The pyspigot.py Helper Module: Provides utility functions for script development.
  - Global Variables: Access to globally available variables within the PySpigot environment.

Error Handling & Logging:
  - Project Errors and Exceptions: Strategies for managing and handling errors within projects.
  - Project Logging: Mechanisms for recording events and debugging information.

Character Encoding:
  - Non-ASCII Characters in Project Files: Guidelines for using non-ASCII characters in project files.
```

--------------------------------

### PySpigot Scripting: Start and Stop Functions

Source: https://pyspigot-docs.magicmq.dev/scripts/writingscripts

Defines the standard functions `onEnable` and `onDisable` that PySpigot scripts can implement to execute code when the script starts or stops.

```python
def onEnable():
    # Code to run when the script is enabled
    print("Script enabled!")

def onDisable():
    # Code to run when the script is disabled
    print("Script disabled!")

```

--------------------------------

### File Logging Enabled Script Option Example

Source: https://pyspigot-docs.magicmq.dev/scripts/scriptoptions

Provides an example of setting 'file-logging-enabled' for a Python script. When true, script errors and log messages are written to a dedicated file.

```yaml
test.py:
  file-logging-enabled:true
```

--------------------------------

### PySpigot Project Configuration (`project.yml`)

Source: https://pyspigot-docs.magicmq.dev/projects/writingprojects

Details the `project.yml` file used to configure PySpigot projects. It specifies options like the main module, enablement, load priority, and logging. The `main` option determines the entry point module.

```yaml
main: main.py
# Other project options can be configured here.
```

--------------------------------

### PySpigot Console Commands for Project Management

Source: https://pyspigot-docs.magicmq.dev/projects/writingprojects

Provides examples of PySpigot console commands for managing projects. These commands allow for manual loading, unloading, and reloading of projects directly from the server console.

```bash
/pyspigot load <projectname>
```

```bash
/pyspigot unload <projectname>
```

```bash
/pyspigot reload <projectname>
```

```bash
/pyspigot reload
```

--------------------------------

### PySpigot Project Development

Source: https://pyspigot-docs.magicmq.dev/pyspigot/pluginconfiguration

Guidance on writing projects with PySpigot, covering general information, project options, and related resources.

```APIDOC
Writing Projects:
  General Information:
    description: General information about developing projects using PySpigot.
    link: https://pyspigot-docs.magicmq.dev/projects/writingprojects/

  Project Options:
    description: Details the configuration options available for PySpigot projects.
    link: https://pyspigot-docs.magicmq.dev/projects/projectoptions/

Helpful Resources:
  Example Scripts:
    description: Access example scripts relevant to project development.
    link: https://pyspigot-docs.magicmq.dev/scripts/examples/

  External Resources:
    description: Links to external resources beneficial for project development.
    link: https://pyspigot-docs.magicmq.dev/scripts/externalresources/

Helper Modules:
  PySpigot Helper Module:
    description: Documentation for the PySpigot helper module used in projects.
    link: https://pyspigot-docs.magicmq.dev/scripts/helpermodule/

  Function Helper Module:
    description: Documentation for the function helper module.
    link: https://pyspigot-docs.magicmq.dev/scripts/functionmodule/
```

--------------------------------

### Full Example: Create and Call Custom Event

Source: https://pyspigot-docs.magicmq.dev/scripts/customevents

A complete example combining the creation of a custom event with a dictionary payload and its subsequent invocation via the Bukkit server's plugin manager.

```python
fromdev.magicmq.pyspigot.event.customimport CustomEvent
fromorg.bukkitimport Bukkit

dictionary = {'test': '1', 'test2': '2'}

event = CustomEvent('script1_event', dictionary)

Bukkit.getServer().getPluginManager().callEvent(event)
```

--------------------------------

### Python ScriptConfig Usage Example

Source: https://pyspigot-docs.magicmq.dev/managers/configuration

Illustrates how to use the ScriptConfig object to modify and save configuration settings.

```python
from psp import ps

# Assume 'config' is a ScriptConfig object obtained from loadConfig
config = ps.config_manager.loadConfig('my_settings.yml')

# Set a value
config.set('database.host', 'localhost')
config.set('database.port', 5432)

# Set a value only if it doesn't exist
was_set = config.setIfNotExists('logging.level', 'INFO')
if was_set:
    print("Logging level set to INFO.")

# Reload the configuration if external changes were made
# config.reload()

# Save the changes to the file
config.save()

# Get the path of the config file
config_path = config.getConfigPath()
print(f"Config saved to: {config_path}")
```

--------------------------------

### PySpigot Project Writing

Source: https://pyspigot-docs.magicmq.dev/scripts/externalresources

Guidance on creating and managing PySpigot projects, covering general information and project-specific options.

```APIDOC
Project Writing:
  General Information: Overview of PySpigot project structure and development.
  Project Options: Configuration settings for PySpigot projects.
```

--------------------------------

### Unloading a Script Example

Source: https://pyspigot-docs.magicmq.dev/managers/scripts

Shows how to unload a script by its name. The function returns a boolean indicating success or failure.

```python
from pyspigot.script import script

# Unload a script named 'my_script'
success = script.unloadScript('my_script')

if success:
    print("Script unloaded successfully.")
else:
    print("Failed to unload script.")
```

--------------------------------

### SQL Database Code Example (Asynchronous)

Source: https://pyspigot-docs.magicmq.dev/managers/databases

Illustrates how to use the PySpigot database manager for asynchronous operations with SQL databases.

```python
# Code Example for SQL Databases, Asynchronous
# This example shows how to perform asynchronous database operations.

# Assuming 'db_manager' is an instance of PySpigot's DatabaseManager
# async def run_async_queries():
#     await db_manager.connect_sql_async(
#         driver='postgresql',
#         host='localhost',
#         port=5432,
#         database='mydb',
#         user='admin',
#         password='securepassword'
#     )

#     # Execute an asynchronous query
#     await db_manager.execute_sql_async("CREATE TABLE IF NOT EXISTS logs (message TEXT)")

#     # Insert data asynchronously
#     await db_manager.execute_sql_async("INSERT INTO logs (message) VALUES ('async log entry')")

#     # Query data asynchronously
#     results = await db_manager.query_sql_async("SELECT * FROM logs")
#     for row in results:
#         print(row)

#     # Close the asynchronous connection
#     await db_manager.close_sql_async()

# # To run this, you would typically use an asyncio event loop:
# # import asyncio
# # asyncio.run(run_async_queries())

```

--------------------------------

### Example Python Script in PySpigot Project

Source: https://pyspigot-docs.magicmq.dev/pyspigot/pyspigot

Demonstrates a basic Python script file that might be found within the 'projects' directory of a PySpigot plugin. This file would contain the core logic for a specific project managed by PySpigot.

```python
# main.py
# Example Python script for a PySpigot project

print("Hello from PySpigot project!")

```

--------------------------------

### Callback Tasks Example

Source: https://pyspigot-docs.magicmq.dev/managers/tasks

Illustrates how to use callback tasks in PySpigot, where an asynchronous task can trigger a synchronous callback upon completion.

```python
from spigot import TaskManager

def async_task():
    print("Async task running...")
    # Simulate some async work
    return "Result from async task"

def sync_callback(result):
    print(f"Callback received: {result}")

task_manager = TaskManager()
task_manager.run_async_with_callback(async_task, sync_callback)
```

--------------------------------

### PySpigot Scripting Basics

Source: https://pyspigot-docs.magicmq.dev/scripts/writingscripts

This section details the fundamental aspects of writing PySpigot scripts, including Jython considerations, standard Python libraries, script information, options, permissions, loading, unloading, start/stop functions, helper modules, global variables, and error handling.

```APIDOC
A Note About Jython:
  Explains the use of Jython and its implications for Python scripting in a Java environment.

Standard Python Libraries:
  Details which standard Python libraries are available and how to use them within PySpigot.

Basic Script Information:
  Covers essential information required for any PySpigot script, such as metadata and structure.

Script Options:
  Describes various configuration options that can be set for individual scripts.

Script Permissions:
  Explains how to define and manage permissions for scripts.

Script Loading:
  Details the process by which PySpigot loads scripts into the server.

Script Unloading:
  Covers how scripts are unloaded and the implications of unloading a script from within itself.

Start and Stop Functions:
  Defines the `onEnable()` and `onDisable()` equivalent functions for PySpigot scripts.

The pyspigot.py Helper Module:
  Introduces the core `pyspigot.py` module and its utility functions.

Global Variables:
  Explains the availability and usage of global variables within the PySpigot environment.

Script Errors and Exceptions:
  Details how to handle Python errors and Java exceptions within scripts, including specific workarounds for non-ASCII characters.
```

--------------------------------

### PySpigot Scripting Basics

Source: https://pyspigot-docs.magicmq.dev/scripts/externalresources

Information on writing scripts in PySpigot, including general information, script options, global variables, external libraries, and custom events.

```APIDOC
Scripting:
  General Information: Basic concepts for writing PySpigot scripts.
  Script Options: Configuration options specific to individual scripts.
  Global Variables: Access to globally available variables within scripts.
  External Libraries: How to include and use external Python libraries.
  Custom Events: Defining and handling custom events.
```

--------------------------------

### PlaceholderAPI Placeholder Unregistration Example

Source: https://pyspigot-docs.magicmq.dev/managers/placeholders

Shows how to unregister a previously registered placeholder expansion from PlaceholderAPI using PySpigot's manager.

```python
# Example of unregistering a placeholder
placeholder_manager.unregister_placeholder("myplugin", "hello")
```

--------------------------------

### Get Asynchronous Protocol Manager

Source: https://pyspigot-docs.magicmq.dev/managers/protocollib

Retrieves the asynchronous protocol manager instance from PySpigot. This manager is used for handling packets asynchronously.

```python
import pyspigot as ps

async_manager = ps.protocol.async()
```

--------------------------------

### PySpigot Project Options

Source: https://pyspigot-docs.magicmq.dev/pyspigot/pyspigot

Details the various options that can be configured for Python projects managed by PySpigot.

```text
Project Options:
  'main-script': The entry point script for the project.
  'version': The version of the project.
  'author': The author of the project.
```

--------------------------------

### Create a Simple Broadcast Script

Source: https://pyspigot-docs.magicmq.dev/pyspigot/quickstart

This Python script demonstrates how to broadcast a message to all online players using PySpigot. It imports the Bukkit API and uses the broadcastMessage function.

```python
from org.bukkit import Bukkit

Bukkit.broadcastMessage('Hello world!')
```

--------------------------------

### Teleporting Players with Jython

Source: https://pyspigot-docs.magicmq.dev/scripts/writingscripts

This example demonstrates how to access the Spigot API from Jython to teleport all online players to a specific location in the 'world' world.

```python
fromorg.bukkitimport Bukkit
fromorg.bukkitimport Location

teleport_location = Location(Bukkit.getWorld('world'), 0, 64, 0)

online_players = Bukkit.getOnlinePlayers()

for player in online_players:
    player.teleport(teleport_location)

```

--------------------------------

### Enable Script Option Example

Source: https://pyspigot-docs.magicmq.dev/scripts/scriptoptions

Demonstrates how to set the 'enabled' option for a Python script. This option controls whether a script is active or inactive.

```yaml
test.py:
  enabled:true
```

--------------------------------

### Player Join Message Notification

Source: https://pyspigot-docs.magicmq.dev/scripts/examples

Displays notifications when a player joins the server. This script utilizes event listeners to react to player join events.

```python
from pyspigot import PySpigot

@PySpigot.event('player_join')
def player_join_message(player):
    PySpigot.broadcast_message(f"§a{player.get_name()} has joined the server!")
```

--------------------------------

### Loading Configuration with Defaults

Source: https://pyspigot-docs.magicmq.dev/managers/configuration

Demonstrates how to load a configuration file using PySpigot, providing a default configuration string. It then retrieves values, showcasing the fallback mechanism for missing keys.

```python
import pyspigot as ps

config_defaults = """
key-1: 'Key 1'
key-2: 'Key 2'
key-3: 'Key 3'
"""

config = ps.config.loadConfig('script_config.yml', config_defaults)

print(config.getString('key-1'))
print(config.getString('key-2'))
print(config.getString('key-3'))
```

--------------------------------

### PySpigot Projects - General Information

Source: https://pyspigot-docs.magicmq.dev/index

This section provides general information about creating PySpigot projects. It outlines the structure and requirements for developing larger, more complex plugins as projects.

```python
# PySpigot Projects - General Information
# This section covers the fundamentals of developing PySpigot plugins as projects.
# Projects offer a more structured approach compared to single-file scripts.

# Project structure typically includes:
# - main plugin file (e.g., plugin.py)
# - configuration files
# - other script modules

```