From 21dcbdcd1396661743b48a4be9fa618e36e82442 Mon Sep 17 00:00:00 2001 From: Golumpa Date: Wed, 17 Jun 2026 15:23:02 +0100 Subject: [PATCH] bump to 0.1.4 --- README.md | 61 ++++++++++++++++++++++++--- docs/export-format.md | 2 +- pyproject.toml | 2 +- run-exporter.ps1 | 22 +++++----- src/nte_history_exporter/__init__.py | 2 +- src/nte_history_exporter/cli.py | 4 +- src/nte_history_exporter/console.py | 1 + src/nte_history_exporter/constants.py | 2 +- 8 files changed, 72 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 063dd14..aea5475 100644 --- a/README.md +++ b/README.md @@ -29,14 +29,38 @@ The exporter decodes Permanent Board, Limited Character Board, and Arc Miracle B ## Requirements -- Python 3.10 or newer. -- Packet-capture permission: Administrator on Windows, or root/capture capabilities on Linux and macOS. +- Python 3.10 or newer when running from source. Release binaries include the Python runtime. +- Packet-capture permission. On Windows, Npcap can usually capture without running this tool as Administrator; the raw-socket fallback may need Administrator. On Linux and macOS, use root or capture capabilities as required by your system. - **Windows:** [Npcap](https://npcap.com/) is recommended. Install it normally; WinPcap API-compatible mode is not required. If Npcap is unavailable or cannot be initialized, `auto` falls back to the Windows built-in raw-socket backend. - **Linux:** install the system **libpcap** runtime if it is not already present. Package names commonly include `libpcap0.8` on Debian/Ubuntu and `libpcap` on Fedora, Arch, and similar distributions. - **macOS:** the system normally includes **libpcap**, so no separate Npcap installation is needed. Npcap is Windows-only and is not bundled with this project. Linux and macOS use libpcap, the cross-platform capture library on which Npcap is based. +## Downloads + +Compiled command-line builds are published from GitHub Actions as release assets: + +- `nte-history-exporter.exe` for Windows +- `nte-history-exporter-linux` for Linux +- `nte-history-exporter-macos` for macOS +- Versioned `.zip` archives for each platform + +The Windows executable is a single console app. Start it from a terminal: + +```powershell +.\nte-history-exporter.exe +``` + +On Linux and macOS, make the downloaded binary executable before running it. Use `sudo` only when your system requires elevated capture permission: + +```bash +chmod +x ./nte-history-exporter-linux +sudo ./nte-history-exporter-linux +``` + +Use `nte-history-exporter-macos` in the same way on macOS. If your browser or OS blocks a downloaded macOS binary, allow it from the system security prompt before running it again. + ## Usage ### Live capture @@ -48,13 +72,21 @@ The default `auto` capture backend uses: Use `--capture-backend libpcap` to require Npcap/libpcap without fallback, or `--capture-backend raw` to require the Windows raw-socket backend. -#### Windows (requires Administrator) +#### Windows + +Downloaded executable: ```powershell -.\run-exporter.ps1 --live +.\nte-history-exporter.exe ``` -Or simply double-click **`run-exporter.cmd`** — it asks for confirmation before requesting Administrator privileges, and does nothing until you agree. +From source: + +```powershell +.\run-exporter.ps1 +``` + +Or simply double-click **`run-exporter.cmd`**. > [!IMPORTANT] > For automatic user UID detection, launch the tool **before pressing Start on the game's main menu**. If you are already in game, history capture can still work; the tool will ask for your UID before saving if it cannot detect it automatically. @@ -73,19 +105,34 @@ If a page response is missed, the exporter reports the missing page number while #### Linux/macOS -Install the project and ensure the system libpcap runtime is available: +Downloaded executable, using `sudo` when your system requires elevated capture permission: + +```bash +chmod +x ./nte-history-exporter-linux +sudo ./nte-history-exporter-linux +``` + +From source, install the project and ensure the system libpcap runtime is available: ```bash python3 -m venv .venv source .venv/bin/activate python -m pip install -e . -sudo .venv/bin/nte-history-exporter --live +sudo .venv/bin/nte-history-exporter ``` macOS normally includes libpcap. On Linux, install the distribution's libpcap runtime package if it is not already present. Capture can also be granted through platform-specific capabilities instead of running the whole exporter with `sudo`. ### File replay +Downloaded executable: + +```powershell +.\nte-history-exporter.exe capture.flows +``` + +From source: + ```powershell .\run-exporter.ps1 capture.flows ``` diff --git a/docs/export-format.md b/docs/export-format.md index a37f10c..eb0ec8e 100644 --- a/docs/export-format.md +++ b/docs/export-format.md @@ -11,7 +11,7 @@ The sanitized JSON export uses: "capture_source": "npcap", "exporter": { "name": "nte-history-exporter", - "version": "0.1.3" + "version": "0.1.4" }, "banner": { "id": "Lottery_Permanent", diff --git a/pyproject.toml b/pyproject.toml index 24e2f3d..eaefb48 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "nte-history-exporter" -version = "0.1.3" +version = "0.1.4" description = "Cross-platform Neverness to Everness pull-history exporter." requires-python = ">=3.10" dependencies = [] diff --git a/run-exporter.ps1 b/run-exporter.ps1 index 9f4bde5..ac8cf9e 100644 --- a/run-exporter.ps1 +++ b/run-exporter.ps1 @@ -14,27 +14,25 @@ function ConvertTo-QuotedArgument { function Test-RequiresAdministrator { param([string[]]$Arguments) - if ($Arguments.Count -eq 0) { - return $true - } if ($Arguments -contains '--help' -or $Arguments -contains '-h') { return $false } - if ($Arguments -contains '--live') { - return $true - } - foreach ($arg in $Arguments) { - if (-not $arg.StartsWith('-')) { - return $false + for ($i = 0; $i -lt $Arguments.Count; $i++) { + $arg = $Arguments[$i] + if ($arg -eq '--capture-backend' -and $i + 1 -lt $Arguments.Count) { + return $Arguments[$i + 1] -eq 'raw' + } + if ($arg -eq '--capture-backend=raw') { + return $true } } - return $true + return $false } if ((Test-RequiresAdministrator -Arguments $args) -and -not (Test-IsAdministrator)) { - Write-Host 'Administrator permission is required for live packet capture.' - Write-Host 'Windows will show a UAC prompt so the exporter can listen to game network traffic.' + Write-Host 'Administrator permission may be required for the Windows raw capture backend.' + Write-Host 'Windows will show a UAC prompt so the exporter can use raw sockets.' Write-Host '' $answer = Read-Host 'Continue and request administrator access? (Y/N)' if ($answer -notin @('Y', 'y', 'Yes', 'yes')) { diff --git a/src/nte_history_exporter/__init__.py b/src/nte_history_exporter/__init__.py index ae73625..bbab024 100644 --- a/src/nte_history_exporter/__init__.py +++ b/src/nte_history_exporter/__init__.py @@ -1 +1 @@ -__version__ = "0.1.3" +__version__ = "0.1.4" diff --git a/src/nte_history_exporter/cli.py b/src/nte_history_exporter/cli.py index be9a8e2..c069f0d 100644 --- a/src/nte_history_exporter/cli.py +++ b/src/nte_history_exporter/cli.py @@ -50,7 +50,9 @@ def main(argv: list[str] | None = None) -> int: return 0 except (LibpcapUnavailable, PermissionError) as exc: console.print_problem(str(exc)) - console.print_note("Install/enable Npcap or libpcap and run with packet-capture permissions.") + console.print_note( + "Install/enable Npcap or libpcap. If using raw capture on Windows, right-click and run as Administrator; on Linux/macOS, try sudo." + ) return 1 decoded = decode_mitmproxy_flows(args.capture_source, args.flow_index) diff --git a/src/nte_history_exporter/console.py b/src/nte_history_exporter/console.py index 40042c9..e256d4a 100644 --- a/src/nte_history_exporter/console.py +++ b/src/nte_history_exporter/console.py @@ -122,6 +122,7 @@ def print_capture_stats(received: int, dropped: int, interface_dropped: int) -> def print_capture_fallback(reason: str) -> None: print(style(" ! Npcap unavailable; using Windows raw capture.", YELLOW)) print(style(f" {reason}", DIM)) + print(style(" Raw capture may require running this terminal as Administrator.", DIM)) def print_results_header() -> None: diff --git a/src/nte_history_exporter/constants.py b/src/nte_history_exporter/constants.py index fc1248c..c363667 100644 --- a/src/nte_history_exporter/constants.py +++ b/src/nte_history_exporter/constants.py @@ -11,7 +11,7 @@ LIMITED_CHARACTER_BANNER_NAME = "Limited Character Board" ARC_BANNER_ID = "Arc_MiracleBox" ARC_BANNER_NAME = "Arc Miracle Box" EXPORTER_NAME = "nte-history-exporter" -EXPORTER_VERSION = "0.1.3" +EXPORTER_VERSION = "0.1.4" HISTORY_REQUEST_BANNER = 4220 HISTORY_REQUEST_LENGTH = 45