modernuo/Projects/Server/Client/ClientVersion.cs
Kamron Batman 61e41df00c
feat: Add zero-alloc interpolation handler to ValueStringBuilder, replace all StringBuilder usage (#2387)
## Summary

- **Add a self-referencing `InterpolationHandler` to `ValueStringBuilder`** that writes directly into the builder's buffer — zero intermediate allocation, works with `stackalloc`-backed builders
- **Replace all `System.Text.StringBuilder` usage** across the codebase with `ValueStringBuilder`
- **Convert `ValueStringBuilder.Create()` to `stackalloc`** at 10 sites where output length is provably bounded
- **Convert manual `Dispose()` to `using var`** where possible, and hoist loop-scoped builders outside loops with `Reset()`
- **Convert verbose `Append()` chains to `Append($"...")`** interpolation for readability
- **Add comprehensive documentation** for string handling patterns

## InterpolationHandler Design

`ValueStringBuilder` is a `ref struct`, which creates challenges for C#'s interpolated string handler pattern:

- **`ref` fields to ref structs are not allowed** (CS9050)
- **`[InterpolatedStringHandlerArgument("")]` passes struct receivers by value**, not by ref
- **`ISelfInterpolatedStringHandler` requires boxing** ref structs into interface fields

**Solution: Copy-and-reconcile pattern.** The handler receives a value copy of the builder. The copy shares the same underlying `char` buffer (`Span` points to the same `stackalloc`/pooled memory), so writes go to the original buffer. `Append()` reconciles by `this = handler._builder`, updating `_length` and any buffer references changed by `Grow()`.

This is safe because:
- The game loop is single-threaded — no concurrent access between handler construction and reconciliation
- If `Grow()` occurs in the copy, the original's stale buffer isn't accessed until `Append()` replaces it
- `Dispose()` correctly returns the reconciled buffer to the pool

## Changes by Category

### ValueStringBuilder (`Projects/Server/Buffers/ValueStringBuilder.cs`)
- Added nested `InterpolationHandler` ref struct with copy-and-reconcile pattern
- Added `Append([InterpolatedStringHandlerArgument("")] scoped ref InterpolationHandler)` method
- Removed `RawInterpolatedStringHandler` overloads (new handler replaces them)
- All `AppendFormatted` overloads delegate to existing `Append` methods (no code duplication)
- Alignment support via direct private field access (nested type privilege)

### StringBuilder → ValueStringBuilder (15 files)
Replaced all `new StringBuilder()` with `ValueStringBuilder.Create()` or `stackalloc`:
- ConPVP games: KingOfTheHill, DoubleDom, CTF, BombingRun, TourneyMatch
- ConPVP infrastructure: Tournament, Participant, TourneyParticipant
- ConPVP gumps: ArenaGump, TournamentBracketGump, AcceptTeamGump, ConfirmSignupGump
- Commands: Handlers, Logging, Add
- Other: TownCrier, SpeechLogGump, TestCenter

Key patterns:
- `sb = new StringBuilder()` reassignment → `sb.Reset()`
- `sb.AppendFormat("{0:N0}", value)` → `sb.Append($"{value:N0}")`
- `sb.Append(x).Append(y)` chains → separate statements (VSB returns void)

### Create() → stackalloc (10 files)
Converted heap-allocated builders to stackalloc where output is bounded:
- ClientVersion (32), MapSelection (160), HouseRaffleStone (48)
- HolySense (96), UnholySense (96), ClientVerification (192)
- AcceptTeamGump (64), ConfirmSignupGump (64)
- BaseWeapon (160), BaseArmor (128)

### Loop optimizations (2 files)
Hoisted `ValueStringBuilder` creation outside loops with `Reset()` per iteration:
- TourneyMatch.cs: `using var` inside for loop → stackalloc before loop
- ArenaGump.cs: `Create()` + `Dispose()` per iteration → stackalloc before loop

### Append chain → interpolation (5 files)
Converted multi-line `Append()` chains to `Append($"...")`:
- BountyMessage.cs: title switch (6 cases), paragraph (15→1 Append), description lines, closing
- AcceptTeamGump, ConfirmSignupGump, TournamentBracketGump: tournament type strings
- AdminGump: comment/tag formatting in loops

### Documentation
- `dev-docs/string-handling.md`: Full reference — construction, interpolation, disposal, decision guide
- `dev-docs/claude-skills/modernuo-string-handling.md`: Claude skill with quick reference
- `CLAUDE.md`: Added rule 17 (no StringBuilder), dev-docs table entry, skills table entry
- `dev-docs/code-standards.md`: Updated memory management section

## Test Plan

- [x] `dotnet build` — 0 errors, 0 warnings
- [x] `dotnet test` — 940/940 tests pass
- [x] 28 ValueStringBuilder tests covering all reconciliation scenarios:
  - Stackalloc no-grow, stackalloc with grow (→pool transition)
  - Heap no-grow, heap with grow, heap double grow
  - Pre-existing content with and without grow
  - Sequential multiple `Append($"...")` calls
  - Mixed plain + interpolated Append
  - Empty interpolation, literal-only, format specifiers
  - Null string holes, ISpanFormattable types
  - Dispose after stackalloc→pool grow
2026-03-22 14:23:44 -07:00

297 lines
10 KiB
C#

/*************************************************************************
* ModernUO *
* Copyright 2019-2026 - ModernUO Development Team *
* Email: hi@modernuo.com *
* File: ClientVersion.cs *
* *
* This program is free software: you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation, either version 3 of the License, or *
* (at your option) any later version. *
* *
* You should have received a copy of the GNU General Public License *
* along with this program. If not, see <http://www.gnu.org/licenses/>. *
*************************************************************************/
using System;
using System.Collections.Generic;
using System.Runtime.CompilerServices;
using Server.Network;
using Server.Text;
namespace Server;
public class ClientVersion : IComparable<ClientVersion>, IComparer<ClientVersion>, IEquatable<ClientVersion>
{
public static readonly ClientVersion Version500a = new("5.0.0a");
public static readonly ClientVersion Version502b = new("5.0.2b");
public static readonly ClientVersion Version6000 = new("6.0.0.0");
public static readonly ClientVersion Version6000KR = new("66.55.38"); // KR 2.44.0.15 (First release)
public static readonly ClientVersion Version6017 = new("6.0.1.7");
public static readonly ClientVersion Version6050 = new("6.0.5.0");
public static readonly ClientVersion Version60142 = new("6.0.14.2");
public static readonly ClientVersion Version60142KR = new("66.55.53"); // KR 2.59.0.2
public static readonly ClientVersion Version7000 = new("7.0.0.0");
public static readonly ClientVersion Version7090 = new("7.0.9.0");
public static readonly ClientVersion Version70120 = new("7.0.12.0"); // Plant localization change
public static readonly ClientVersion Version70130 = new("7.0.13.0");
public static readonly ClientVersion Version70160 = new("7.0.16.0");
public static readonly ClientVersion Version70300 = new("7.0.30.0");
public static readonly ClientVersion Version70331 = new("7.0.33.1");
public static readonly ClientVersion Version704565 = new("7.0.45.65");
public static readonly ClientVersion Version70500 = new("7.0.50.0");
public static readonly ClientVersion Version70610 = new("7.0.61.0");
public static readonly ClientVersion Version70654 = new("7.0.65.4"); // Insufficient mana change
public ClientVersion(int maj, int min, int rev, int pat, ClientType type = ClientType.Classic)
{
if (maj >= 67)
{
Major = maj - 60;
Type = ClientType.SA;
}
else
{
Major = maj;
Type = maj == 66 ? ClientType.KR : type;
}
Minor = min;
Revision = rev;
Patch = pat;
SourceString = ToStringImpl().Intern();
}
public ClientVersion(string fmt)
{
fmt = fmt.ToLower();
SourceString = fmt.Intern();
try
{
var br1 = fmt.IndexOfOrdinal('.');
var br2 = fmt.IndexOf('.', br1 + 1);
var br3 = br2 + 1;
while (br3 < fmt.Length && char.IsDigit(fmt, br3))
{
br3++;
}
Major = Utility.ToInt32(fmt.AsSpan()[..br1]);
Minor = Utility.ToInt32(fmt.AsSpan(br1 + 1, br2 - br1 - 1));
Revision = Utility.ToInt32(fmt.AsSpan(br2 + 1, br3 - br2 - 1));
if (br3 < fmt.Length)
{
if (Major <= 5 && Minor <= 0 && Revision <= 6) // Anything before 5.0.7
{
if (!char.IsWhiteSpace(fmt, br3))
{
Patch = fmt[br3] - 'a';
}
}
else
{
Patch = Utility.ToInt32(fmt.AsSpan(br3 + 1, fmt.Length - br3 - 1));
}
}
if (Major == 66)
{
Type = ClientType.KR;
}
else if (Major > 66)
{
Major -= 60;
Type = ClientType.SA;
}
else if (fmt.InsensitiveContains("third dawn") ||
fmt.InsensitiveContains("uo:td") ||
fmt.InsensitiveContains("uotd") ||
fmt.InsensitiveContains("uo3d") ||
fmt.InsensitiveContains("uo:3d"))
{
Type = ClientType.UOTD;
}
}
catch
{
Major = 0;
Minor = 0;
Revision = 0;
Patch = 0;
Type = ClientType.Classic;
}
}
public int Major { get; }
public int Minor { get; }
public int Revision { get; }
public int Patch { get; }
public ClientType Type { get; }
public string SourceString { get; }
public int CompareTo(ClientVersion o)
{
if (o == null)
{
return 1;
}
if (Major > o.Major)
{
return 1;
}
if (Major < o.Major)
{
return -1;
}
if (Minor > o.Minor)
{
return 1;
}
if (Minor < o.Minor)
{
return -1;
}
if (Revision > o.Revision)
{
return 1;
}
if (Revision < o.Revision)
{
return -1;
}
// Don't test patch for EC since it is always 0 but compatible with classic non-zero
if (Type == ClientType.SA || o.Type == ClientType.SA)
{
return 0;
}
if (Patch > o.Patch)
{
return 1;
}
if (Patch < o.Patch)
{
return -1;
}
return 0;
}
int IComparer<ClientVersion>.Compare(ClientVersion x, ClientVersion y) => Compare(x, y);
public static bool operator >=(ClientVersion l, ClientVersion r) => Compare(l, r) >= 0;
public static bool operator >(ClientVersion l, ClientVersion r) => Compare(l, r) > 0;
public static bool operator <=(ClientVersion l, ClientVersion r) => Compare(l, r) <= 0;
public static bool operator <(ClientVersion l, ClientVersion r) => Compare(l, r) < 0;
public static bool operator ==(ClientVersion l, ClientVersion r) => Equals(l, r);
public static bool operator !=(ClientVersion l, ClientVersion r) => !Equals(l, r);
private string ToStringImpl()
{
using var builder = new ValueStringBuilder(stackalloc char[32]);
if (Type == ClientType.SA)
{
builder.Append($"{Major + 60:00}.{Minor:00}.{Revision:00}");
}
else if (Major > 5 || Minor > 0 || Revision > 6)
{
builder.Append($"{Major}.{Minor}.{Revision}.{Patch}");
}
else if (Patch > 0)
{
builder.Append($"{Major}.{Minor}.{Revision}{(char)('a' + (Patch - 1))}");
}
else
{
builder.Append($"{Major}.{Minor}.{Revision}");
}
if (Type == ClientType.UOTD)
{
builder.Append(" uotd");
}
return builder.ToString();
}
public override string ToString() => SourceString;
public static bool IsNull(object x) => ReferenceEquals(x, null);
public static int Compare(ClientVersion a, ClientVersion b)
{
if (IsNull(a) && IsNull(b))
{
return 0;
}
if (IsNull(a))
{
return -1;
}
if (IsNull(b))
{
return 1;
}
return a.CompareTo(b);
}
public ProtocolChanges ProtocolChanges
{
[MethodImpl(MethodImplOptions.AggressiveInlining)]
get => this switch
{
var v when v.Type is ClientType.KR && v >= Version60142KR => ProtocolChanges.Version60142,
var v when v.Type is ClientType.KR => ProtocolChanges.Version6000,
var v when v >= Version70610 => ProtocolChanges.Version70610,
var v when v >= Version70500 => ProtocolChanges.Version70500,
var v when v >= Version704565 => ProtocolChanges.Version704565,
var v when v >= Version70331 => ProtocolChanges.Version70331,
var v when v >= Version70300 => ProtocolChanges.Version70300,
var v when v >= Version70160 => ProtocolChanges.Version70160,
var v when v >= Version70130 => ProtocolChanges.Version70130,
var v when v >= Version7090 => ProtocolChanges.Version7090,
var v when v >= Version7000 => ProtocolChanges.Version7000,
var v when v >= Version60142 => ProtocolChanges.Version60142,
var v when v >= Version6017 => ProtocolChanges.Version6017,
var v when v >= Version6000 => ProtocolChanges.Version6000,
var v when v >= Version502b => ProtocolChanges.Version502b,
_ => ProtocolChanges.Version500a, // We do not support versions lower than 5.0.0a
};
}
public bool Equals(ClientVersion other) =>
!ReferenceEquals(null, other) && (ReferenceEquals(this, other) || Major == other.Major &&
Minor == other.Minor && Revision == other.Revision && Patch == other.Patch && Type == other.Type);
public override bool Equals(object obj) =>
!ReferenceEquals(null, obj) &&
(ReferenceEquals(this, obj) || obj.GetType() == GetType() && Equals((ClientVersion)obj));
public override int GetHashCode() => HashCode.Combine(Major, Minor, Revision, Patch);
}