Bevy Engine Migration Tool

Automated migration tool for Bevy Engine projects between versions 0.12, 0.13, 0.14, 0.15, 0.16, 0.17, 0.18, and 0.19.

📋 Description

This tool automates the migration process for projects using the Bevy game engine between different versions. It supports migrations from version 0.12 to 0.19 using a modular architecture and AST code analysis.

Key Features

🔄 Automatic migration between Bevy versions 0.12 → 0.13 → 0.14 → 0.15 → 0.16 → 0.17 → 0.18 → 0.19
🧩 Modular architecture with separate modules for each version
🔍 AST analysis using ast-grep for precise code transformations
📁 Smart file management with automatic backups
🎯 Automatic version detection of your project
🧠 Complex logic support via Python callbacks and inline YAML rules
🛡️ Safe dry-run mode for previewing changes
📊 Detailed reporting of the migration process

Supported Migrations

0.12 → 0.13: WorldQuery split into QueryData/QueryFilter, Input renamed to ButtonInput, TextureAtlas rework, rendering and UI changes
0.13 → 0.14: Complete Color overhaul (Srgba/LinearRgba), AnimationGraph, SubApp split, Dir2/Dir3, massive rendering changes, winit 0.30, wgpu 0.20
0.15 → 0.16: Plugin system updates, system registration, entity creation improvements (72 transformations)
0.16 → 0.17: Required components system, observer updates, input system changes (130+ transformations in 3 parts)
0.17 → 0.18: Rendering improvements, UI system, window system, new features (105+ transformations)
0.18 → 0.19 (Part 1): Messages API, observer renames, reflect reorganization, and core renames (Manual target only)

🛠️ Installation

Installing the Package

# Clone the repository
git clone <repository-url>
cd bevy-migration-tool

# Install the package in editable mode (recommend for development)
pip install -e .

# Or install normally
pip install .

This will install the bevymigrate package and the bevymigrate CLI command.

🚀 Usage

Basic Usage

After installation, you can run the tool directly using the bevymigrate command:

# Run migration on your project (0.18 is default target)
bevymigrate /path/to/bevy/project

# Migrate to Bevy 0.19 (Part 1) explicitly
bevymigrate /path/to/bevy/project --target-version 0.19-part1

# Run a dry-run to see what would change
bevymigrate /path/to/bevy/project --dry-run

# Migrate project to the latest supported version (0.18)
bevymigrate /path/to/your/bevy/project

# Migrate to a specific version
bevymigrate /path/to/your/bevy/project --target-version 0.17

# Preview changes without modifying files
bevymigrate /path/to/your/bevy/project --dry-run

# Verbose output with debug information
bevymigrate /path/to/your/bevy/project --verbose

Advanced Options

# Migrate with custom backup directory
bevymigrate /path/to/project --backup-dir ./my_backups

# Force migration (if version is not detected automatically)
bevymigrate /path/to/project --force

# Exclude specific files or directories
bevymigrate /path/to/project --exclude "target/**" "*.bak" "custom_dir/**"

# Combined example
bevymigrate ./my_bevy_game --target-version 0.17 --dry-run --verbose --backup-dir ./backups

Command Examples

# Example 1: Migrate a simple project
bevymigrate ./my_game

# Example 2: Preview migration with verbose output
bevymigrate ./my_game --dry-run --verbose

# Example 3: Step-by-step migration to version 0.16
bevymigrate ./my_game --target-version 0.16

# Example 4: Migration with custom settings
bevymigrate ./my_game --backup-dir ./project_backups --exclude "assets/**" --verbose

📖 How to Use

Step-by-Step Guide

Prepare your project

# Make sure your project is under version control
cd /path/to/your/bevy/project
git add .
git commit -m "Before Bevy migration"

Check current version

# The tool will auto-detect the version, but you can check Cargo.toml
cat Cargo.toml | grep bevy

Run migration in preview mode
```
bevymigrate . --dry-run --verbose
```
Execute migration
```
bevymigrate .
```

Verify results

# Check that the project compiles
cargo check

# Run tests
cargo test

# Run the project
cargo run

Command Line Parameters

Parameter	Description	Example
`project_path`	Path to Bevy project (required)	`./my_game`
`--target-version`	Target version for migration	`--target-version 0.17`
`--dry-run`	Preview mode	`--dry-run`
`--backup-dir`	Directory for backups	`--backup-dir ./backups`
`--verbose, -v`	Verbose output	`--verbose`
`--force`	Force migration	`--force`
`--exclude`	Exclude files/directories	`--exclude "target/*" ".tmp"`

🏗️ Project Architecture

src/
└── bevymigrate/
    ├── __init__.py
    ├── main.py                     # Application entry point
    ├── core/                       # Core components
    │   ├── migration_engine.py     # Migration engine
    │   ├── ast_processor.py        # AST processor
    │   └── file_manager.py         # File manager
    ├── migrations/                 # Migration modules
    │   ├── base_migration.py       # Base migration class
    │   ├── v0_12_to_0_13.py        # Migration 0.12 → 0.13
    │   ├── v0_13_to_0_14.py        # Migration 0.13 → 0.14
    │   ├── v0_14_to_0_15_part1.py  # Migration 0.14 → 0.15 Part 1
    │   ├── v0_14_to_0_15_part2.py  # Migration 0.14 → 0.15 Part 2
    │   ├── v0_15_to_0_16.py        # Migration 0.15 → 0.16
    │   ├── v0_16_to_0_17_part1.py  # Migration 0.16 → 0.17 Part 1
    │   ├── v0_16_to_0_17_part2.py  # Migration 0.16 → 0.17 Part 2
    │   ├── v0_16_to_0_17_part3.py  # Migration 0.16 → 0.17 Part 3
    │   ├── v0_17_to_0_18.py        # Migration 0.17 → 0.18
    │   └── v0_18_to_0_19_part1.py  # Migration 0.18 → 0.19 Part 1
    └── utils/                      # Utilities
        └── version_detector.py     # Version detection

Core Components

MigrationEngine: Coordinates the migration process
ASTProcessor: Performs code transformations using AST
FileManager: Manages file operations and backups
VersionDetector: Automatically detects Bevy version in the project
BaseMigration: Base class for all migration modules

📊 Migration Statistics

Migration	Transformations	Parts	Breaking Changes
0.12→0.13	~40	1	40+
0.13→0.14	~60	1	60+
0.14→0.15	~80	2	80+
0.15→0.16	72	1	70+
0.16→0.17	130+	3	150+
0.17→0.18	105+	1	80+
0.18→0.19	50+	1	50+
Total	535+	10	530+

🔧 Configuration

The tool uses a centralized configuration system in src/config/migration_rules.py. You can customize:

Transformation rules for each version
File patterns to process
Exclusions and filters
Rule priority levels

Example Custom Rule

# Add a custom migration rule
rule = MigrationRule(
    name="custom_transformation",
    description="Custom transformation",
    pattern=r"old_pattern",
    replacement="new_pattern",
    file_patterns=["**/*.rs"],
    priority=100
)

🛡️ Safety

The tool automatically creates backups before making changes:

Automatic backup of all modified files
Dry-run mode for safe preview
Validation of project structure before migration
Rollback in case of errors

Backup Location

By default, backups are saved to:

your_project/
└── migration_backup/
    └── backup_YYYYMMDD_HHMMSS/
        ├── Cargo.toml
        ├── src/
        └── ...

📊 Reporting

The tool provides detailed information about the migration process:

Number of processed files
Applied transformations
Warnings and errors
Recommendations for manual review

Example Output

2024-02-04 08:07:56 - INFO - Detected Bevy version: 0.15
2024-02-04 08:07:57 - INFO - Starting migration from 0.15 to 0.18
2024-02-04 08:07:58 - INFO - Migration path: 0.15 -> 0.16 -> 0.17 -> 0.18
2024-02-04 08:08:00 - INFO - Files processed: 25
2024-02-04 08:08:00 - INFO - Files modified: 18
2024-02-04 08:08:00 - INFO - Transformations applied: 47
2024-02-04 08:08:00 - INFO - Migration completed successfully!

🔍 Troubleshooting

Common Issues

ast-grep-py not found
```
pip install -r requirements.txt
```

Cannot detect Bevy version

# Use the --force flag
python src/main.py . --force

Compilation errors after migration
- Check files requiring manual review
- Refer to Bevy documentation for the specific version
- Restore from backup if needed

Logging

For detailed debug information:

python src/main.py . --verbose

Logs include:

Detected code patterns
Applied transformations
Warnings about potential issues
File processing statistics

🧠 Complex Migrations

For transformations that require more than simple pattern replacement, the tool provides two powerful mechanisms: Python callbacks and inline YAML rules. These are applied directly without creating temporary files on disk.

1. Python Callbacks

Useful for conditional replacements, dynamic string manipulation, or context-aware transformations.

def input_callback(vars, file_path):
    # vars contains captured ast-grep variables (e.g., $T)
    t_type = vars.get("T", "unknown")
    return f"Res<ButtonInput<{t_type}>>"

# In your migration class:
transformations.append(self.create_transformation(
    pattern="Res<Input<$T>>",
    replacement="", # Ignored when callback is present
    description="Complex replacement using Python",
    callback=input_callback
))

2. Inline YAML Rules

Allows using the full power of ast-grep YAML configuration directly.

yaml_rule = """
id: custom-check
language: rust
rule:
  pattern: foo($A)
  inside:
    kind: function_item
    has:
      field: name
      pattern: main
fix: bar($A)
"""

transformations.append(self.create_transformation(
    pattern="", # pattern is ignored when rule_yaml is present
    replacement="",
    description="Advanced YAML rule",
    rule_yaml=yaml_rule
))

🤝 Contributing

Adding a New Migration

Create a new file in src/migrations/
Inherit from BaseMigration
Implement required methods
Register the migration in MigrationEngine

Example Migration Module

from migrations.base_migration import BaseMigration
from core.ast_processor import ASTTransformation

class Migration_0_18_to_0_19(BaseMigration):
    @property
    def from_version(self) -> str:
        return "0.18"
    
    @property
    def to_version(self) -> str:
        return "0.19"
    
    def get_transformations(self) -> List[ASTTransformation]:
        return [
            self.create_transformation(
                pattern="old_pattern",
                replacement="new_pattern",
                description="Transformation description"
            )
        ]

📝 License

This project is licensed under the MIT License. See the LICENSE file for details.

🆘 Support

If you encounter issues or have questions:

Check the "Troubleshooting" section
Create an issue in the project repository
Include logs from running with the --verbose flag

📚 Additional Resources

Note: Always create backups of your projects before running migrations. While the tool creates automatic backups, extra precaution never hurts.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bevy Engine Migration Tool

📋 Description

Key Features

Supported Migrations

🛠️ Installation

Installing the Package

🚀 Usage

Basic Usage

Advanced Options

Command Examples

📖 How to Use

Step-by-Step Guide

Command Line Parameters

🏗️ Project Architecture

Core Components

📊 Migration Statistics

🔧 Configuration

Example Custom Rule

🛡️ Safety

Backup Location

📊 Reporting

Example Output

🔍 Troubleshooting

Common Issues

Logging

🧠 Complex Migrations

1. Python Callbacks

2. Inline YAML Rules

🤝 Contributing

Adding a New Migration

Example Migration Module

📝 License

🆘 Support

📚 Additional Resources

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Bevy Engine Migration Tool

📋 Description

Key Features

Supported Migrations

🛠️ Installation

Installing the Package

🚀 Usage

Basic Usage

Advanced Options

Command Examples

📖 How to Use

Step-by-Step Guide

Command Line Parameters

🏗️ Project Architecture

Core Components

📊 Migration Statistics

🔧 Configuration

Example Custom Rule

🛡️ Safety

Backup Location

📊 Reporting

Example Output

🔍 Troubleshooting

Common Issues

Logging

🧠 Complex Migrations

1. Python Callbacks

2. Inline YAML Rules

🤝 Contributing

Adding a New Migration

Example Migration Module

📝 License

🆘 Support

📚 Additional Resources