test/Documentation/convert_skills_HOW_TO_USE.md

# Perfect World Skill Converter - How to Use

## Overview
This Python tool converts C++ skill files (`skill*.h`) to C# format for Unity.

## Prerequisites
- Python 3.6 or higher installed
- C++ skill source files (from `perfect-world-source`)
- Unity project with Skills folder structure

## Directory Structure Expected
```
E:\Projects\
├── perfect-world-source\
│   └── perfect-world-source\
│       └── CElement\
│           └── CElementSkill\          # C++ skill*.h files here
│               ├── skill1.h
│               ├── skill2.h
│               └── ...
│           └── stubs1.cpp              # Optional: skill list file
└── perfect-world-unity\
    └── Assets\
        └── PerfectWorld\
            └── Scripts\
                └── Skills\              # C# output goes here
                    ├── SkillStubs1\     # Per-stubs subfolder
                    │   ├── skill1.cs
                    │   ├── skill2.cs
                    │   └── SkillStubs1.cs
                    └── ...
```

## How to Run

### Option 1: Convert Specific Skill IDs
```bash
cd E:\Projects
python convert_skills_fixed.py --ids 1,2,3,4,5
```

### Option 2: Convert a Range of Skills
```bash
python convert_skills_fixed.py --range 1-100
```

Or multiple ranges:
```bash
python convert_skills_fixed.py --range 1-50,100-150
```

### Option 3: Convert from stubs file (RECOMMENDED)
This automatically extracts skill IDs from a `stubs1.cpp` file and creates organized subfolders:

```bash
python convert_skills_fixed.py --stubs "E:\Projects\perfect-world-source\perfect-world-source\CElement\CElementSkill\stubs1.cpp"
```

This will:
- Extract all skill IDs from `stubs1.cpp`
- Create a `SkillStubs1` subfolder
- Generate all skill files in that subfolder
- Generate a `SkillStubs1.cs` file with all skill declarations

### Option 4: Convert All Built-in Ranges
```bash
python convert_skills_fixed.py --all
```

## Command Line Arguments

| Argument | Description | Example |
|----------|-------------|---------|
| `--cpp` | C++ source directory | `--cpp "E:\Projects\perfect-world-source\...\CElementSkill"` |
| `--cs` | C# target directory | `--cs "E:\Projects\perfect-world-unity\...\Skills"` |
| `--ids` | Comma-separated skill IDs | `--ids 1,2,3,10,25` |
| `--range` | Range of skills | `--range 1-100` or `--range 1-50,100-150` |
| `--stubs` | Path to stubs.cpp file | `--stubs "path\to\stubs1.cpp"` |
| `--all` | Convert all built-in ranges | `--all` |

## Default Paths
If you don't specify `--cpp` or `--cs`, these defaults are used:
- **C++ Source:** `E:\Projects\perfect-world-source\perfect-world-source\CElement\CElementSkill`
- **C# Target:** `E:\Projects\perfect-world-unity\Assets\PerfectWorld\Scripts\Skills`

## Examples

### Example 1: Convert skills 1-10 with custom paths
```bash
python convert_skills_fixed.py ^
    --cpp "D:\PWSource\CElementSkill" ^
    --cs "D:\Unity\PWUnity\Scripts\Skills" ^
    --range 1-10
```

### Example 2: Convert from stubs file (typical workflow)
```bash
cd E:\Projects
python convert_skills_fixed.py --stubs "E:\Projects\perfect-world-source\perfect-world-source\CElement\CElementSkill\stubs1.cpp"
```

### Example 3: Quick test with a few skills
```bash
python convert_skills_fixed.py --ids 1,10,53
```

## What the Tool Does

1. **Reads C++ skill files** (`skill*.h`)
2. **Parses** constructor, methods, states, and fields
3. **Converts** to C# syntax:
   - Removes pointer syntax (`->` becomes `.`)
   - Converts types (float casts, etc.)
   - Adds `override` keywords where needed
   - Handles Chinese characters properly
   - Uses `GPDataTypeHelper.ReplacePercentD` for GetIntroduction
4. **Generates** C# files in Unity project
5. **Updates** skill stub registration files

## Output

For each converted skill, you'll get:
```
Converting skill 1...
  [OK] Created E:\Projects\perfect-world-unity\Assets\PerfectWorld\Scripts\Skills\SkillStubs1\skill1.cs
Converting skill 2...
  [OK] Created E:\Projects\perfect-world-unity\Assets\PerfectWorld\Scripts\Skills\SkillStubs1\skill2.cs
...
[OK] Generated E:\Projects\perfect-world-unity\Assets\PerfectWorld\Scripts\Skills\SkillStubs1\SkillStubs1.cs
[OK] Updated SkillStubs1.cs with 50 skills

============================================================
Conversion complete!
  [OK] Successfully converted: 50 skills
============================================================
```

## Troubleshooting

### "Warning: skill{X}.h does not exist"
- The C++ source file is missing
- Check your `--cpp` path
- Verify the skill ID exists in the C++ codebase

### "Cannot find SkillStubs1.cs"
- Normal if converting for the first time
- The tool will generate it when using `--stubs` option

### Encoding Errors
- The tool handles GB2312/GBK/GB18030 automatically
- If you still see errors, the source file might be corrupted

### Permission Denied
- Make sure Visual Studio/Unity doesn't have the files locked
- Run command prompt as Administrator if needed

## Recommended Workflow

1. **First time setup:**
   ```bash
   cd E:\Projects
   python convert_skills_fixed.py --stubs "path\to\stubs1.cpp"
   ```

2. **Convert additional skill sets:**
   ```bash
   python convert_skills_fixed.py --stubs "path\to\stubs2.cpp"
   python convert_skills_fixed.py --stubs "path\to\stubs3.cpp"
   ```

3. **Test specific skills:**
   ```bash
   python convert_skills_fixed.py --ids 1,2,3
   ```

4. **Batch convert ranges:**
   ```bash
   python convert_skills_fixed.py --range 1-1000
   ```

## Tips

- Always backup your Unity project before mass conversion
- The tool is safe to run multiple times (it overwrites)
- Use `--stubs` option for organized folder structure
- Check the generated C# files for any syntax errors
- The tool preserves Chinese comments and names