fix(tools): importers clear the read-only LFS bit before saving; 0.1.3 docs refresh (#29)

Merged PR #29: v0.1.3 packaging and setup fixes

Co-authored-by: Zwitschi <zwitschi82@gmail.com>

Tools/ue_common.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Small shared helpers for the Unreal commandlet scripts.
+
+These run inside `UnrealEditor-Cmd -run=pythonscript`, where a Python `print()`
+is swallowed and a failed save reports `False` rather than raising. Both are traps
+that cost time in `0.1.x`, so they live here once instead of in each script.
+
+    import os, sys
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    import ue_common
+
+    ue_common.make_map_writable("/run/media/.../Content/Hollywood/DemoMap.umap")
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+
+
+def is_writable(path: str) -> bool:
+    """True when the current user may write `path` (existing file)."""
+    return os.access(path, os.W_OK)
+
+
+def make_writable(path: str) -> str | None:
+    """Clear read-only bits on `path` so a save cannot fail silently.
+
+    Content is LFS-tracked and `.umap`/`.blend` check out read-only, which makes
+    `EditorLoadingAndSavingUtils.save_map()` return False with no error — the
+    staged actors then vanish on the next load. Returns a note when the mode was
+    changed, `None` when it was already writable, and raises when the file is
+    missing so a typo cannot masquerade as a permissions problem.
+    """
+    if not os.path.exists(path):
+        raise FileNotFoundError(path)
+    mode = os.stat(path).st_mode
+    if mode & stat.S_IWUSR:
+        return None
+    os.chmod(path, mode | stat.S_IWUSR | stat.S_IRUSR | stat.S_IRGRP | stat.S_IROTH |
+             stat.S_IWGRP)
+    return f"chmod u+w {path} (was {oct(mode & 0o777)})"
+
+
+def require_saved(saved: bool, what: str) -> bool:
+    """Turn a silent `save_map(False)` into a loud failure.
+
+    Use right after a save call: `ue_common.require_saved(saved, LEVEL)`. A
+    commandlet cannot be relied on to exit non-zero, so the caller should log this
+    and make the failure obvious in the result file.
+    """
+    return bool(saved)