Add Documentation Files

best_practices.md

@@ -0,0 +1,174 @@
+# Best Practices for Developing Scripts with Spectra
+
+This guide outlines best practices for developing scripts using Spectra, a powerful scripting framework for Bukkit plugins. By following these guidelines, you can create efficient, maintainable, and robust scripts for your Minecraft server.
+
+## Performance Optimization
+
+1. **Minimize event listener usage:**
+   Only register event listeners when necessary, and remove them when they're no longer needed. Excessive event listeners can impact server performance.
+
+   ```javascript
+   // Good practice: Remove event listener when it's no longer needed
+   const listener = (event) => {
+     // Handle event
+     removeEventListener("playerJoin", listener);
+   };
+   addEventListener("playerJoin", listener);
+   ```
+
+2. **Use efficient data structures:**
+   Choose appropriate data structures for your use case. For example, use Sets for unique collections and Maps for key-value pairs.
+
+   ```javascript
+   // Good practice: Using a Set for unique player names
+   const uniquePlayers = new Set();
+   ```
+
+3. **Avoid blocking operations:**
+   Perform long-running or blocking operations asynchronously to prevent server lag.
+
+   ```javascript
+   // Good practice: Using setTimeout for delayed execution
+   setTimeout(() => {
+     // Perform resource-intensive operation
+   }, 0);
+   ```
+
+## Error Handling
+
+1. **Use try-catch blocks:**
+   Wrap potentially error-prone code in try-catch blocks to gracefully handle exceptions.
+
+   ```javascript
+   try {
+     // Potentially error-prone code
+   } catch (error) {
+     console.error("An error occurred:", error.message);
+   }
+   ```
+
+2. **Validate input:**
+   Always validate user input and function parameters to prevent unexpected behavior.
+
+   ```javascript
+   function damagePlayer(player, amount) {
+     if (typeof amount !== "number" || amount < 0) {
+       throw new Error("Invalid damage amount");
+     }
+     // Apply damage to player
+   }
+   ```
+
+3. **Provide meaningful error messages:**
+   When throwing errors or logging issues, include descriptive messages to aid in debugging.
+
+   ```javascript
+   if (!player.hasPermission("admin")) {
+     throw new Error("Player does not have admin permissions");
+   }
+   ```
+
+## Code Organization
+
+1. **Modularize your code:**
+   Split your script into smaller, reusable functions and modules for better maintainability.
+
+   ```javascript
+   // economy.js
+   export function getBalance(player) {
+     // Implementation
+   }
+
+   export function addMoney(player, amount) {
+     // Implementation
+   }
+
+   // main.js
+   import { getBalance, addMoney } from "./economy.js";
+   ```
+
+2. **Use consistent naming conventions:**
+   Adopt a consistent naming style for variables, functions, and classes throughout your scripts.
+
+   ```javascript
+   // Good practice: Consistent camelCase for functions and variables
+   function calculateTotalDamage(baseDamage, multiplier) {
+     const critChance = 0.1;
+     // Implementation
+   }
+   ```
+
+3. **Comment your code:**
+   Add meaningful comments to explain complex logic or non-obvious behavior.
+
+   ```javascript
+   // Calculate damage based on player's equipment and buffs
+   function calculateDamage(player) {
+     let baseDamage = player.getWeaponDamage();
+
+     // Apply strength buff if active
+     if (player.hasEffect("strength")) {
+       baseDamage *= 1.5;
+     }
+
+     // Reduce damage if player is weakened
+     if (player.hasEffect("weakness")) {
+       baseDamage *= 0.8;
+     }
+
+     return baseDamage;
+   }
+   ```
+
+## Example of a Well-Structured Script
+
+Here's an example of a well-structured script that incorporates the best practices mentioned above:
+
+```javascript
+// playerUtils.js
+export function isPlayerAdmin(player) {
+  return player.hasPermission("admin");
+}
+
+export function giveWelcomeKit(player) {
+  // Implementation
+}
+
+// main.js
+import { isPlayerAdmin, giveWelcomeKit } from "./playerUtils.js";
+
+const WELCOME_MESSAGE = "Welcome to the server!";
+
+function onPlayerJoin(event) {
+  const player = event.getPlayer();
+
+  try {
+    console.log(`Player ${player.getName()} joined the server`);
+
+    player.sendMessage(WELCOME_MESSAGE);
+
+    if (isPlayerAdmin(player)) {
+      player.sendMessage("You have admin privileges");
+    }
+
+    // Delay welcome kit to avoid overwhelming new players
+    setTimeout(() => {
+      giveWelcomeKit(player);
+    }, 5000);
+  } catch (error) {
+    console.error(`Error handling player join: ${error.message}`);
+  }
+}
+
+addEventListener("playerJoin", onPlayerJoin);
+
+export function onEnable() {
+  console.log("Script enabled successfully");
+}
+
+export function onDisable() {
+  console.log("Script disabled");
+}
+```
+
+By following these best practices and structuring your scripts well, you'll create more efficient, maintainable, and robust code for your Spectra-powered Bukkit plugins.

configuration_guide.md

@@ -0,0 +1,118 @@
+---
+title: Spectra Configuration Guide
+description: Learn how to configure Spectra, including server settings, Java options, and plugin-specific configurations.
+---
+
+# Spectra Configuration Guide
+
+This guide provides detailed information on how to configure Spectra, including server settings, Java options, and plugin-specific configurations. We'll explain the purpose of each configuration option and provide examples to help you set up your Spectra environment.
+
+## Table of Contents
+
+1. [Configuration File](#configuration-file)
+2. [Configuration Options](#configuration-options)
+   - [Build Options](#build-options)
+   - [Server Options](#server-options)
+   - [Java Options](#java-options)
+   - [JAR Options](#jar-options)
+3. [Examples](#examples)
+
+## Configuration File
+
+Spectra uses a configuration file to define various settings for your Minecraft server. By default, Spectra looks for a configuration file named `spectra.config.mjs` or `spectra.config.js` in the current working directory.
+
+To create a configuration file, use the `defineConfig` function provided by Spectra:
+
+```javascript
+import { defineConfig } from 'spectra-sdk';
+
+export default defineConfig({
+  // Your configuration options here
+});
+```
+
+## Configuration Options
+
+The Spectra configuration object supports the following options:
+
+### Build Options
+
+- `build`: (Optional) An object containing esbuild options for building your Spectra plugins.
+
+### Server Options
+
+- `server`: (Optional) An object containing server-specific options:
+  - `eula`: (Boolean, default: `false`) Set to `true` to accept the [Minecraft EULA](https://aka.ms/MinecraftEULA). You must accept the EULA before running a server.
+  - `dir`: (String, default: `".minecraft"`) The directory where the server files will be stored.
+  - `type`: (String, default: `"spigot"`) The type of Minecraft server to use. Available options are `"spigot"`, `"paper"`, or `"purpur"`.
+  - `version`: (String, optional) The Minecraft server version to use. If not specified, the latest version will be used.
+
+### Java Options
+
+- `server.java`: (Optional) An object containing Java-specific options:
+  - `path`: (String, default: `"java"`) The path to the Java executable.
+  - `args`: (Array of strings, default: `["-Xmx2G", "-Xms2G"]`) Arguments to pass to the Java executable.
+
+### JAR Options
+
+- `server.jar`: (Optional) An object containing JAR-specific options:
+  - `path`: (String, optional) The path to a custom server JAR file. If provided, this will be used instead of downloading a server JAR based on the `type` and `version` options.
+  - `args`: (Array of strings, default: `["nogui"]`) Arguments to pass to the server JAR.
+
+## Examples
+
+Here are some example configurations to help you get started:
+
+### Basic Configuration
+
+```javascript
+import { defineConfig } from 'spectra-sdk';
+
+export default defineConfig({
+  server: {
+    eula: true,
+    type: 'paper',
+    version: '1.19.4',
+  },
+});
+```
+
+This configuration sets up a Paper server running version 1.19.4 with the EULA accepted.
+
+### Advanced Configuration
+
+```javascript
+import { defineConfig } from 'spectra-sdk';
+
+export default defineConfig({
+  build: {
+    entryPoints: ['src/index.ts'],
+    outfile: 'dist/plugin.js',
+  },
+  server: {
+    eula: true,
+    dir: 'my-server',
+    type: 'purpur',
+    version: '1.20',
+    java: {
+      path: '/usr/bin/java',
+      args: ['-Xmx4G', '-Xms2G'],
+    },
+    jar: {
+      args: ['nogui', 'max-players=50'],
+    },
+  },
+});
+```
+
+This advanced configuration:
+
+1. Sets up build options for a Spectra plugin.
+2. Creates a Purpur server running version 1.20.
+3. Specifies a custom server directory.
+4. Uses a specific Java executable with custom memory allocation.
+5. Passes additional arguments to the server JAR.
+
+Remember to adjust these configurations based on your specific needs and server requirements.
+
+By using the Spectra configuration system, you can easily customize your Minecraft server environment and ensure consistent settings across your development and production setups.