mc-creative-clone 0.1.0__py3-none-any.whl

mc_creative_clone/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("mc-creative-clone")

mc_creative_clone/main.py

@@ -0,0 +1,412 @@
+import argparse
+from datetime import date
+import logging
+from os import scandir
+from pathlib import Path
+import re
+from shutil import copytree, move, rmtree, which
+from subprocess import CalledProcessError, run
+from sys import exit, platform
+
+import nbtlib
+import questionary
+from rich.console import Console
+from rich.logging import RichHandler
+
+logging.basicConfig(
+    level="WARNING",
+    format="%(message)s",
+    datefmt="[%X]",
+    handlers=[RichHandler(rich_tracebacks=True)],
+)
+log = logging.getLogger("mc-creative-clone")
+console = Console()
+
+
+def get_prism_path() -> Path:
+    """Detects the OS and returns the PrismLauncher data directory.
+
+    Returns:
+        Path: The path to the PrismLauncher data directory.
+
+    Raises:
+        ValueError: If the current platform is not supported.
+        FileNotFoundError: If the PrismLauncher data directory does not exist.
+    """
+    # Detect OS
+    if platform == "linux" or platform == "linux2":
+        # OS is Linux
+        prism_path = Path("~/.local/share/PrismLauncher").expanduser()
+    elif platform == "darwin":
+        # OS is MacOS
+        prism_path = Path("~/Library/Application Support/PrismLauncher").expanduser()
+    elif platform == "win32":
+        # OS is Windows
+        prism_path = Path("~\\AppData\\Roaming\\PrismLauncher").expanduser()
+    else:
+        raise ValueError(f"{platform} is invalid")
+
+    if prism_path.exists():
+        return prism_path
+    raise FileNotFoundError(f"{prism_path} does not exist")
+
+
+def get_prism_instance(prism_path: Path, instance_name: str | None = None) -> Path:
+    """Finds and returns the path of a PrismLauncher instance.
+
+    If multiple instances are found, the user is prompted to select one.
+
+    Args:
+        prism_path: The path to the PrismLauncher data directory.
+        instance_name: The name of the instance to select. If None, prompts interactively.
+
+    Returns:
+        Path: The path to the selected PrismLauncher instance.
+
+    Raises:
+        FileNotFoundError: If the instances directory or no instances are found.
+    """
+    instances_path = prism_path / "instances"
+
+    if not instances_path.is_dir():
+        raise FileNotFoundError(f"{instances_path} is not a valid directory")
+
+    instances_list = [entry for entry in scandir(instances_path) if entry.is_dir()]
+
+    if instance_name is not None:
+        match = next((i for i in instances_list if i.name == instance_name), None)
+        if match is None:
+            raise FileNotFoundError(f"Could not find instance '{instance_name}'.")
+        return Path(match.path)
+
+    if len(instances_list) == 0:
+        raise FileNotFoundError("Could not find any instances.")
+
+    if len(instances_list) == 1:
+        return Path(instances_list[0].path)
+    choices = [
+        questionary.Choice(title=instance.name, value=instance.path)
+        for instance in instances_list
+    ]
+    selection = questionary.select("Choose an instance", choices=choices).ask()
+    if selection is None:
+        raise KeyboardInterrupt("User cancelled selection.")
+    return Path(selection)
+
+
+def parse_args() -> argparse.Namespace:
+    """Parses and returns command line arguments.
+
+    Returns:
+        argparse.Namespace: The parsed command line arguments.
+    """
+    parser = argparse.ArgumentParser(
+        prog="mc-creative-clone",
+        description="Copies a minecraft world and converts it to a creative mode world.",
+        epilog="If no options are provided, the script will run interactively.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "--prism-path",
+        "-p",
+        default=None,
+        metavar="PATH",
+        help="Path to the PrismLauncher data directory. "
+        "Defaults to the standard OS path if not specified.",
+    )
+    parser.add_argument(
+        "--instance",
+        "-i",
+        default=None,
+        metavar="INSTANCE",
+        help="Name of the PrismLauncher instance to use."
+        "Prompted interactively if not specified.",
+    )
+    parser.add_argument(
+        "--world",
+        "-w",
+        default=None,
+        metavar="WORLD",
+        help="Name of the world to copy. Prompted interactively if not specified.",
+    )
+    parser.add_argument(
+        "--force",
+        "-f",
+        action="store_true",
+        help="Overwrite the destination world if it already exists, without prompting.",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Enable verbose (debug) logging output.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview actions without making any changes to the filesystem.",
+    )
+
+    args = parser.parse_args()
+
+    if args.prism_path is None:
+        args.prism_path = get_prism_path()
+
+    return args
+
+
+def get_minecraft_folder(instance_path: Path) -> Path:
+    """Finds and returns the .minecraft directory for a given instance.
+
+    Args:
+        instance_path: The path of the PrismLauncher instance.
+
+    Returns:
+        Path: The path to the .minecraft directory.
+
+    Raises:
+        FileNotFoundError: If the .minecraft directory cannot be found.
+    """
+    instance_minecraft_dir = instance_path / "minecraft"
+    if not instance_minecraft_dir.is_dir():
+        instance_minecraft_dir = instance_path / ".minecraft"
+    if not instance_minecraft_dir.is_dir():
+        raise FileNotFoundError(
+            f"Could not find minecraft directory in {instance_path}"
+        )
+    return instance_minecraft_dir
+
+
+def get_save_folder(minecraft_folder_path: Path, world_name: str | None = None) -> Path:
+    """Finds and returns the path of a Minecraft world save folder.
+
+    If multiple worlds are found, the user is prompted to select one.
+
+    Args:
+        minecraft_folder_path: The path of the PrismLauncher instance .minecraft folder.
+        world_name: The name of the world to select. If None, prompts interactively.
+
+    Returns:
+        Path: The path to the selected world save folder.
+
+    Raises:
+        FileNotFoundError: If the saves directory or no save folders are found.
+    """
+    instance_save_path = minecraft_folder_path / "saves"
+    if not instance_save_path.is_dir():
+        raise FileNotFoundError(f"Could not find saves path in {minecraft_folder_path}")
+
+    save_folders = [entry for entry in scandir(instance_save_path) if entry.is_dir()]
+
+    if world_name is not None:
+        match = next((w for w in save_folders if w.name == world_name), None)
+        if match is None:
+            raise FileNotFoundError(f"Could not find world '{world_name}'.")
+        return Path(match.path)
+
+    if len(save_folders) == 0:
+        raise FileNotFoundError(
+            f"Could not find any save folders in {instance_save_path}."
+        )
+
+    if len(save_folders) == 1:
+        return Path(save_folders[0].path)
+    choices = [
+        questionary.Choice(title=world.name, value=world.path) for world in save_folders
+    ]
+    selection = questionary.select("Choose a world to copy", choices=choices).ask()
+    if selection is None:
+        raise KeyboardInterrupt("User cancelled selection.")
+    return Path(selection)
+
+
+def get_level_dat(world_path: Path) -> Path:
+    """Finds and returns the path of a world's level.dat file.
+
+    Args:
+        world_path: The path to the world save folder.
+
+    Returns:
+        Path: The path to the level.dat file.
+
+    Raises:
+        FileNotFoundError: If the level.dat file does not exist.
+    """
+    level_dat_path = world_path / "level.dat"
+
+    if not level_dat_path.is_file():
+        raise FileNotFoundError(f"{level_dat_path} is not a valid filepath.")
+
+    return level_dat_path
+
+
+def get_creative_world_path(world_path: Path) -> Path:
+    """Generates the path for the creative backup world.
+
+    Appends '_creative' and the current date to the original world path.
+
+    Args:
+        world_path: The path to the original world save folder.
+
+    Returns:
+        Path: The path to the creative backup world.
+    """
+    return Path(str(world_path) + f"_creative_{date.today()}")
+
+
+def copy_world(world_path: Path, force: bool = False) -> Path:
+    """Copies a world folder and returns the path of the new copy.
+
+    The world folder is named with the original name suffixed by
+    '_creative' and the current date.
+
+    Args:
+        world_path: The path to the world save folder to copy.
+        force: If True, overwrites the destination without prompting.
+
+    Returns:
+        Path: The path to the newly created world copy.
+    """
+    new_path = get_creative_world_path(world_path)
+
+    if new_path.exists():
+        if force:
+            log.debug(f"Removing {new_path}...")
+            rmtree(new_path)
+        else:
+            log.warning(f"{new_path} already exists")
+            overwrite = None
+            while overwrite is None:
+                overwrite = questionary.confirm(
+                    f"{new_path} already exists. Overwrite?"
+                ).ask()
+            if overwrite:
+                log.debug(f"Removing {new_path}...")
+                rmtree(new_path)
+            else:
+                numbers = [
+                    int(m.group(1))
+                    for path in scandir(new_path.parent)
+                    if path.is_dir()
+                    and (
+                        m := re.search(
+                            rf"{re.escape(new_path.name)}_old_(\d+)$",
+                            path.name,
+                        )
+                    )
+                ]
+
+                next_number = max(numbers, default=0) + 1
+
+                backup_path = new_path.parent / f"{new_path.name}_old_{next_number}"
+                log.debug(f"Renaming {new_path} to {backup_path}...")
+                move(new_path, backup_path)
+                log.debug(f"Renamed {new_path} to {backup_path}")
+
+    log.debug(f"Copying {world_path} to {new_path}...")
+    copytree(world_path, new_path)
+    log.debug(f"Copied {world_path} to {new_path}")
+    return new_path
+
+
+def patch_level_dat(level_dat_path: Path) -> None:
+    """Patches a level.dat file to enable creative mode and cheats.
+
+    Sets GameType to Creative, enables cheats, and updates the world
+    and player game modes.
+
+    Args:
+        level_dat_path: The path to the level.dat file to patch.
+    """
+    nbt_file = nbtlib.load(level_dat_path)
+    nbt_data = nbt_file["Data"]
+
+    level_name = nbt_data["LevelName"]
+
+    nbt_data["allowCommands"] = nbtlib.Byte(1)
+    nbt_data["GameType"] = nbtlib.Int(1)
+    nbt_data["LevelName"] = nbtlib.String(level_name + "_creative")
+    if "Player" in nbt_data:
+        nbt_data["Player"]["playerGameType"] = nbtlib.Int(1)
+
+    nbt_file.save()
+
+
+def launch_prism(prism_path: Path, instance_path: Path) -> None:
+    """Launches PrismLauncher with the specified instance.
+
+    Args:
+        prism_path: The path to the PrismLauncher data directory.
+        instance_path: The path to the PrismLauncher instance to launch.
+
+    Raises:
+        FileNotFoundError: If the PrismLauncher executable cannot be found.
+    """
+    prism_executable = which("prismlauncher")
+    if prism_executable is None:
+        raise FileNotFoundError("Could not find prismlauncher executable in PATH.")
+
+    run(  # noqa: S603
+        [
+            prism_executable,
+            "--directory",
+            str(prism_path),
+            "--launch",
+            instance_path.name,
+        ],
+        check=True,
+    )
+
+
+def main() -> None:
+    """Main entry point for mc-creative-clone."""
+    try:
+        args = parse_args()
+        log.setLevel(logging.DEBUG if args.verbose else logging.INFO)
+        log.info("Hello from mc-creative-clone!")
+
+        instance = get_prism_instance(args.prism_path, args.instance)
+        log.debug(f"Instance path: {instance}")
+
+        minecraft_folder = get_minecraft_folder(instance)
+        log.debug(f"Minecraft folder: {minecraft_folder}")
+
+        world = get_save_folder(minecraft_folder, args.world)
+        log.debug(f"World path: {world}")
+
+        new_world = get_creative_world_path(world)
+        if args.dry_run:
+            log.info(f"[DRY RUN] Would make a copy of {world.name}")
+            log.info(f"[DRY RUN] Would patch level.dat at {new_world / 'level.dat'}")
+        else:
+            log.info(f"Making a copy of {world.name}...")
+            new_world = copy_world(world, args.force)
+            log.info(f"Copied {world.name}")
+
+            new_level_dat = get_level_dat(new_world)
+            log.debug(f"Level.dat path: {new_level_dat}")
+            log.debug(f"Patching {new_level_dat}...")
+            patch_level_dat(new_level_dat)
+            log.debug(f"Patched {new_level_dat}")
+
+            log.info("Launching Minecraft through PrismLauncher...")
+            launch_prism(args.prism_path, instance)
+
+        log.info("Done!")
+    except KeyboardInterrupt:
+        log.info("Aborted")
+        exit(0)
+    except FileNotFoundError:
+        log.exception("Hit a FileNotFoundError.")
+        exit(1)
+    except ValueError:
+        log.exception("Hit a ValueError.")
+        exit(1)
+    except CalledProcessError:
+        log.exception("Hit a CalledProcessError.")
+        exit(1)
+
+
+if __name__ == "__main__":
+    main()

mc_creative_clone-0.1.0.dist-info/METADATA

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: mc-creative-clone
+Version: 0.1.0
+Summary: Copies a Minecraft world and converts it to a creative mode backup
+Project-URL: Repository, https://github.com/xanderboy2001/mc-creative-clone
+Author-email: Alexander Christian <alexanderechristian@gmail.com>
+License: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: minecraft,nbt,prismlauncher
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.10
+Requires-Dist: nbtlib>=2.0.4
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=14.3.3
+Description-Content-Type: text/markdown
+
+<!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 -->
+<a id="readme-top"></a>
+<!--
+*** Thanks for checking out the Best-README-Template. If you have a suggestion
+*** that would make this better, please fork the repo and create a pull request
+*** or simply open an issue with the tag "enhancement".
+*** Don't forget to give the project a star!
+*** Thanks again! Now go create something AMAZING! :D
+-->
+
+
+
+<!-- PROJECT SHIELDS -->
+<!--
+*** I'm using markdown "reference style" links for readability.
+*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).
+*** See the bottom of this document for the declaration of the reference variables
+*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.
+*** https://www.markdownguide.org/basic-syntax/#reference-style-links
+-->
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+[![GPL-3.0-or-later][license-shield]][license-url]
+[![LinkedIn][linkedin-shield]][linkedin-url]
+
+
+
+<h3 align="center">Minecraft Creative Backup</h3>
+
+  <p align="center">
+    A command-line tool that copies a Minecraft world save, patches it into creative mode with cheats enabled, and launches it through PrismLauncher — all in one command.
+    <br />
+    <a href="https://github.com/xanderboy2001/mc-creative-clone"><strong>Explore the docs »</strong></a>
+    <br />
+    <br />
+    <a href="https://github.com/xanderboy2001/mc-creative-clone">View Demo</a>
+    &middot;
+    <a href="https://github.com/xanderboy2001/mc-creative-clone/issues/new?labels=bug&template=bug-report---.md">Report Bug</a>
+    &middot;
+    <a href="https://github.com/xanderboy2001/mc-creative-clone/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a>
+  </p>
+</div>
+
+
+
+<!-- TABLE OF CONTENTS -->
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li>
+      <a href="#about-the-project">About The Project</a>
+      <ul>
+        <li><a href="#built-with">Built With</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#getting-started">Getting Started</a>
+      <ul>
+        <li><a href="#prerequisites">Prerequisites</a></li>
+        <li><a href="#installation">Installation</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#usage">Usage</a>
+      <ul>
+        <li><a href="#options">Options></a></li>
+        <li><a href="#examples"><Examples></a></li>
+      </ul>
+    </li>
+    <li><a href="#contributing">Contributing</a></li>
+    <li><a href="#license">License</a></li>
+    <li><a href="#contact">Contact</a></li>
+  </ol>
+</details>
+
+
+
+<!-- ABOUT THE PROJECT -->
+## About The Project
+
+Minecraft Creative Backup is a Python CLI tool that automates the process of creating creative mode backups of Minecraft worlds managed by PrismLauncher.
+
+When building or experimenting in Minecraft, it's useful to have a creative mode copy of a survival world - but doing it manually means copying the folder, opening the world, changing the game mode, and enabling cheats. This tool automates all of that in a single command.
+
+### What it does
+
+- Copies a Minecraft world save folder
+- Patches the world's `level.dat` to enable creative mode and cheats
+- Renames the backup with the current date for easy identification
+- Launches the instance directly through PrismLauncher
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+### Built With
+
+* [![Python][Python-badge]][Python-url]
+* [![Rich][Rich-badge]][Rich-url]
+* [![questionary][questionary-badge]][questionary-url]
+* [![nbtlib][nbtlib-badge]][nbtlib-url]
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- GETTING STARTED -->
+## Getting Started
+
+
+### Prerequisites
+
+- Python 3.14 or higher
+- [PrismLauncher](https://prismlauncher.org/) installed and configured with at least one instance and world.
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+### Installation
+
+1. Clone the repository
+```sh
+   git clone https://github.com/xanderboy2001/mc-creative-clone.git
+   cd mc-creative-clone
+```
+
+2. Install the package
+```sh
+   uv tool install .
+```
+
+   Or with pip:
+```sh
+   pip install .
+```
+
+3. Verify the installation
+```sh
+   mc-creative-clone --help
+```
+
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- USAGE EXAMPLES -->
+## Usage
+
+Run the tool interactively - you will be prompted to select an instance and world:
+```sh
+mc-creative-clone
+```
+
+Or specify options directly to skip the interactive prompts
+```sh
+mc-creative-clone --instance "My instance" --world "My world"
+```
+
+### Options
+
+| **Option** | **Short** | **Description** |
+| --- | --- | --- |
+| `--prism-path PATH` | `-p` | Path to PrismLauncher data directory. Defaults to the standard OS path. |
+| `--instance INSTANCE` | `-i` | Name of the PrismLauncher instance to use. |
+| `--world WORLD` | `-w` | Name of the world to copy. |
+| `--force` | `-f` | Overwrite the destination world if it already exists without prompting. |
+| `--dry-run` | | Preview actions without making any changes to the filesystem. |
+| `--verbose` | `-v` | Enable verbose debug logging output. |
+
+### Examples
+
+Preview what would happen without making any changes:
+```sh
+mc-creative-clone --dry-run --instance "Survival" --world "My World"
+```
+
+
+Force overwrite an existing backup:
+```sh
+mc-creative-clone --force --instance "Survival" --world "My World"
+```
+
+
+Use a custom PrismLauncher data directory:
+```sh
+mc-creative-clone --prism-path "/path/to/prismlauncher"
+```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- CONTRIBUTING -->
+## Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
+Don't forget to give the project a star! Thanks again!
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+### Top contributors:
+
+<a href="https://github.com/xanderboy2001/mc-creative-clone/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=xanderboy2001/mc-creative-clone" alt="contrib.rocks image" />
+</a>
+
+
+
+<!-- LICENSE -->
+## License
+
+Distributed under the GPL-3.0-or-later. See `LICENSE.txt` for more information.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- CONTACT -->
+## Contact
+
+Alexander Christian - alexanderechristian@gmail.com
+
+Project Link: [https://github.com/xanderboy2001/mc-creative-clone](https://github.com/xanderboy2001/mc-creative-clone)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- MARKDOWN LINKS & IMAGES -->
+<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
+[contributors-shield]: https://img.shields.io/github/contributors/xanderboy2001/mc-creative-clone.svg?style=for-the-badge
+[contributors-url]: https://github.com/xanderboy2001/mc-creative-clone/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/xanderboy2001/mc-creative-clone.svg?style=for-the-badge
+[forks-url]: https://github.com/xanderboy2001/mc-creative-clone/network/members
+[stars-shield]: https://img.shields.io/github/stars/xanderboy2001/mc-creative-clone.svg?style=for-the-badge
+[stars-url]: https://github.com/xanderboy2001/mc-creative-clone/stargazers
+[issues-shield]: https://img.shields.io/github/issues/xanderboy2001/mc-creative-clone.svg?style=for-the-badge
+[issues-url]: https://github.com/xanderboy2001/mc-creative-clone/issues
+[license-shield]: https://img.shields.io/github/license/xanderboy2001/mc-creative-clone.svg?style=for-the-badge
+[license-url]: https://github.com/xanderboy2001/mc-creative-clone/blob/main/LICENSE
+[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
+[linkedin-url]: https://linkedin.com/in/alexander-e-christian
+[product-screenshot]: images/screenshot.png
+<!-- Shields.io badges. You can a comprehensive list with many more badges at: https://github.com/inttter/md-badges -->
+[Python-badge]: https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white
+[Python-url]: https://python.org
+[Rich-badge]: https://img.shields.io/badge/Rich-FAD000?style=for-the-badge&logo=python&logoColor=black
+[Rich-url]: https://github.com/Textualize/rich
+[questionary-badge]: https://img.shields.io/badge/questionary-4a4a55?style=for-the-badge&logo=python&logoColor=white
+[questionary-url]: https://github.com/tmbo/questionary
+[nbtlib-badge]: https://img.shields.io/badge/nbtlib-4a4a55?style=for-the-badge&logo=python&logoColor=white
+[nbtlib-url]: https://github.com/vberlier/nbtlib