Release 2.13.0

.github/copilot-coding-agent-setup.md

@@ -0,0 +1,54 @@
+# GitHub Copilot coding agent setup instructions
+
+This section only applies to the GitHub Copilot coding agent, running in a Linux runner from the GitHub Action environment. It does not apply to other environments, such as local development.
+
+The GitHub Actions workflow `.github/workflows/copilot-setup-steps.yml` runs the setup steps mentioned in this file automatically. The commands below are the manual equivalent and **should only be run if you encounter a build failure** — for example, if GitVersion cannot determine the version, if submodules are missing, or if NuGet restore fails.
+
+## Step 1 — Initialize git submodules
+
+`Rampastring.XNAUI` (and its nested submodule `Rampastring.Tools`) may not be pre-initialized. Missing them causes compile errors about unknown `Rampastring.*` types.
+
+```shell
+git submodule update --init --recursive
+```
+
+## Step 2 — Unshallow the clone and fetch `develop`
+
+The build system uses **GitVersion.MsBuild** to compute version numbers at compile time. It requires two things:
+
+- A full (non-shallow) commit history.
+- The `develop` branch reachable as a remote-tracking ref (it is the mainline branch in `GitVersion.yml`). Without it, any branch that is not `develop` or `master` fails with `Gitversion could not determine which branch to treat as the development branch`.
+
+Run all three commands unconditionally:
+
+- `--unshallow` is a no-op on an already-full clone (`|| true` prevents it from aborting).
+- `set-branches` resets the remote's fetch refspec to the standard glob `+refs/heads/*:refs/remotes/origin/*`, removing any single-branch refspec that a shallow clone may have injected. Without this, LibGit2Sharp (used by GitVersion 5.12.0) crashes with `ref 'refs/remotes/origin/develop' doesn't match the destination` because it iterates refspecs in order and fails on the first non-matching one instead of falling through to the glob.
+- The final fetch brings `refs/remotes/origin/develop` into the local ref store through that glob refspec so GitVersion can find it.
+
+The same fix must be applied to every submodule recursively: `Rampastring.XNAUI` and its nested `Rampastring.Tools` submodule also carry `GitVersion.MsBuild` and are subject to the same crash when checked out with a narrow single-branch refspec.
+
+```shell
+git fetch --unshallow origin || true
+git remote set-branches origin '*'
+git fetch origin develop
+git submodule foreach --recursive \
+  'git fetch --unshallow origin || true; git remote set-branches origin "*"; git fetch origin'
+```
+
+## Step 3 — Restore NuGet packages
+
+Run restore from the **solution file** so that ALL projects — including `SecondStageUpdater` — are restored. `SecondStageUpdater` is not a `<ProjectReference>` of `DXMainClient`, but it is always built via the custom `BuildUpdater` MSBuild target. If it is not restored before the build, NETSDK1127 or NETSDK1004 errors occur. Always pass the `Configuration` property; omitting it picks the wrong target frameworks.
+
+```shell
+dotnet restore DXClient.slnx -p:Configuration=UniversalGLRelease
+```
+
+## Step 4 — Build
+
+`--no-restore` is **required**. When `dotnet build` runs without it, the implicit restore only traverses DXMainClient's `<ProjectReference>` graph, which excludes `SecondStageUpdater`. This leaves SecondStageUpdater's restore assets stale after any code change, causing build failures. Always run Step 3 first, then build with `--no-restore`.
+
+```shell
+dotnet build DXMainClient/DXMainClient.csproj -p:Configuration=UniversalGLRelease -f net8.0 --no-restore
+```
+
+A successful build ends with `0 Error(s)`.

.github/copilot-instructions.md

@@ -0,0 +1,40 @@
+# Agent Instructions
+
+
+## General information
+
+### Project structure
+
+| Path | Description |
+|------|-------------|
+| `DXMainClient/` | Main entry-point project — always the build target |
+| `ClientCore/` | Core game-client logic |
+| `ClientGUI/` | UI layer |
+| `ClientUpdater/` | Auto-updater logic |
+| `SecondStageUpdater/` | Secondary updater executable |
+| `Rampastring.XNAUI/` | UI framework (git submodule) |
+| `GitVersion.yml` | GitVersion branch and versioning strategy |
+| `global.json` | Pins the required .NET SDK version (10.0, any feature band) |
+| `Directory.Build.props` | MSBuild properties shared across all projects |
+| `Directory.Packages.props` | Central NuGet package version management |
+| `Docs/Build.md` | Human-oriented build documentation |
+
+### Build the project
+
+Always run restore before building. `SecondStageUpdater` is built via a custom MSBuild target (`BuildUpdater`) that fires for every DXMainClient build, but it is not in DXMainClient's project reference graph. This means the implicit restore triggered by `dotnet build` (without `--no-restore`) will not restore it, causing a build failure after any code change that invalidates the NuGet cache.
+
+```shell
+dotnet restore DXClient.slnx -p:Configuration=UniversalGLRelease
+dotnet build DXMainClient/DXMainClient.csproj -p:Configuration=UniversalGLRelease -f net8.0 --no-restore
+```
+
+A successful build ends with `0 Error(s)`.
+
+### Contributing guidelines
+See [Contributing.md](../Contributing.md) for coding style, formatting, and other contribution guidelines. Be aware, Copilot, you MUST read and follow this file, even if the user did not explicitly ask you to.
+
+## GitHub Copilot coding agent setup instructions
+
+This section only applies to the GitHub Copilot coding agent, running in a Linux runner from the GitHub Action environment. It does not apply to other environments, such as local development.
+
+The steps in the [copilot-coding-agent-setup.md](./copilot-coding-agent-setup.md) file are automatically executed via a GitHub Action workflow before the agent starts. **Only read and run them manually if you encounter a build failure**.

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,57 @@
+name: Copilot setup steps
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code with full history and submodules
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      # the set-branches call is required to collapse the shallow-clone's specific-branch refspec back to the glob, preventing a LibGit2Sharp crash in GitVersion 5.12.0
+      - name: Unshallow clone and fetch develop branch
+        run: |
+          git fetch --unshallow origin || true
+          git remote set-branches origin '*'
+          git fetch origin develop
+          # Apply the same fix to every submodule (including nested ones), because GitVersion.MsBuild
+          # runs against each submodule directory that carries it, and the same LibGit2Sharp refspec
+          # crash occurs there when the submodule was checked out with a narrow single-branch refspec.
+          git submodule foreach --recursive \
+            'git fetch --unshallow origin || true; git remote set-branches origin "*"; git fetch origin'
+
+      - name: Set up .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          global-json-file: ./global.json
+
+      - name: Restore NuGet packages
+        # Restore from the solution file so that SecondStageUpdater is included.
+        # SecondStageUpdater is not a ProjectReference of DXMainClient, but it is
+        # always built via the BuildUpdater MSBuild target; omitting it from the
+        # restore causes NETSDK1127/NETSDK1004 on subsequent agent builds.
+        run: dotnet restore DXClient.slnx -p:Configuration=UniversalGLRelease
+
+      - name: Build
+        # --no-restore is required: the implicit restore triggered by 'dotnet build'
+        # only walks DXMainClient's ProjectReference graph and therefore skips
+        # SecondStageUpdater, leaving its restore assets stale.
+        run: dotnet build DXMainClient/DXMainClient.csproj -p:Configuration=UniversalGLRelease -f net8.0 --no-restore

.gitignore

@@ -389,6 +389,9 @@ FodyWeavers.xsd
 !.vscode/extensions.json
 *.code-workspace
 
+# Official VS Code C# Dev Kit Extension exclusion
+*.lscache
+
 # Local History for Visual Studio Code
 .history/
 

AdditionalFiles/PreprocessFont/README.md

@@ -0,0 +1,7 @@
+This directory serves as a backup for the font preprocessing utilities referenced in [Fonts.md](/Docs/Fonts.md).
+
+## Bits'N'Picas
+https://github.com/kreativekorp/bitsnpicas
+
+## BdfToolSP
+https://github.com/SadPencil/BdfToolSP

ClientCore/Caching/CacheLease.cs

@@ -0,0 +1,62 @@
+#nullable enable
+using System;
+using System.Threading;
+
+namespace ClientCore.Caching;
+
+/// <summary>
+/// A disposable lease on a cached value. The caller must dispose this lease when done
+/// with the value to release the reference. If the underlying value is <see cref="IDisposable"/>,
+/// it is disposed only when all leases and the cache itself have released their references.
+/// </summary>
+public sealed class CacheLease<T> : IDisposable
+{
+    private readonly T value;
+    private readonly Action? onRelease;
+    private int disposeFlag = 0;
+
+    /// <summary>
+    /// Creates a lease that directly owns the value.
+    /// Disposing this lease invokes <paramref name="onRelease"/> if provided.
+    /// </summary>
+    /// <param name="value">The directly owned value.</param>
+    /// <param name="onRelease">Action to invoke when the lease is disposed, or <c>null</c>.</param>
+    public static CacheLease<T> CreateOwned(T value, Action? onRelease) => new CacheLease<T>(value, onRelease);
+
+    /// <summary>
+    /// Creates a lease that directly owns the value.
+    /// Disposing this lease invokes <paramref name="onRelease"/> if provided.
+    /// </summary>
+    internal CacheLease(T value, Action? onRelease)
+    {
+        this.value = value;
+        this.onRelease = onRelease;
+    }
+
+    /// <summary>
+    /// Creates a lease backed by a ref-counted value.
+    /// The ref count was already incremented by <see cref="RefCountedValue{T}.AcquireLease"/>;
+    /// disposing this lease calls <see cref="RefCountedValue{T}.Release"/>.
+    /// </summary>
+    internal CacheLease(RefCountedValue<T> refCounted)
+    {
+        value = refCounted.Value;
+        onRelease = refCounted.Release;
+    }
+
+    /// <summary>
+    /// Gets the leased value.
+    /// </summary>
+    public T Value => value;
+
+    /// <summary>
+    /// Releases this lease. If this was the last reference to a ref-counted value,
+    /// the underlying value is disposed.
+    /// Safe to call multiple times; only the first call takes effect.
+    /// </summary>
+    public void Dispose()
+    {
+        if (Interlocked.Exchange(ref disposeFlag, 1) == 0)
+            onRelease?.Invoke();
+    }
+}