API/docs/Server-Modding-Guide.md

# Server Modding Guide

This guide explains how to create and install mods for the Galaxy Strike Online server.

## Overview

The Galaxy Strike Online server supports modding through a local SQLite database that stores mod data and assets. Mods can add new ships, items, quests, and game systems to the server.

## Mod Directory Structure

All mods are stored in the `GameServer/mods/` directory. Each mod has its own folder with the following structure:

```
GameServer/mods/
├── your-mod-name/
│   ├── mod.json              # Mod manifest file
│   └── assets/               # Mod assets folder
│       ├── ships/            # Ship definitions
│       ├── items/            # Item definitions
│       ├── quests/           # Quest definitions
│       └── systems/          # Game system modifications
```

## Mod Manifest (mod.json)

Every mod must include a `mod.json` file in its root directory with the following structure:

```json
{
  "name": "Your Mod Name",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A brief description of your mod",
  "dependencies": ["other-mod-name"],
  "config": {
    "setting1": "value1",
    "setting2": 42
  }
}
```

### Required Fields
- `name` - Unique identifier for your mod
- `version` - Version string (semantic versioning recommended)
- `author` - Mod author name

### Optional Fields
- `description` - Brief description of what your mod does
- `dependencies` - Array of mod names that must be loaded first
- `config` - Configuration options for your mod

## Asset Types

### Ships

Place ship definitions in `assets/ships/` as JSON files:

```json
{
  "id": "custom_fighter",
  "name": "Custom Fighter",
  "description": "A powerful custom fighter ship",
  "rarity": "rare",
  "stats": {
    "health": 150,
    "maxHealth": 150,
    "attack": 25,
    "defense": 15,
    "speed": 20,
    "criticalChance": 0.10,
    "criticalDamage": 2.0
  },
  "abilities": [
    {
      "id": "laser_burst",
      "name": "Laser Burst",
      "damage": 50,
      "cooldown": 5
    }
  ],
  "requirements": {
    "level": 10,
    "credits": 5000
  }
}
```

### Items

Place item definitions in `assets/items/` as JSON files:

```json
{
  "id": "custom_blaster",
  "name": "Custom Blaster",
  "description": "A powerful custom blaster",
  "type": "weapon",
  "rarity": "epic",
  "stats": {
    "attack": 30,
    "criticalChance": 0.15,
    "criticalDamage": 2.5
  },
  "requirements": {
    "level": 15,
    "class": "fighter"
  },
  "value": 2500
}
```

### Quests

Place quest definitions in `assets/quests/` as JSON files:

```json
{
  "id": "custom_mission",
  "name": "Custom Mission",
  "description": "A special custom mission",
  "type": "combat",
  "difficulty": "medium",
  "objectives": [
    {
      "type": "defeat_enemies",
      "target": "enemy_fighter",
      "count": 10
    },
    {
      "type": "collect_items",
      "target": "energy_crystal",
      "count": 5
    }
  ],
  "rewards": {
    "experience": 1000,
    "credits": 2000,
    "items": ["custom_blaster"]
  },
  "requirements": {
    "level": 12,
    "completed_quests": ["basic_training"]
  }
}
```

### Systems

Place system modifications in `assets/systems/` as JSON files:

```json
{
  "id": "custom_combat_system",
  "name": "Custom Combat System",
  "description": "Modifies combat mechanics",
  "type": "combat",
  "modifications": {
    "damage_formula": "base_damage * (1 + critical_chance * critical_damage)",
    "speed_bonus": 1.2,
    "defense_reduction": 0.9
  },
  "conditions": {
    "player_level": 20,
    "active_mods": ["advanced_combat"]
  }
}
```

## Installation

### Automatic Installation

1. Create your mod folder in `GameServer/mods/`
2. Add your `mod.json` manifest and assets
3. Restart the GameServer or use the reload endpoint:
   ```bash
   curl -X POST "http://localhost:3001/api/mods/reload" \
        -H "Authorization: Bearer YOUR_TOKEN"
   ```

### Manual Installation via API

You can also manage mods through the API endpoints:

#### List all mods
```bash
curl -X GET "http://localhost:3001/api/mods" \
     -H "Authorization: Bearer YOUR_TOKEN"
```

#### Enable a mod
```bash
curl -X POST "http://localhost:3001/api/mods/1/enable" \
     -H "Authorization: Bearer YOUR_TOKEN"
```

#### Disable a mod
```bash
curl -X POST "http://localhost:3001/api/mods/1/disable" \
     -H "Authorization: Bearer YOUR_TOKEN"
```

#### Set mod load order
```bash
curl -X POST "http://localhost:3001/api/mods/load-order" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"modIds": [1, 3, 2]}'
```

## Mod Development Best Practices

### 1. Use Unique IDs
Always use unique IDs for your assets to avoid conflicts:
```json
{
  "id": "yourmodname_ship_name",
  "name": "Ship Name"
}
```

### 2. Version Your Mods
Use semantic versioning (major.minor.patch):
- `1.0.0` - Initial release
- `1.1.0` - New features
- `1.1.1` - Bug fixes
- `2.0.0` - Breaking changes

### 3. Handle Dependencies
If your mod depends on other mods, specify them in `mod.json`:
```json
{
  "dependencies": ["base_game_expansion", "common_items_pack"]
}
```

### 4. Test Thoroughly
- Test your mod with and without other popular mods
- Test different player levels and progressions
- Verify all assets load correctly

### 5. Provide Documentation
Include a README.md in your mod folder with:
- Installation instructions
- Configuration options
- Known issues
- Changelog

## Configuration

### Server Preferences
Set server-wide mod preferences via API:
```bash
curl -X POST "http://localhost:3001/api/mods/preferences/server" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"key": "max_mods_per_player", "value": 10}'
```

### Mod-Specific Configuration
Access your mod's configuration in-game:
```javascript
const modConfig = await ModService.getModConfig('your-mod-name');
```

## Troubleshooting

### Common Issues

1. **Mod not loading**
   - Check `mod.json` syntax
   - Verify all required fields are present
   - Check server logs for error messages

2. **Assets not appearing**
   - Verify file paths are correct
   - Check JSON syntax in asset files
   - Ensure assets are in the correct subdirectories

3. **Load order issues**
   - Set explicit load order via API
   - Check dependencies are satisfied
   - Verify dependent mods are enabled

4. **Performance issues**
   - Limit the number of assets per mod
   - Optimize JSON structures
   - Use efficient algorithms in system modifications

### Debug Mode

Enable debug logging by setting the LOG_LEVEL environment variable:
```bash
LOG_LEVEL=debug npm start
```

## API Reference

### Authentication
All mod management endpoints require JWT authentication. Include your token in the Authorization header:
```
Authorization: Bearer YOUR_JWT_TOKEN
```

### Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/mods` | List all mods |
| GET | `/api/mods/:id` | Get specific mod |
| POST | `/api/mods/:id/enable` | Enable mod |
| POST | `/api/mods/:id/disable` | Disable mod |
| GET | `/api/mods/assets/:type` | Get assets by type |
| GET | `/api/mods/assets/:type/:assetId` | Get specific asset |
| GET | `/api/mods/load-order` | Get load order |
| POST | `/api/mods/load-order` | Set load order |
| GET | `/api/mods/preferences/server` | Get server preferences |
| POST | `/api/mods/preferences/server` | Set server preference |
| POST | `/api/mods/reload` | Reload mods from filesystem |

## Example Mod

Here's a complete example of a simple mod that adds a new ship:

### File Structure
```
GameServer/mods/
└── simple_ship_pack/
    ├── mod.json
    └── assets/
        └── ships/
            └── scout_ship.json
```

### mod.json
```json
{
  "name": "Simple Ship Pack",
  "version": "1.0.0",
  "author": "Example Author",
  "description": "Adds a simple scout ship to the game"
}
```

### assets/ships/scout_ship.json
```json
{
  "id": "simple_ship_pack_scout",
  "name": "Scout Ship",
  "description": "A fast and agile scout ship",
  "rarity": "common",
  "stats": {
    "health": 80,
    "maxHealth": 80,
    "attack": 15,
    "defense": 8,
    "speed": 25,
    "criticalChance": 0.08,
    "criticalDamage": 1.8
  },
  "abilities": [
    {
      "id": "quick_scan",
      "name": "Quick Scan",
      "description": "Reveals nearby enemies",
      "cooldown": 10
    }
  ],
  "requirements": {
    "level": 5,
    "credits": 1000
  }
}
```

This mod will be automatically loaded when the server starts and will add the Scout Ship to the game, available for players to purchase at level 5.