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

cd E:\Projects
python convert_skills_fixed.py --ids 1,2,3,4,5

Option 2: Convert a Range of Skills

python convert_skills_fixed.py --range 1-100

Or multiple ranges:

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:

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

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

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)

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

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:

   cd E:\Projects
   python convert_skills_fixed.py --stubs "path\to\stubs1.cpp"
   

2. Convert additional skill sets:

   python convert_skills_fixed.py --stubs "path\to\stubs2.cpp"
   python convert_skills_fixed.py --stubs "path\to\stubs3.cpp"
   

3. Test specific skills:

   python convert_skills_fixed.py --ids 1,2,3
   

4. Batch convert ranges:

   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