Galaxy-Strike-Online/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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

   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

curl -X GET "http://localhost:3001/api/mods" \
     -H "Authorization: Bearer YOUR_TOKEN"

Enable a mod

curl -X POST "http://localhost:3001/api/mods/1/enable" \
     -H "Authorization: Bearer YOUR_TOKEN"

Disable a mod

curl -X POST "http://localhost:3001/api/mods/1/disable" \
     -H "Authorization: Bearer YOUR_TOKEN"

Set mod load order

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:

{
  "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:

{
  "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:

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:

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:

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

{
  "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

{
  "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.