Enhance build process and documentation

Author: Natuworkguy

.flake8

@@ -1,4 +1,4 @@
 [flake8]
-ignore = E501
+ignore = E501, W503
 exclude =
     .venv

docs/using_build_tools.md

@@ -7,10 +7,23 @@ the game's root folder.
 Click "Build Game", then "Yes".
 
 ABS Engine will now compile the game and all of its dependencies
-to the folder that contains the project file.
+to the folder that contains the project file, using Pyinstaller
+under the hood. A "Building Game" window stays open with a progress
+bar while this happens, and only closes once Pyinstaller has
+actually finished.
+
 When you run the new `run.py` file in that folder,
 ABS Engine will emulate its original environment.
 
+The finished build is written to a `dist/<ProjectName>/` folder
+next to your project file (spaces in the project name are replaced
+with hyphens), containing the game's executable alongside an
+`_internal/` folder with its bundled dependencies. Pyinstaller's
+intermediate files are written to a `build/` folder and a generated
+`<ProjectName>.spec` file, also next to your project file.
+Building again automatically replaces a previous `dist/<ProjectName>/`
+folder, even if it still exists from an earlier build.
+
 ## Git Ignore Recommendations
 
 Add the following generated build outputs to your project's
@@ -21,19 +34,31 @@ data/images/abs_*  # Remove if using ABS Engine's logo or other assets
 engine/
 launch_game.py
 run.py
+build/
+dist/
+*.spec
 ```
 
 These files and directories may change in future ABS Engine updates.
 They should stay out of source control and only be included in
 compiled production executables.
 
-To package the game into a single executable file,
-use a tool like **Pyinstaller**. The command should look like this:
+## Building Manually
+
+Build Game already runs Pyinstaller for you, but if you'd rather
+package the game yourself, for example to produce a single
+executable file instead of a folder, you can invoke Pyinstaller
+directly:
 
 ```bash
 pyinstaller --onefile --noconsole --name MyGame --add-data "game.absp:." --add-data "scripts:scripts" --add-data "data:data" run.py
 ```
 
+>[!NOTE]
+> On Windows, use a semicolon (`;`) instead of a colon between the
+> source and destination of each `--add-data` flag, since Windows
+> paths already use a colon after the drive letter (e.g. `C:\`).
+
 Pyinstaller adds `engine/` without any additional flags because
 it is directly imported.
 Use `--icon <file>` to add an icon.

engine/build_tools.py

@@ -5,24 +5,78 @@
 Build and development utilities for the engine.
 """
 
+import os
 import shutil
+import stat
+import time
+from PyInstaller.__main__ import run as pyinstaller
+from multiprocessing import Process
 
 from tkinter import messagebox
 from pathlib import Path
+from typing import Optional
 
 from .saveload import resource_path
 from .logger import logger, Status
 
 engine_path = Path(__file__).parent
 
 
-def build(directory: Path, ENGINE_DATA_PATH: str) -> None:
+def _clear_readonly(func, path, exc: BaseException) -> None:
+    os.chmod(path, stat.S_IWRITE)
+    func(path)
+
+
+def _remove_previous_build(path: Path, retries: int = 5, delay: float = 0.5) -> None:
+    if not path.exists():
+        return
+
+    for attempt in range(retries):
+        try:
+            shutil.rmtree(path, onexc=_clear_readonly)  # ty: ignore[unknown-argument]
+            return
+        except PermissionError:
+            if attempt == retries - 1:
+                raise
+            time.sleep(delay)
+
+
+def _build_pyinstaller(name: str, directory: Path) -> None:
+    _remove_previous_build(directory / "dist" / name)
+
+    pyi_args = [
+        "--onedir",
+        "--noconsole",
+        "--noconfirm",
+        "--name", name,
+        "--distpath", str(directory / "dist"),
+        "--workpath", str(directory / "build"),
+        "--specpath", str(directory),
+        f"--add-data={directory / 'game.absp'!s}{os.pathsep}.",
+    ]
+
+    if (directory / "scripts").exists():
+        pyi_args.append(f"--add-data={directory / 'scripts'!s}{os.pathsep}scripts")
+
+    pyi_args.append(f"--add-data={directory / 'data'!s}{os.pathsep}data")
+    pyi_args.append(str(directory / "run.py"))
+
+    pyinstaller(pyi_args=pyi_args)
+
+
+def build(name: str, directory: Path, ENGINE_DATA_PATH: str) -> Optional[Process]:
     """
     Build the game
 
     Args:
+        name (str): The project's name
         directory (Path): Path to build the game to
         ENGINE_DATA_PATH (str): Path of the data directory
+
+    Returns:
+        Optional[Process]: The process running the PyInstaller build, or None if
+        the build could not be started. Callers can poll `process.is_alive()` to
+        know when the build has actually finished.
     """
 
     if not directory.exists():
@@ -33,7 +87,7 @@ def build(directory: Path, ENGINE_DATA_PATH: str) -> None:
             "Build Error",
             f'Build directory "{str(directory.resolve())}" does not exist. Save the project to a valid location and try again.',
         )
-        return
+        return None
 
     launch_game_script = Path(resource_path("data/scripts/launch_game.py")).read_text(
         encoding="utf-8"
@@ -44,3 +98,10 @@ def build(directory: Path, ENGINE_DATA_PATH: str) -> None:
 
     shutil.copytree(engine_path, directory / "engine", dirs_exist_ok=True, ignore=ignore)
     shutil.copytree(Path(ENGINE_DATA_PATH), directory / "data", dirs_exist_ok=True, ignore=ignore)
+
+    name = name.replace(" ", "-")
+
+    process = Process(target=_build_pyinstaller, args=(name, directory,))
+    process.start()
+
+    return process

engine/core/__init__.py

@@ -440,7 +440,11 @@ def __init__(
         self.screen: pygame.Surface = pygame.display.set_mode(self.wsize, display_flags)
         pygame.display.set_caption(title)
 
-        if not IS_EDITOR and sys.stdout.isatty():
+        if (
+            not IS_EDITOR
+            and sys.stdout is not None
+            and sys.stdout.isatty()
+        ):
             print(colorama.ansi.set_title(title), end="")
 
         self.set_icon(icon_path)

engine/gui/__init__.py

@@ -63,6 +63,11 @@ def __init__(self) -> None:
         self.root.geometry("530x700")
         self.load_theme()
 
+        try:
+            ttk.Style(self.root).theme_use("vista")
+        except TclError:
+            pass
+
         self.root.bind("<Control-Shift-S>", lambda *args: self.save_project_as())
         self.root.bind("<Control-s>", lambda *args: self.save_project())
         self.root.bind("<Control-o>", lambda *args: self.load_project())
@@ -185,12 +190,72 @@ def build_game(self) -> None:
 
         logger("Build Tools: Starting build")
 
-        build(Path(GP_BASE_PATH), ENGINE_DATA_PATH=ENGINE_DATA_PATH)
+        process = build(
+            name=self.project_name_input.get(),
+            directory=Path(GP_BASE_PATH),
+            ENGINE_DATA_PATH=ENGINE_DATA_PATH,
+        )
+
+        if process is None:
+            return
+
+        progress_popup = tk.Toplevel(self.root)
+        progress_popup.wm_title("Building Game")
+        progress_popup.resizable(False, False)
+        progress_popup.protocol("WM_DELETE_WINDOW", lambda: None)
+        progress_popup.transient(self.root)
+
+        progress_content = ttk.Frame(progress_popup, padding=(24, 20))
+        progress_content.pack(fill="both", expand=True)
+
+        ttk.Label(
+            progress_content, text="Building Game", font=("Segoe UI", 12, "bold")
+        ).pack(anchor="w")
+
+        ttk.Label(
+            progress_content,
+            text="This may take a few moments, please wait...",
+            foreground="#666666",
+        ).pack(anchor="w", pady=(2, 14))
+
+        progress_bar = ttk.Progressbar(progress_content, mode="indeterminate", length=300)
+        progress_bar.pack(fill="x")
+        progress_bar.start(10)
+
+        ttk.Label(
+            progress_content,
+            text="See the console for detailed logs.",
+            foreground="#999999",
+            font=("Segoe UI", 8),
+        ).pack(anchor="w", pady=(12, 0))
+
+        progress_popup.update_idletasks()
+        popup_x = self.root.winfo_x() + (self.root.winfo_width() - progress_popup.winfo_width()) // 2
+        popup_y = self.root.winfo_y() + (self.root.winfo_height() - progress_popup.winfo_height()) // 2
+        progress_popup.geometry(f"+{popup_x}+{popup_y}")
+
+        progress_popup.grab_set()
+
+        def poll_build() -> None:
+            if process.is_alive():
+                self.root.after(200, poll_build)
+                return
+
+            progress_bar.stop()
+            progress_popup.grab_release()
+            progress_popup.destroy()
+
+            if process.exitcode == 0:
+                logger("Build Tools: Build completed")
+                messagebox.showinfo("Build Tools | ABS Engine", "The build has been completed.")
+            else:
+                logger("Build Tools: Build failed", status=LoggerStatus.WARNING)
+                messagebox.showerror(
+                    "Build Tools | ABS Engine",
+                    "The build failed. Check the console/log output for details.",
+                )
 
-        logger("Build Tools: Waiting for root")
-        self.root.after(3000, lambda: None)
-        logger("Build Tools: Build completed")
-        messagebox.showinfo("Build Tools | ABS Engine", "The build has been completed.")
+        self.root.after(200, poll_build)
 
     def game_settings(self) -> None:
         self.game_settings_popup = tk.Toplevel(self.root, height=150)

engine/logger.py

@@ -53,7 +53,7 @@ def logger(message: str, *, status: Status = Status.INFO) -> None:
     """
 
     source = _get_caller_module().upper()
-    is_tty: bool = sys.stdout.isatty()
+    is_tty: bool = sys.stdout is not None and sys.stdout.isatty()
 
     if is_tty:
         if status == Status.CRITICAL:

requirements-dev.txt

@@ -8,4 +8,5 @@ interrogate
 ty
 
 # Typeshed packages
-types-colorama
+types-colorama
+types-pyinstaller

requirements.txt

@@ -1,2 +1,3 @@
 pygame-ce
-colorama
+colorama
+pyinstaller