Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ unchanged. It does not bundle Path of Exile or LocalExile, and does not offer a

## Install

Requirements: Windows 10/11 x64, the .NET 10 Desktop Runtime, and a PoE **3.29.3c** or **3.29.3d** client: your own standalone one, or for a release one Waypoint downloads from Steam
Requirements: Windows 10/11 x64, the .NET 10 Desktop Runtime, and a PoE **3.29.3c** or **3.29.3d** client: your own standalone or Steam install, or one Waypoint downloads from Steam
with your own Steam account ([The game client from Steam](docs/launcher.md#the-game-client-from-steam)) (a player who has only 3.29.3b gets
the last LocalExile made for it, see [Game client builds](docs/launcher.md#game-client-builds)). The setup guide
offers two ways to get LocalExile:
Expand All @@ -34,7 +34,7 @@ offers two ways to get LocalExile:
| [Git](https://git-scm.com/downloads/win) | Branches and pull requests |
| [Python 3.9+](https://www.python.org/downloads/windows/) | Data extraction, consistent save backups, the account tools. Tick the installer's *Add python.exe to PATH*; Waypoint also finds a Python installed without it |
| [Node.js](https://nodejs.org/en/download) | The bundle-decompression dependency |
| Your own standalone PoE **3.29.3c** or **3.29.3d** client | A separate copy in the checkout's `Client` folder; Steam layout and other builds are unsupported |
| A PoE **3.29.3c** or **3.29.3d** client, standalone or from Steam | A separate copy in the checkout's `Client` folder; other builds are unsupported |

Frida (`pip install frida`) is optional: it is needed for walk maps, the console and live mod control, not for ordinary play.
The item crafter's Give item uses the Waypoint Tools mod instead, which it offers to install.
Expand All @@ -55,7 +55,7 @@ where they are. Neither old file is changed.

Linux has its own executable and interface (`src/Waypoint.Linux`, Avalonia) over the same engine, and the Windows app is
built as before. It needs the .NET 10 SDK, [umu-launcher](https://github.com/Open-Wine-Components/umu-launcher) and your own
standalone PoE **3.29.3c** or **3.29.3d** client. A source checkout also needs PowerShell 7 (`dotnet tool install --global PowerShell`), Git,
PoE **3.29.3c** or **3.29.3d** client, standalone or from Steam. A source checkout also needs PowerShell 7 (`dotnet tool install --global PowerShell`), Git,
Python 3.9+ and Node.js.

```bash
Expand Down
122 changes: 104 additions & 18 deletions docs/launcher.md

Large diffs are not rendered by default.

10 changes: 7 additions & 3 deletions scripts/LeagueArt.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,13 +66,17 @@ def atlas_sprite(atlas, key):
def extract(root, cache):
import PIL
from PIL import Image
archive = root / "Client/Content.ggpk"
# A client from Steam has no archive: its files are loose, LocalExile's extractor takes the client folder, and the
# index of its bundles stands for it.
archive = stamp = root / "Client/Content.ggpk"
if not archive.is_file():
archive, stamp = root / "Client", root / "Client/Bundles2/_.index.bin"
source_file = root / "src/GameServer.Core/Accounts/LeagueCatalog.cs"
source = source_file.read_bytes()
if len(source) > 1024 * 1024:
raise ValueError("Banner contract is too large.")
selector = wire_selector(source.decode("utf-8-sig"))
before = signature(archive)
before = signature(stamp)
source_hash = hashlib.sha256(source).hexdigest()
helper_hash = hashlib.sha256(Path(__file__).read_bytes()).hexdigest()
key = hashlib.sha256(json.dumps([str(root), before, source_hash, helper_hash, PIL.__version__]).encode()).hexdigest()
Expand Down Expand Up @@ -124,7 +128,7 @@ def read(path):
image.convert("RGBA").crop(bounds).save(staging / (kind + ".png"))
provenance["sprites"][kind] = {"key": chosen, "texture": texture, "bounds": bounds}
provenance["hashes"][kind] = hashlib.sha256((staging / (kind + ".png")).read_bytes()).hexdigest()
if before != signature(archive) or source_file.read_bytes() != source:
if before != signature(stamp) or source_file.read_bytes() != source:
raise ValueError("Client assets or banner contract changed while reading.")
destination.mkdir(exist_ok=True)
for kind in ("normal", "hardcore"):
Expand Down
53 changes: 42 additions & 11 deletions scripts/RuntimeBridge.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,8 @@ function Import-RuntimeProfile {
[Environment]::SetEnvironmentVariable($key, $expression.Value, 'Process')
}
}
# Game_GGPK: LocalExile stopped reading it when its servers stopped opening the client's files; a profile from before
# may still name the old default. The client's files are found in Client, in either layout (Get-ClientLayout).
foreach ($entry in @{
Game_BIND='127.0.0.1'; Game_LOGIN_PORT='20493'; Game_GATEWAY_PORT='6112'; Game_AUTH_CONTROL_PORT='20495';
Game_PATCH_TCP_PORT='12995'; Game_PATCH_URL='http://127.0.0.1:8080/'; Game_CLIENT_EXE='Client/Game.exe'; Game_GGPK='Client/Content.ggpk'
Expand Down Expand Up @@ -276,7 +278,7 @@ function Get-Snapshot {
@{ Name='Launch adapter'; Ready=((Test-Path -LiteralPath (At 'scripts/dev/live.ps1')) -and ((Get-Content -LiteralPath (At 'scripts/dev/live.ps1') -Raw) -match '\$ClientOnly')); Detail='scripts/dev/live.ps1 must support -ClientOnly and -Only' },
@{ Name='Original client'; Ready=(Test-Path -LiteralPath (At 'Client/Game.exe')); Detail=(Get-ClientDetail) },
@{ Name='Prepared client'; Ready=(Test-Path -LiteralPath $gamePath); Detail='Follow Agents/GettingStarted.md steps 4-5 to prepare Game.patched.exe' },
@{ Name='Client archive'; Ready=(Test-Path -LiteralPath (At 'Client/Content.ggpk')); Detail='Standalone Content.ggpk is required; Steam layout is unsupported' },
@{ Name='Client archive'; Ready=((Get-ClientLayout) -eq 'Standalone' -or ((Get-ClientLayout) -eq 'Steam' -and (Test-SteamLayoutAccepted))); Detail=(Get-ArchiveDetail) },
@{ Name='Login keys'; Ready=(Test-Path -LiteralPath (At 'data/login-keys.json')); Detail='data/login-keys.json must match the prepared client; never regenerate existing keys casually' },
@{ Name='Python'; Ready=(Test-Python); Detail='Python 3.9+ is required for data extraction' },
@{ Name='Node.js'; Ready=([bool](Get-Command node -ErrorAction SilentlyContinue)); Detail='Node.js is required for bundle decompression' },
Expand Down Expand Up @@ -801,9 +803,26 @@ function Start-FreshSaves($snapshot) {
Assert-Physical $history
if (Test-Path -LiteralPath $history) { Remove-Item -LiteralPath $history }
}
# How Client holds the game's files, told apart as LocalExile does (its ClientFiles.Resolve): a Content.ggpk first, else the
# loose files of a Steam install, known by Bundles2/_.index.bin. '' when it holds neither.
function Get-ClientLayout {
if (Test-Path -LiteralPath (At 'Client/Content.ggpk') -PathType Leaf) { return 'Standalone' }
if (Test-Path -LiteralPath (At 'Client/Bundles2/_.index.bin') -PathType Leaf) { return 'Steam' }
return ''
}
# Whether this checkout's LocalExile runs a Steam install: its own live.ps1 says so, by accepting Bundles2\_.index.bin in
# place of Content.ggpk. An older checkout refuses such a client at every start.
function Test-SteamLayoutAccepted {
$live = At 'scripts/dev/live.ps1'
return (Test-Path -LiteralPath $live -PathType Leaf) -and ((Get-Content -LiteralPath $live -Raw) -match 'Bundles2\\_\.index\.bin')
}
function Get-ArchiveDetail {
if ((Get-ClientLayout) -eq 'Steam' -and -not (Test-SteamLayoutAccepted)) { return 'This LocalExile runs only a standalone client. A client from Steam needs a newer LocalExile.' }
return 'Client needs Content.ggpk (standalone) or Bundles2\_.index.bin (Steam)'
}
function Get-ClientDetail {
$client = Get-Item -LiteralPath (At 'Client') -Force -ErrorAction SilentlyContinue
if (-not $client -or -not ($client.Attributes -band [IO.FileAttributes]::ReparsePoint)) { return 'Standalone 3.29.3c executable at Client/Game.exe' }
if (-not $client -or -not ($client.Attributes -band [IO.FileAttributes]::ReparsePoint)) { return 'Client/Game.exe: a copy of PathOfExile.exe (Steam: PathOfExileSteam.exe)' }
$target = @($client.Target)[0]
if (Test-Path -LiteralPath (At 'Client/Game.exe')) { return "Linked to $target" }
return "Client links to $target, which has no client. Run the setup guide to replace the link."
Expand All @@ -820,27 +839,36 @@ function Prepare-Client($snapshot) {
Write-Host "Client is a link to $target and is already prepared: nothing to do."
return
}
Require (Test-Path -LiteralPath (At 'Client/Content.ggpk')) 'Copy the complete standalone 3.29.3c client into Client first.'
foreach ($relative in @('Client/Content.ggpk','Client/Game.exe','Client/PathOfExile.exe','Client/Game.patched.exe','data','data/login-keys.json')) {
$layout = Get-ClientLayout
Require $layout 'Copy the complete game client into Client first.'
Require ($layout -ne 'Steam' -or (Test-SteamLayoutAccepted)) (Get-ArchiveDetail)
foreach ($relative in @('Client/Content.ggpk','Client/Bundles2','Client/Bundles2/_.index.bin','Client/gateway_list.txt','Client/Game.exe','Client/PathOfExile.exe','Client/PathOfExileSteam.exe','Client/Game.patched.exe','data','data/login-keys.json')) {
$item = Get-Item -LiteralPath (At $relative) -ErrorAction SilentlyContinue
Require (-not $item -or -not ($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) "Preparation refuses redirected files or folders: $relative"
}
$keys = Test-Path -LiteralPath (At 'data/login-keys.json')
$patched = Test-Path -LiteralPath (At 'Client/Game.patched.exe')
Require ($keys -or -not $patched) 'A prepared executable exists without keys. Preserve it and recover its matching keys, or prepare a new client copy.'
$game = At 'Client/Game.exe'
$original = At 'Client/PathOfExile.exe'
$prepared = At 'Client/Game.patched.exe'
$gameHash = if (Test-Path -LiteralPath $game) { (Get-FileHash -LiteralPath $game -Algorithm SHA256).Hash } else { '' }
$originalHash = if (Test-Path -LiteralPath $original) { (Get-FileHash -LiteralPath $original -Algorithm SHA256).Hash } else { '' }
# Only a fingerprint from ClientLocator for this checkout's declared build authorizes a repair: one for each executable
# GGG shipped under the build's name (a hotfix keeps the name), comma-separated.
# Small launchers, future builds and a different checkout's build cannot replace an existing executable, and a
# Game.exe that is one of the build's own executables is valid as it is: the build's other one does not replace it.
$clientHashes = @($ClientExecutableHash -split ',' | Where-Object { $_ })
# The game's own executable, in LocalExile's order (its ClientInstall): PathOfExile.exe, or a Steam install's
# PathOfExileSteam.exe, which is the same file. PathOfExile.exe can be the small launcher, so one that is the build's
# goes first; without one, the first that is there, as before.
$originals = @(@('PathOfExile.exe','PathOfExileSteam.exe') | Where-Object { Test-Path -LiteralPath (At "Client/$_") -PathType Leaf } |
ForEach-Object { @{ Name=$_; Hash=(Get-FileHash -LiteralPath (At "Client/$_") -Algorithm SHA256).Hash } })
$chosen = @(@($originals | Where-Object { $clientHashes -contains $_.Hash }) + $originals) | Select-Object -First 1
$originalName = if ($chosen) { $chosen.Name } elseif ($layout -eq 'Steam') { 'PathOfExileSteam.exe' } else { 'PathOfExile.exe' }
$original = At "Client/$originalName"
$originalHash = if ($chosen) { $chosen.Hash } else { '' }
$refresh = $originalHash -and $clientHashes -contains $originalHash -and $gameHash -and $clientHashes -notcontains $gameHash
Write-Host "Client/Game.exe SHA-256: $gameHash"
Write-Host "Client/PathOfExile.exe SHA-256: $originalHash"
Write-Host "Client/$originalName SHA-256: $originalHash"
Set-Stage 'Building preparation tools' 'Auth and Patch'
foreach ($name in @('Auth','Patch')) {
& dotnet build (At "src/GameServer.$name") --nologo -v minimal
Expand All @@ -851,7 +879,7 @@ function Prepare-Client($snapshot) {
$stagedGame = $null; $stagedPatch = $null
try {
if (-not $gameHash) {
Require (Test-Path -LiteralPath $original) 'Client/PathOfExile.exe or Client/Game.exe is required.'
Require (Test-Path -LiteralPath $original) 'Client/PathOfExile.exe (Steam: PathOfExileSteam.exe) or Client/Game.exe is required.'
Copy-Item -LiteralPath $original -Destination $game
$gameHash = (Get-FileHash -LiteralPath $game -Algorithm SHA256).Hash
}
Expand All @@ -864,7 +892,7 @@ function Prepare-Client($snapshot) {
}
if (-not $keys) {
& dotnet $auth keygen $inputGame
Require ($LASTEXITCODE -eq 0) 'Key generation failed. Check that the original executable is standalone 3.29.3c.'
Require ($LASTEXITCODE -eq 0) 'Key generation failed. Check that the original executable is a version this LocalExile runs.'
}
$knownGame = $refresh -or ($gameHash -and $clientHashes -contains $gameHash)
$stalePatch = $patched -and $knownGame -and (
Expand Down Expand Up @@ -898,8 +926,11 @@ function Prepare-Client($snapshot) {
if ($temp -and (Test-Path -LiteralPath $temp)) { Remove-Item -LiteralPath $temp -Force }
}
}
Set-Stage 'Selecting local gateway' 'Only the copied client archive is updated.'
& dotnet (At 'src/GameServer.Patch/bin/Debug/net10.0/GameServer.Patch.dll') gateway (At 'Client/Content.ggpk') --login '127.0.0.1:20493'
# The login list is in the GGPK, or a Steam install's loose Client/gateway_list.txt: LocalExile's own tool finds it in
# the client folder (its live.ps1 gives it the folder). A standalone client still gets its archive named, which every
# LocalExile takes.
Set-Stage 'Selecting local gateway' $(if ($layout -eq 'Steam') { 'Only the copied client''s gateway list is updated.' } else { 'Only the copied client archive is updated.' })
& dotnet (At 'src/GameServer.Patch/bin/Debug/net10.0/GameServer.Patch.dll') gateway $(if ($layout -eq 'Steam') { At 'Client' } else { At 'Client/Content.ggpk' }) --login '127.0.0.1:20493'
Require ($LASTEXITCODE -eq 0) 'Local gateway setup failed. Close all clients and inspect the operation log.'
}
function Register-Account($snapshot) {
Expand Down
51 changes: 51 additions & 0 deletions src/Launcher.Core/CheckoutIgnores.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
namespace Launcher.Core;

/// <summary>
/// What Waypoint keeps in a LocalExile folder beside <c>Client</c> is its own: the clients set aside in <c>Clients\</c>
/// (<see cref="ClientVersions"/>) and the folders a download, a copy or a removal works in (<c>.waypoint-…</c>). A release
/// has no git. A source copy does, and there git would list those folders as new files, and a switch of the checkout, which
/// stashes what is not committed, would take a client apart. So before Waypoint makes one of them in a source copy, it
/// names them in the copy's own <c>info/exclude</c>: git's place for what one clone ignores, which no commit holds and
/// which therefore stays whichever revision the copy is on. Nothing tracked is changed.
/// </summary>
public static class CheckoutIgnores
{
public static IReadOnlyList<string> Patterns { get; } = ["/" + ClientVersions.KeptFolder + "/", "/.waypoint-*"];

const string Heading = "# Waypoint: game clients it keeps beside Client, and the folders it works in";

/// <summary>Names Waypoint's folders in the checkout's <c>info/exclude</c>; nothing for a folder without git, and
/// nothing when they are named already. True when the file holds them afterwards.</summary>
public static bool Ensure(string folder)
{
try
{
if (Exclude(folder) is not { } file) return false;
string[] lines = File.Exists(file) ? File.ReadAllLines(file) : [];
var missing = Patterns.Where(pattern => !lines.Any(line => line.Trim() == pattern)).ToList();
if (missing.Count == 0) return true;
Directory.CreateDirectory(Path.GetDirectoryName(file)!);
var text = new List<string>(lines);
if (!lines.Any(line => line.Trim() == Heading)) text.Add(Heading);
text.AddRange(missing);
File.WriteAllLines(file, text);
return true;
}
catch (Exception e) when (e is IOException or UnauthorizedAccessException or ArgumentException) { return false; }
}

/// <summary>The checkout's <c>info/exclude</c>: in <c>.git</c>, or for a worktree (whose <c>.git</c> is a file that
/// names its own folder) in the repository that folder's <c>commondir</c> names. Null for a folder without git.</summary>
static string? Exclude(string folder)
{
string git = Path.Combine(folder, ".git");
if (Directory.Exists(git)) return Path.Combine(git, "info", "exclude");
if (!File.Exists(git)) return null;
string? own = File.ReadLines(git).Select(line => line.Trim()).FirstOrDefault(line => line.StartsWith("gitdir:", StringComparison.Ordinal))?["gitdir:".Length..].Trim();
if (own is not { Length: > 0 }) return null;
own = Path.GetFullPath(own, folder);
string shared = Path.Combine(own, "commondir");
string common = File.Exists(shared) ? Path.GetFullPath(File.ReadAllText(shared).Trim(), own) : own;
return Directory.Exists(common) ? Path.Combine(common, "info", "exclude") : null;
}
}
Loading
Loading