test/Documentation/PYTHON_TOOL_USAGE.md

Python Skill Conversion Tool - Command Line Usage

Quick Start

The Python tool is located at: e:\Projects\convert_skills.py

Prerequisites

• Python 3.x installed
• Access to both C++ source and C# target directories
• PowerShell or Command Prompt on Windows

Command Syntax

PowerShell (Recommended for Windows)

# Navigate to the project directory first
cd e:\Projects

# Then run the conversion command
python convert_skills.py [OPTIONS]

Important: PowerShell uses ; (semicolon) as command separator, NOT &&

Command Prompt

cd e:\Projects && python convert_skills.py [OPTIONS]

Usage Examples

1. Convert a Single Skill

cd e:\Projects
python convert_skills.py 390

This converts only skill390.h to skill390.cs

2. Convert Multiple Specific Skills

cd e:\Projects
python convert_skills.py 390,391,392,393

This converts skills 390, 391, 392, and 393 (comma-separated, no spaces)

3. Convert a Range of Skills

cd e:\Projects
python convert_skills.py 390,391,392,393,394,395,396,397,398,399

For ranges, you need to list them out with commas.

4. Convert All Remaining Skills

cd e:\Projects
python convert_skills.py --all

This converts all skill ranges defined in the tool:

• 390-439 (50 skills)
• 440-491 (52 skills)
• 896-900 (5 skills)
• 923-924 (2 skills)
• And all other ranges listed in SKILL_CONVERSION_INSTRUCTIONS.md

What the Tool Does

When you run the conversion, the tool will:

1. ✅ Read the C++ skill file from: perfect-world-source/perfect-world-source/CElement/CElementSkill/skillNN.h
2. ✅ Parse all classes, methods, fields, and states
3. ✅ Convert C++ syntax to C# syntax
4. ✅ Apply all type mappings (bool, float, arrays, etc.)
5. ✅ Generate the C# file at: perfect-world-unity/Assets/PerfectWorld/Scripts/Skills/skillNN.cs
6. ✅ Update SkillStubs1.cs to uncomment the skill stub registration

Expected Output

Successful Conversion

Converting skill 390...
  [OK] Created e:\Projects\perfect-world-unity\Assets\PerfectWorld\Scripts\Skills\skill390.cs
[OK] Updated SkillStubs1.cs with 1 skills

============================================================
Conversion complete!
  [OK] Successfully converted: 1 skills
============================================================

Failed Conversion

Converting skill 999...
Warning: e:\Projects\perfect-world-source\perfect-world-source\CElement\CElementSkill\skill999.h does not exist

============================================================
Conversion complete!
  [OK] Successfully converted: 0 skills
  [FAIL] Failed: 1 skills: [999]
============================================================

Common Issues & Solutions

Issue 1: "python is not recognized"

Problem: Python is not in your PATH

Solution:

# Use full path to Python
C:\Python39\python.exe convert_skills.py 390

Or add Python to your PATH environment variable.

Issue 2: "No such file or directory"

Problem: Not in the correct directory

Solution:

# Always navigate to e:\Projects first
cd e:\Projects
python convert_skills.py 390

Issue 3: "The token '&&' is not a valid statement separator"

Problem: Using bash syntax in PowerShell

Solution:

# Use semicolon in PowerShell
cd e:\Projects ; python convert_skills.py 390

# OR run commands separately
cd e:\Projects
python convert_skills.py 390

Issue 4: File encoding errors

Problem: Chinese characters not displaying correctly

Solution: The tool uses UTF-8 encoding with error handling. If you see encoding issues, check that:

• Your terminal supports UTF-8
• The source C++ files are readable
• The generated C# files can be opened in your IDE

Verification Steps

After running the conversion, verify:

1. Check the generated file exists:

   ls perfect-world-unity\Assets\PerfectWorld\Scripts\Skills\skill390.cs
   

2. Check for linter errors in your IDE:

   • Open the generated skillNN.cs file
   • Look for red squiggly lines or errors
   • The tool should generate error-free code

3. Verify SkillStubs1.cs was updated:

   # Search for the uncommented line
   Select-String -Path "perfect-world-unity\Assets\PerfectWorld\Scripts\Skills\SkillStubs1.cs" -Pattern "Skill390Stub"
   

Batch Conversion Strategy

For converting many skills efficiently:

Strategy 1: Small Batches (Recommended)

Convert in small batches of 5-10 skills, verify each batch:

cd e:\Projects

# Batch 1
python convert_skills.py 390,391,392,393,394
# Check for errors in IDE

# Batch 2
python convert_skills.py 395,396,397,398,399
# Check for errors in IDE

# Continue...

Strategy 2: Full Range

Convert an entire range at once (riskier):

cd e:\Projects
python convert_skills.py --all

Then check all files for errors.

Advanced Usage

Modifying the Tool

If you need to customize conversion behavior, edit convert_skills.py:

1. Change source/target directories: Lines 507-508
2. Add new skill ranges: Lines 513-534
3. Modify conversion rules: Various methods in the SkillConverter class

Testing Changes

After modifying the tool, test on a single skill first:

cd e:\Projects
python convert_skills.py 390

Compare the output with the expected pattern from existing converted skills.

File Paths Reference

Item	Path
Python Tool	e:\Projects\convert_skills.py
C++ Source	e:\Projects\perfect-world-source\perfect-world-source\CElement\CElementSkill\
C# Target	e:\Projects\perfect-world-unity\Assets\PerfectWorld\Scripts\Skills\
Stub Registry	e:\Projects\perfect-world-unity\Assets\PerfectWorld\Scripts\Skills\SkillStubs1.cs

Getting Help

If the tool produces incorrect output:

1. Check SKILL_CONVERSION_INSTRUCTIONS.md for the correct pattern
2. Check PYTHON_TOOL_STATUS.md for known issues
3. Compare output with existing converted skills (skill65.cs, skill374.cs)
4. Manually fix the generated file if needed
5. Report the issue so the tool can be improved

Summary of Commands

# Single skill
cd e:\Projects
python convert_skills.py 390

# Multiple skills
cd e:\Projects
python convert_skills.py 390,391,392

# All skills
cd e:\Projects
python convert_skills.py --all

Remember: Always navigate to e:\Projects first, then run the Python command!