test/Documentation/HOW_TO_USE_CONVERTER.md

How to Use convert_skills_fixed.py with stubs2.cpp

Overview

The convert_skills_fixed.py script converts C++ skill header files (skill*.h) to C# Unity skill files. When used with --stubs, it automatically extracts skill IDs from the stubs file and converts all those skills.

Basic Usage with stubs2.cpp

Step 1: Basic Command

python convert_skills_fixed.py --stubs "perfect-world-source/perfect-world-source/CElement/CElementSkill/stubs2.cpp"

This will:

• Extract all skill IDs from stubs2.cpp (before the #ifdef _SKILL_SERVER line)
• Convert each skill from C++ to C#
• Create a SkillStubs2 subfolder in your output directory
• Generate individual skill{id}.cs files
• Generate a SkillStubs2.cs file with all stub declarations

Step 2: Full Command with All Options

python convert_skills_fixed.py ^
  --cpp "e:\Projects\perfect-world-source\perfect-world-source\CElement\CElementSkill" ^
  --cs "e:\Projects\perfect-world-unity\Assets\PerfectWorld\Scripts\Skills" ^
  --gfx "C:\Users\BrewPC\Downloads\gfx" ^
  --stubs "perfect-world-source/perfect-world-source/CElement/CElementSkill/stubs2.cpp"

Step 3: Using Absolute Paths (Recommended)

python convert_skills_fixed.py ^
  --cpp "E:\Projects\perfect-world-source\perfect-world-source\CElement\CElementSkill" ^
  --cs "E:\Projects\perfect-world-unity\Assets\PerfectWorld\Scripts\Skills" ^
  --gfx "C:\Users\BrewPC\Downloads\gfx" ^
  --stubs "E:\Projects\perfect-world-source\perfect-world-source\CElement\CElementSkill\stubs2.cpp"

Parameters Explained

Parameter	Description	Default
--cpp	Path to C++ source directory containing skill*.h files	e:\Projects\perfect-world-source\perfect-world-source\CElement\CElementSkill
--cs	Path to C# target directory (Unity project)	e:\Projects\perfect-world-unity\Assets\PerfectWorld\Scripts\Skills
--gfx	Path to GFX directory containing .sgc files for effect paths	C:\Users\BrewPC\Downloads\gfx
--stubs	Path to stubs file (e.g., stubs2.cpp) to extract skill IDs	(none)
--ids	Comma-separated skill IDs (e.g., 1,2,3)	(none)
--range	Range of skills (e.g., 1-100 or 1-50,100-150)	(none)
--all	Convert built-in skill ranges	(false)

What Happens When You Run It

1. Extracts Skill IDs: Reads stubs2.cpp and finds all Skill{ID}Stub declarations before #ifdef _SKILL_SERVER
2. Creates Output Structure:
   • Creates Skills/SkillStubs2/ subfolder (if it doesn't exist)
   • Each skill gets its own skill{id}.cs file
3. Converts Each Skill:
   • Parses the C++ skill{id}.h file
   • Extracts fields, methods, states, arrays, etc.
   • Optionally reads .sgc files for GFX effect paths
   • Generates C# code following the established pattern
4. Generates SkillStubs2.cs: Creates a file with all stub declarations
5. Updates SkillStubs1.cs: Uncomments the converted skills in the main stubs file

Output Structure

After conversion, you'll have:

Skills/
├── SkillStubs2/
│   ├── skill2546.cs
│   ├── skill1100.cs
│   ├── skill1101.cs
│   ├── ...
│   └── SkillStubs2.cs
└── SkillStubs1.cs (updated)

Example: Converting stubs2.cpp

# Navigate to your project directory
cd E:\Projects

# Run the converter
python convert_skills_fixed.py --stubs "perfect-world-source/perfect-world-source/CElement/CElementSkill/stubs2.cpp"

Troubleshooting

Issue: "Warning: skill{id}.h does not exist"

• Solution: Make sure the --cpp path points to the correct directory containing the skill header files

Issue: "Warning: SkillStubs1.cs does not exist"

• Solution: This is normal if you're creating a new stubs file. The script will create SkillStubs2.cs instead.

Issue: GFX paths not extracted

• Solution: Ensure --gfx points to the directory containing the sgc/ subfolder with .sgc files

Alternative: Convert Specific Skills

If you only want to convert specific skills from stubs2.cpp:

# Convert only skills 2546, 1100, and 1101
python convert_skills_fixed.py --ids "2546,1100,1101"

Alternative: Convert a Range

# Convert skills 1100-1259
python convert_skills_fixed.py --range "1100-1259"

Notes

• The script automatically handles encoding (GB2312/GBK/GB18030/UTF-8)
• GFX paths are extracted from .sgc files if the --gfx directory is provided
• The script creates proper C# namespaces and follows Unity conventions
• Server-side code is wrapped in #if SKILL_SERVER directives
• Client-side code is wrapped in #if SKILL_CLIENT directives