# Alterchase Modding SDK

Welcome to the Alterchase Modding SDK! This SDK allows you to create custom content for Alterchase including levels, models, and enemies.

## Table of Contents

1. [Getting Started](#getting-started)
2. [Creating Mod Assets](#creating-mod-assets)
3. [Building Mod Packages](#building-mod-packages)
4. [Testing Your Mods](#testing-your-mods)
5. [Publishing to mod.io](#publishing-to-modio)
6. [Best Practices](#best-practices)

## Getting Started

### Installation

1. Open your Unity project (Unity 6000.2 or later recommended)
2. Import the Alterchase SDK package
3. Ensure you have Newtonsoft.Json installed (should be already available in your packages)
4. Open the SDK windows from the menu: `Alterchase SDK`

### SDK Structure

The SDK consists of three main components:

- **Mod Assets**: Individual content pieces (Levels, Models, Enemies)
- **Mod Packages**: Collections of mod assets ready for distribution
- **Editor Tools**: Windows to help you create, validate, and publish mods

## Creating Mod Assets

### Level Mod Assets

Create custom levels for Alterchase players to explore.

**To create a Level Mod Asset:**

1. Right-click in the Project window
2. Select `Create > Alterchase SDK > Level Mod Asset`
3. Configure the following properties:
   - **Asset Name**: The display name of your level
   - **Scene Asset**: The Unity scene file for your level
   - **Level Preview**: A thumbnail image of your level
   - **Difficulty**: Set the difficulty (Easy, Medium, Hard, Expert, Nightmare)
   - **Estimated Completion Time**: How long it takes to complete (in seconds)
   - **Level Tags**: Keywords to help players find your level
   - **Supports Multiplayer**: Whether your level works in multiplayer mode
   - **Player Spawn Point**: Where the player starts in your level
   - **Ambient Music**: Background music for your level

**Level Design Tips:**
- Ensure your level has a player spawn point
- Test your level thoroughly before publishing
- Add clear objectives or goals for players
- Consider performance optimization for complex scenes

### Model Mod Assets

Add custom 3D models as props, decorations, or interactive objects.

**To create a Model Mod Asset:**

1. Right-click in the Project window
2. Select `Create > Alterchase SDK > Model Mod Asset`
3. Configure the following properties:
   - **Asset Name**: The display name of your model
   - **Model Prefab**: Your GameObject prefab
   - **Category**: What type of model it is (Prop, Furniture, Vehicle, etc.)
   - **Is Interactable**: Can players interact with it?
   - **Has Physics**: Should it use physics simulation?
   - **Mass**: Weight of the object (if physics enabled)
   - **Materials**: Custom materials for your model
   - **Can Be Destroyed**: Can it be destroyed during gameplay?
   - **Destruction Prefab**: What spawns when destroyed
   - **Sound Effects**: Audio clips for interactions

**Model Creation Tips:**
- Keep polygon count reasonable for performance
- Ensure your models have proper colliders
- Use appropriate materials and textures
- Test physics interactions in-game

### Enemy Mod Assets

Create custom enemies with unique behaviors and characteristics.

**To create an Enemy Mod Asset:**

1. Right-click in the Project window
2. Select `Create > Alterchase SDK > Enemy Mod Asset`
3. Configure the following properties:
   - **Asset Name**: The display name of your enemy
   - **Enemy Prefab**: Your enemy GameObject with all components
   - **Tier**: Enemy type (Basic, Elite, Boss, MiniBoss)
   - **Max Health**: Total health points
   - **Move Speed**: How fast the enemy moves
   - **Attack Damage**: Damage dealt per attack
   - **Attack Range**: How close enemy needs to be to attack
   - **Attack Cooldown**: Time between attacks
   - **Detection Range**: How far the enemy can detect players
   - **Animator Controller**: Animation controller for the enemy
   - **Behavior Type**: AI behavior (Aggressive, Defensive, Patrol, etc.)
   - **Can Fly**: Can the enemy fly?
   - **Can Climb**: Can it climb surfaces?
   - **Patrol Radius**: Area the enemy patrols
   - **Experience On Kill**: XP rewarded when defeated
   - **Drop Items**: Items that drop on death
   - **Drop Chance**: Probability of dropping items
   - **Sound Effects**: Various audio clips for the enemy

**Enemy Design Tips:**
- Balance health, damage, and speed appropriately
- Ensure your enemy prefab has necessary components (Rigidbody, Collider, etc.)
- Test AI behavior thoroughly
- Consider adding visual and audio feedback for attacks

## Building Mod Packages

### Creating a Mod Package

1. Open `Alterchase SDK > Mod Package Builder`
2. Click "Create New" to create a new Mod Package
3. Fill in package information:
   - **Package Name**: Name of your mod
   - **Author Name**: Your name
   - **Version**: Version number (e.g., 1.0.0)
   - **Description**: What your mod adds
   - **Package Icon**: A thumbnail for your mod
     - **Recommended Size**: 512x288 pixels (16:9 aspect ratio)
     - **Format**: PNG or JPG
     - **Maximum File Size**: 8MB
     - This ensures compatibility with mod.io and optimal display quality
   - **Tags**: Keywords to help players find your mod

### Adding Assets to Your Package

1. Select your Mod Package in the Project window
2. In the Inspector, add your mod assets to the appropriate lists:
   - **Levels**: Drag your Level Mod Assets here
   - **Models**: Drag your Model Mod Assets here
   - **Enemies**: Drag your Enemy Mod Assets here

### Validating Your Package

1. Open `Alterchase SDK > Mod Package Builder`
2. Select your Mod Package
3. Click "Validate Package"
4. Fix any errors that appear

### Building Asset Bundles

1. Ensure your package is validated
2. In the Mod Package Builder, click "Build Asset Bundles"
3. Your mod will be built to the output path specified in the package
4. Asset bundles will be created in `Builds/Mods/[YourModName]/`

## Testing Your Mods

### Using the Mod Tester Window

The Mod Tester provides a complete testing environment for your built mods.

**To test your mod:**

1. Build your mod package first (see [Building Asset Bundles](#building-asset-bundles))
2. Open `Alterchase SDK > Mod Tester`
3. Load your asset bundle:
   - Click **"Browse"**
   - Navigate to `Builds/Mods/[YourModName]/`
   - Select your asset bundle file
   - Click **"Load Asset Bundle"**

**Testing Features:**

- **Package Information**: View mod name, author, version, and asset counts
- **Load & Test Levels**: Automatically creates a test scene for level testing
- **Spawn Models**: Instantly spawn model prefabs in your current scene
- **Spawn Enemies**: Place enemy prefabs for behavior testing
- **Create Test Scene**: Generate a new test environment with a floor and proper lighting
- **Enter Play Mode**: Quick access to test your mod in runtime

**Workflow Example:**

```
1. Load your asset bundle
2. Click "Create Test Scene" to set up a testing environment
3. Spawn models or enemies to test
4. Click "Enter Play Mode" to see them in action
5. Exit Play Mode and iterate
6. Click "Unload" when done
```

### Using ModLoaderTestHelper (Advanced)

For automated testing in Play Mode, use the `ModLoaderTestHelper` component:

1. Create a new scene or use an existing one
2. Add an empty GameObject and attach the `ModLoaderTestHelper` component
3. Configure settings:
   - **Asset Bundle Path**: Path to your built asset bundle
   - **Level To Load**: Name of the level to auto-load (optional)
   - **Auto Spawn Models**: Automatically spawn all models on Start
   - **Auto Spawn Enemies**: Automatically spawn all enemies on Start
   - **Spawn Spacing**: Distance between spawned objects
4. Enter Play Mode to test

**Example Setup:**

```csharp
// This component auto-loads and tests your mod when you enter Play Mode
var testHelper = gameObject.AddComponent<ModLoaderTestHelper>();
testHelper.assetBundlePath = "Builds/Mods/MyMod/mymod";
testHelper.autoSpawnModels = true;
testHelper.spawnSpacing = 5f;
```

### Manual Testing with Code

For custom test scenarios, load and test mods programmatically:

```csharp
using AlterchaseSDK;
using UnityEngine;

public class CustomModTester : MonoBehaviour
{
    void Start()
    {
        // Load asset bundle
        AssetBundle bundle = AssetBundle.LoadFromFile("Builds/Mods/MyMod/mymod");
        
        // Get the mod package
        ModPackage package = bundle.LoadAsset<ModPackage>("MyModPackage");
        
        // Load specific assets
        ModelModAsset[] models = bundle.LoadAllAssets<ModelModAsset>();
        foreach (var model in models)
        {
            GameObject instance = Instantiate(model.ModelPrefab);
            Debug.Log($"Spawned: {model.AssetName}");
        }
    }
}
```

## Distributing Your Mods

### Preparing for Distribution

1. Build your asset bundles (see Building Asset Bundles section)
2. Test your mod thoroughly using the Mod Tester tool
3. Verify all assets load correctly

### Distribution Options

After building your mod package, you can distribute it through various channels:

- **Manual Distribution**: Share the built mod files directly with players
- **Community Platforms**: Upload to modding communities or file-sharing platforms
- **Third-Party Platforms**: Use platforms like mod.io, Nexus Mods, or others by manually uploading your built files

### Distribution Files

Your built mod files will be located in:
- Default path: `ModBuilds/[YourModName]`
- Contains: `.mod` asset bundle files

For detailed distribution guidance, see [DISTRIBUTION_GUIDE.md](DISTRIBUTION_GUIDE.md).

## Best Practices

### Performance

- Keep polygon counts reasonable (< 50k triangles per model)
- Optimize textures (use appropriate resolutions)
- Use occlusion culling in levels
- Limit the number of active physics objects
- Profile your content in the Unity Profiler

### Compatibility

- Test your mods with the latest version of Alterchase
- Ensure all required assets are included in your package
- Avoid modifying core game files
- Follow the project's coding guidelines

### Quality

- Provide clear descriptions for your mods
- Include preview images and screenshots
  - **Package Icon**: 512x288 pixels (16:9 ratio) for mod.io compatibility
  - **Level Previews**: 1920x1080 pixels or 1280x720 pixels recommended
  - Use high-quality JPG or PNG images under 8MB each
- Test thoroughly before publishing
- Respond to player feedback
- Keep your mods updated

### Asset Organization

- Keep all mod assets in a dedicated folder structure:
  ```
  /Assets/MyMods/
    /MyModName/
      /Levels/
      /Models/
      /Enemies/
      /Materials/
      /Textures/
      /Audio/
  ```

### Naming Conventions

- Use clear, descriptive names for assets
- Avoid special characters in file names
- Use consistent naming patterns
- Prefix custom assets to avoid conflicts

## SDK Tools Reference

### Mod Asset Library

Browse and manage all mod assets in your project.

- **Location**: `Alterchase SDK > Mod Asset Library`
- **Features**:
  - View all Level, Model, and Enemy assets
  - Search and filter assets
  - Quick validation
  - Create new assets

### Mod Package Builder

Build and validate your mod packages.

- **Location**: `Alterchase SDK > Mod Package Builder`
- **Features**:
  - Create new packages
  - Validate packages
  - Build asset bundles
  - View package information

### mod.io Upload Window

Upload your mods to the mod.io platform.

- **Location**: `Alterchase SDK > Upload to mod.io`
- **Features**:
  - Authenticate with mod.io
  - Upload mod packages
  - Manage uploads

## Support

For help and support:

- Check the Alterchase Discord server
- Visit the mod.io community forums
- Report issues on the GitHub repository

## License

This SDK is provided for creating content for Alterchase. Please review the modding terms of service before publishing content.

---

**Happy Modding!**

Create amazing content for the Alterchase community!
