# Alterchase SDK - Mod Testing Guide

Complete guide for testing your mods before publishing to mod.io.

## Table of Contents

1. [Why Test Your Mods?](#why-test-your-mods)
2. [Testing Methods](#testing-methods)
3. [Using the Mod Tester Window](#using-the-mod-tester-window)
4. [Using ModLoaderTestHelper](#using-modloadertesthelper)
5. [Manual Testing](#manual-testing)
6. [Testing Checklist](#testing-checklist)
7. [Common Issues](#common-issues)

## Why Test Your Mods?

Testing your mods before publishing ensures:

- ✅ All assets load correctly from the asset bundle
- ✅ Prefabs spawn and function as expected
- ✅ Levels are playable and stable
- ✅ No missing references or broken components
- ✅ Performance is acceptable
- ✅ No console errors or warnings
- ✅ Better player experience

**Always test your mods before uploading to mod.io!**

## Testing Methods

The SDK provides three ways to test your mods:

| Method | Best For | Difficulty |
|--------|----------|------------|
| **Mod Tester Window** | Quick testing, spawning individual assets | Easy |
| **ModLoaderTestHelper** | Automated testing, batch spawning | Medium |
| **Manual Code** | Custom scenarios, advanced testing | Advanced |

## Using the Mod Tester Window

The **Mod Tester** window is the recommended way to test your mods.

### Step 1: Build Your Mod

Before testing, you must build your mod package:

1. Open `Alterchase SDK > Mod Package Builder`
2. Select your Mod Package
3. Click **"Validate Package"** (fix any errors)
4. Click **"Build Asset Bundles"**
5. Wait for the build to complete
6. Note the output path (usually `Builds/Mods/[YourModName]/`)

### Step 2: Open the Mod Tester

1. Open `Alterchase SDK > Mod Tester`
2. The Mod Tester window will appear

### Step 3: Load Your Asset Bundle

1. Click **"Browse"** next to the Bundle Path field
2. Navigate to your build output folder (`Builds/Mods/[YourModName]/`)
3. Select your asset bundle file (no file extension)
4. Click **"Load Asset Bundle"**

The window will display:
- Package name, author, version, and description
- Number of levels, models, and enemies loaded
- List of all assets in the package

### Step 4: Test Individual Assets

**Testing Levels:**
1. Find your level in the "Levels" section
2. Click **"Load & Test Scene"**
3. A new test scene will be created with the ModLoader configured
4. Click **"Enter Play Mode"** to test the level

**Testing Models:**
1. Have a scene open (or click "Create Test Scene")
2. Find your model in the "Models" section
3. Click **"Spawn in Scene"**
4. The model will spawn in front of your Scene View camera
5. Repeat for other models
6. Click **"Enter Play Mode"** to test physics and interactions

**Testing Enemies:**
1. Have a scene open (or click "Create Test Scene")
2. Find your enemy in the "Enemies" section
3. Click **"Spawn in Scene"**
4. The enemy will spawn in front of your Scene View camera
5. Click **"Enter Play Mode"** to test AI behavior

### Step 5: Test in Play Mode

1. Click **"Enter Play Mode"**
2. Test functionality:
   - Walk around and interact with models
   - Test enemy AI behavior
   - Check animations and effects
   - Verify audio plays correctly
   - Monitor the Console for errors
3. Exit Play Mode when finished

### Step 6: Iterate

1. If you find issues, exit Play Mode
2. Click **"Unload"** in the Mod Tester
3. Make changes to your mod assets
4. Rebuild the asset bundle
5. Reload and test again

## Using ModLoaderTestHelper

The `ModLoaderTestHelper` component automates loading and spawning during Play Mode.

### Setup

1. Create a new scene or open an existing one
2. Create an empty GameObject: `GameObject > Create Empty`
3. Name it "ModLoaderTestHelper"
4. Add the component: `Add Component > ModLoaderTestHelper`

### Configuration

**Asset Bundle Path:**
- Set to your built asset bundle path
- Example: `C:/MyProject/Builds/Mods/MyMod/mymod`
- Or use relative path: `Builds/Mods/MyMod/mymod`

**Level To Load:**
- Enter the exact name of a level to auto-load
- Leave empty to skip level loading
- Example: `My Custom Arena`

**Auto Spawn Models:**
- Check to automatically spawn all models when entering Play Mode
- Models will spawn in a row with spacing

**Auto Spawn Enemies:**
- Check to automatically spawn all enemies when entering Play Mode
- Enemies will spawn 5 units forward from the helper object

**Spawn Spacing:**
- Distance between spawned objects (default: 3 units)

### Testing Workflow

1. Configure the ModLoaderTestHelper
2. Enter Play Mode
3. Assets will automatically load and spawn
4. Test functionality
5. Exit Play Mode
6. Adjust settings and repeat

### Example Configurations

**Test All Assets:**
```
Asset Bundle Path: Builds/Mods/TestMod/testmod
Auto Spawn Models: ✓
Auto Spawn Enemies: ✓
Spawn Spacing: 5
```

**Test Specific Level:**
```
Asset Bundle Path: Builds/Mods/MyLevel/mylevel
Level To Load: Arena Boss Fight
Auto Spawn Models: ✗
Auto Spawn Enemies: ✗
```

**Test Enemy Spawning Only:**
```
Asset Bundle Path: Builds/Mods/EnemyPack/enemypack
Auto Spawn Models: ✗
Auto Spawn Enemies: ✓
Spawn Spacing: 10
```

## Manual Testing

For advanced testing scenarios, load mods programmatically.

### Basic Asset Bundle Loading

```csharp
using UnityEngine;
using AlterchaseSDK;

public class ManualModTester : MonoBehaviour
{
    public string bundlePath = "Builds/Mods/MyMod/mymod";

    void Start()
    {
        // Load the asset bundle
        AssetBundle bundle = AssetBundle.LoadFromFile(bundlePath);
        
        if (bundle == null)
        {
            Debug.LogError("Failed to load asset bundle!");
            return;
        }

        // Load the mod package
        ModPackage package = bundle.LoadAsset<ModPackage>("MyModPackage");
        
        if (package != null)
        {
            Debug.Log($"Loaded: {package.PackageName} by {package.AuthorName}");
        }

        // Don't forget to unload when done
        // bundle.Unload(false);
    }
}
```

### Spawning Specific Assets

```csharp
using UnityEngine;
using System.Linq;
using AlterchaseSDK;

public class SpawnSpecificAssets : MonoBehaviour
{
    void Start()
    {
        AssetBundle bundle = AssetBundle.LoadFromFile("Builds/Mods/MyMod/mymod");
        
        // Load all models
        ModelModAsset[] models = bundle.LoadAllAssets<ModelModAsset>();
        
        // Find specific model by name
        ModelModAsset targetModel = models.FirstOrDefault(m => m.AssetName == "Cool Prop");
        
        if (targetModel != null && targetModel.ModelPrefab != null)
        {
            GameObject instance = Instantiate(targetModel.ModelPrefab, Vector3.zero, Quaternion.identity);
            Debug.Log($"Spawned: {targetModel.AssetName}");
        }
    }
}
```

### Loading Levels

```csharp
using UnityEngine;
using UnityEngine.SceneManagement;
using System.Linq;
using AlterchaseSDK;

public class LoadModLevel : MonoBehaviour
{
    void Start()
    {
        AssetBundle bundle = AssetBundle.LoadFromFile("Builds/Mods/MyLevel/mylevel");
        
        LevelModAsset[] levels = bundle.LoadAllAssets<LevelModAsset>();
        LevelModAsset level = levels.FirstOrDefault();
        
        if (level != null && !string.IsNullOrEmpty(level.ScenePath))
        {
            SceneManager.LoadScene(level.ScenePath, LoadSceneMode.Additive);
            Debug.Log($"Loading level: {level.AssetName}");
        }
    }
}
```

## Testing Checklist

Use this checklist before publishing your mod:

### Pre-Build Testing
- [ ] All mod assets have valid references (no missing prefabs/scenes)
- [ ] Package validation passes without errors
- [ ] Asset names are clear and descriptive
- [ ] Package info (name, author, version) is correct
- [ ] Package icon is assigned (512x288 recommended)

### Asset Bundle Testing
- [ ] Asset bundle builds without errors
- [ ] Asset bundle file exists in expected location
- [ ] Bundle loads in Mod Tester window
- [ ] All assets appear in the loaded package

### Level Testing
- [ ] Level scene loads correctly
- [ ] Player spawn point is valid
- [ ] No missing textures or materials
- [ ] Lighting bakes correctly
- [ ] Performance is acceptable (check FPS)
- [ ] No console errors when loading
- [ ] Multiplayer support works (if enabled)

### Model Testing
- [ ] Model prefabs spawn correctly
- [ ] Materials and textures display properly
- [ ] Colliders are set up correctly
- [ ] Physics behaves as expected
- [ ] Scale is appropriate
- [ ] Destruction works (if enabled)
- [ ] Sound effects play correctly

### Enemy Testing
- [ ] Enemy prefabs spawn correctly
- [ ] Health system works
- [ ] AI behavior functions as intended
- [ ] Animations play correctly
- [ ] Attack detection works
- [ ] Death effects trigger properly
- [ ] Loot drops work (if configured)
- [ ] Audio plays correctly (idle, attack, damage, death)

### Performance Testing
- [ ] FPS is stable (60+ FPS recommended)
- [ ] No memory leaks (check Profiler)
- [ ] Draw calls are reasonable
- [ ] Asset bundle size is acceptable
- [ ] Loading time is reasonable

### Final Checks
- [ ] No errors in Console
- [ ] No warnings in Console (or justified)
- [ ] Tested in both Editor and Build
- [ ] Documentation/README updated
- [ ] Version number incremented (if updating)

## Common Issues

### "Failed to load asset bundle"

**Cause**: File path is incorrect or file doesn't exist

**Solution**:
- Verify the file path is correct
- Check the file exists in `Builds/Mods/[YourModName]/`
- Use forward slashes `/` in paths, not backslashes `\`
- Use absolute path if relative path fails

### "Could not find ModPackage in the asset bundle"

**Cause**: ModPackage asset was not included in the build

**Solution**:
- Ensure your ModPackage is assigned in the Mod Package Builder
- Rebuild the asset bundle
- Check that the ModPackage asset exists in your project

### "Prefab is null after loading"

**Cause**: Prefab reference was not properly serialized in the asset bundle

**Solution**:
- Check that the prefab is assigned in the ModAsset
- Ensure the prefab is in your project (not a scene object)
- Make sure the prefab is included in the asset bundle build
- Rebuild the asset bundle

### Models/Enemies spawn at wrong position

**Cause**: Spawn position calculation issue

**Solution**:
- Manually position the spawned object in the Scene
- Use `Selection.activeGameObject.transform.position` to see where it spawned
- Adjust spawn spacing in ModLoaderTestHelper
- Use manual spawning code with specific positions

### Level scene won't load

**Cause**: Scene path is invalid or scene not included in build

**Solution**:
- Check that the scene path is correct in the Level Mod Asset
- Ensure the scene is assigned in the Level Mod Asset Inspector
- Make sure the scene is included in the asset bundle
- Rebuild the asset bundle

### Missing materials/textures

**Cause**: Materials or textures not included in asset bundle

**Solution**:
- Ensure all materials are assigned to prefabs
- Check that textures are referenced by materials
- Verify shader is supported (use Standard shader if unsure)
- Include all dependencies in the asset bundle build

### Console errors in Play Mode

**Cause**: Various issues (missing scripts, broken references, etc.)

**Solution**:
- Read the error message carefully
- Check for missing script components
- Verify all required components are on prefabs
- Test the prefab directly in the scene before building
- Check for namespace conflicts

### Performance issues (low FPS)

**Cause**: High polygon count, too many objects, or unoptimized assets

**Solution**:
- Reduce polygon count on models
- Use LOD (Level of Detail) groups
- Optimize textures (reduce resolution, use compression)
- Limit number of spawned objects
- Use Unity Profiler to identify bottlenecks
- Enable occlusion culling for levels

### Asset bundle file is too large

**Cause**: Uncompressed textures, high-poly models, or unoptimized assets

**Solution**:
- Compress textures in Import Settings
- Reduce texture resolution where possible
- Optimize model polygon counts
- Use appropriate audio compression
- Consider splitting into multiple smaller mods

## Advanced Testing Tips

### Using Unity Profiler

1. Open Window > Analysis > Profiler
2. Enter Play Mode with your mod loaded
3. Check:
   - CPU Usage (should stay below 16ms for 60 FPS)
   - Memory allocation
   - Draw calls (fewer is better)
   - Physics performance

### Frame Debugger

1. Open Window > Analysis > Frame Debugger
2. Enter Play Mode
3. Click "Enable" to capture a frame
4. Inspect draw calls and rendering order
5. Identify performance bottlenecks

### Memory Profiler

1. Open Window > Analysis > Memory Profiler
2. Capture a snapshot after loading your mod
3. Check for memory leaks
4. Verify asset bundle memory usage
5. Compare before/after loading

### Build Testing

Always test your mod in a standalone build, not just in the Editor:

1. Build a development build of Alterchase
2. Place your mod in the expected location
3. Run the build and load your mod
4. Check for platform-specific issues

## Need Help?

If you encounter issues not covered in this guide:

- Check the [README.md](README.md) for general documentation
- Review the [QUICKSTART.md](QUICKSTART.md) for setup steps
- Visit the Alterchase Discord for community support
- Check the Unity Console for specific error messages

---

**Happy Testing!** Remember: thorough testing leads to better mods and happier players.
