README.md

# ⚡ ScriptsLab

<div align="center">

![ScriptsLab Logo](https://img.shields.io/badge/ScriptsLab-v1.0.2-blue?style=for-the-badge)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Paper](https://img.shields.io/badge/Paper-1.21.8-green?style=for-the-badge)](https://papermc.io/)
[![Java](https://img.shields.io/badge/Java-17-orange?style=for-the-badge)](https://adoptium.net/)

**Production-Grade JavaScript Scripting Framework for Minecraft Paper Servers**

[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Examples](#-examples) • [Contributing](#-contributing)

</div>

---

## 📖 Overview

ScriptsLab is a powerful, production-ready plugin framework for Paper/Spigot servers that enables server administrators and developers to create custom gameplay features using JavaScript. Built on **GraalVM**, it provides a clean, modern API with full access to the Bukkit/Paper API.

### Why ScriptsLab?

| Feature | Description |
|---------|-------------|
| 🚀 **Zero Restart Required** | Hot-reload scripts without restarting your server |
| 🎯 **Clean Architecture** | Modular design with dependency injection |
| ⚡ **High Performance** | Powered by GraalVM JavaScript engine |
| 🔒 **Thread-Safe** | Automatic synchronization for Bukkit API calls |
| 🎨 **Rich API** | Commands, events, items, storage, scheduler, and more |
| 📦 **Module System** | Organize code into reusable modules |
| 🛠️ **Developer Friendly** | Modern JavaScript with full IDE support |

---

## ✨ Features

### Core Features

- 🎮 **Command System** - Register custom commands with permissions
- 📡 **Event System** - Listen to any Bukkit/Paper event
- ⚔️ **Custom Items** - Create items with custom abilities and attributes
- 💾 **Storage System** - YAML-based persistent data storage
- ⏰ **Task Scheduler** - Sync/async task scheduling
- 📊 **Metrics Collection** - Built-in performance monitoring
- 🔌 **Module System** - Hot-loadable plugin modules

### Advanced Features

- **Thread-Safe API** - Automatic main-thread scheduling for Bukkit calls
- **Dependency Injection** - Clean service architecture
- **Event Bus** - Internal plugin communication
- **Script Hot-Reload** - Update scripts without restart
- **Unrestricted Mode** - Full Java API access (configurable)

---

## 📦 Installation

### Requirements

| Requirement | Version |
|--------------|---------|
| Minecraft Server | Paper 1.21.8+ (or compatible Spigot fork) |
| Java | 17 or higher |
| Memory | Minimum 2GB RAM (GraalVM included in JAR) |

### Steps

1. **Download** the latest `ScriptsLab-1.0.0.jar` from [Releases](https://github.com/yourusername/ScriptsLab/releases)

2. **Install** the plugin:
   ```bash
   cp ScriptsLab-1.0.0.jar /path/to/server/plugins/
   ```

3. **Start** your server:
   ```bash
   java -Xmx2G -jar paper.jar
   ```

4. **Verify** installation:
   ```
   [ScriptsLab] ✓ Script Engine initialized
   [ScriptsLab] ✓ Loaded X scripts
   ```

---

## 🚀 Quick Start

### Your First Script

Create a file `plugins/ScriptsLab/scripts/hello.js`:

```javascript
Commands.register('hello', function(sender, args) {
    sender.sendMessage('§aHello, ' + sender.getName() + '!');
}, 'scriptslab.hello');

Console.log('Hello command registered!');
```

**That's it!** The script loads automatically. Use `/hello` in-game.

### Example: Fly Command

```javascript
Commands.register('fly', function(sender, args) {
    if (!sender.isPlayer()) {
        sender.sendMessage('§cOnly players can fly!');
        return;
    }
    
    var flying = !sender.getAllowFlight();
    sender.setAllowFlight(flying);
    
    if (flying) {
        sender.sendMessage('§aFlight enabled!');
    } else {
        sender.sendMessage('§cFlight disabled!');
    }
}, 'scriptslab.fly');
```

### Example: Welcome Message

```javascript
API.registerEvent('PlayerJoinEvent', function(event) {
    var player = event.getPlayer();
    var Bukkit = Java.type('org.bukkit.Bukkit');
    
    event.joinMessage(null);
    
    player.sendMessage('§6§l⚡ Welcome to the server!');
    player.sendMessage('§7Online: §a' + Bukkit.getOnlinePlayers().size());
});
```

---

## 📚 Documentation

### API Reference

#### Commands API
```javascript
Commands.register(name, handler, permission);

Commands.register('heal', function(sender, args) {
    sender.setHealth(sender.getMaxHealth());
    sender.sendMessage('§aHealed!');
}, 'scriptslab.heal');
```

#### Events API
```javascript
API.registerEvent(eventName, handler);

API.registerEvent('PlayerDeathEvent', function(event) {
    var player = event.getPlayer();
    Console.log(player.getName() + ' died!');
});
```

#### Items API
```javascript
Items.registerItem(id, material, displayName, ...lore);
Items.giveItem(player, itemId, amount);
API.addAttribute(meta, 'GENERIC_ATTACK_DAMAGE', 'modifier_name', 10.0, 'ADD_NUMBER', 'HAND');
```

#### Scheduler API
```javascript
Scheduler.runLater(function() {
    Console.log('Delayed task!');
}, 20);

Scheduler.runTimer(function() {
    Console.log('Every second!');
}, 0, 20);

Scheduler.runAsync(function() {
    // Heavy computation
});
```

#### Storage API
```javascript
var repo = Storage.getRepository('mydata');
repo.set('player.uuid', playerData);
repo.save();
var data = repo.get('player.uuid');
```

#### Thread-Safe Bukkit API
```javascript
API.addPotionEffectSync(player, effectType, duration, amplifier, ambient, particles);
API.strikeLightningSync(location);
API.removePotionEffectSync(player, effectType);
```

#### Console API
```javascript
Console.log('Info message');
Console.warn('Warning message');
Console.error('Error message');
```

---

## 🎯 Examples

### Lightning Sword

Complete example of a custom weapon with abilities:

```javascript
var Material = Java.type('org.bukkit.Material');
var ItemStack = Java.type('org.bukkit.inventory.ItemStack');

Commands.register('getlightningsword', function(sender, args) {
    if (!sender.isPlayer()) return;
    
    var player = org.bukkit.Bukkit.getPlayer(sender.getName());
    var sword = new ItemStack(Material.DIAMOND_SWORD);
    var meta = sword.getItemMeta();
    
    meta.setDisplayName('§6§l⚡ LIGHTNING SWORD ⚡');
    meta.setUnbreakable(true);
    
    API.addAttribute(meta, 'GENERIC_ATTACK_DAMAGE', 'lightning_damage', 10.0, 'ADD_NUMBER', 'HAND');
    API.addAttribute(meta, 'GENERIC_ATTACK_SPEED', 'lightning_speed', 0.8, 'ADD_NUMBER', 'HAND');
    
    sword.setItemMeta(meta);
    player.getInventory().addItem(sword);
    player.sendMessage('§6⚡ You received the Lightning Sword!');
});

API.registerEvent('EntityDamageByEntityEvent', function(event) {
    var Player = Java.type('org.bukkit.entity.Player');
    if (!(event.getDamager() instanceof Player)) return;
    
    var attacker = event.getDamager();
    var item = attacker.getInventory().getItemInMainHand();
    
    if (item && item.getType() === Material.DIAMOND_SWORD) {
        var meta = item.getItemMeta();
        if (meta && meta.hasDisplayName() && 
            meta.getDisplayName().indexOf('LIGHTNING SWORD') !== -1) {
            
            var location = event.getEntity().getLocation();
            API.strikeLightningSync(location);
            
            event.setDamage(event.getDamage() + 5.0);
            attacker.sendMessage('§6⚡ Lightning strikes!');
        }
    }
});
```

More examples in the [`scripts/`](scripts/) directory!

---

## 🏗️ Architecture

ScriptsLab follows **Clean Architecture** principles:

```
┌─────────────────────────────────────┐
│         JavaScript Scripts          │
│    (User-defined functionality)     │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│          Script API Layer           │
│   (ScriptAPIImpl, Thread-Safety)    │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│         Core Services Layer         │
│  (Commands, Events, Items, etc.)    │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│      Bukkit/Paper API Layer         │
│    (Minecraft Server Platform)      │
└─────────────────────────────────────┘
```

### Key Components

| Component | Description |
|-----------|-------------|
| **GraalScriptEngine** | GraalVM JavaScript execution |
| **CommandManager** | Dynamic command registration |
| **EventBus** | Event handling and distribution |
| **ItemManager** | Custom item management |
| **StorageManager** | Persistent data storage |
| **TaskScheduler** | Async/sync task scheduling |
| **DI Container** | Dependency injection |

---

## 🔧 Building from Source

### Prerequisites

- Java 17 JDK
- Maven 3.8+
- Git

### Build Steps

```bash
git clone https://github.com/yourusername/ScriptsLab.git
cd ScriptsLab
mvn clean package -DskipTests
```

Output: `target/ScriptsLab-1.0.0.jar` (~50MB with GraalVM)

### Development

```bash
mvn test           # Run tests
mvn javadoc:javadoc  # Generate documentation
mvn clean         # Clean build
```

---

## 🤝 Contributing

We welcome contributions! Here's how you can help:

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request

### Contribution Guidelines

- Follow existing code style
- Add tests for new features
- Update documentation
- Keep commits atomic and descriptive

---

## 📝 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- **GraalVM Team** - For the amazing JavaScript engine
- **Paper Team** - For the excellent Minecraft server platform
- **Bukkit/Spigot Community** - For the plugin API foundation

---

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/animesao/ScriptsLab/issues)
- **Discussions**: [GitHub Discussions](https://github.com/animesao/ScriptsLab/discussions)
- **Wiki**: [Documentation Wiki](https://github.com/animesao/ScriptsLab/tree/main/wiki)

---

<div align="center">

**Made with ❤️ for the Minecraft community**

⭐ Star us on GitHub if you find this useful!

</div>