d7668df5ee
## At a glance
```csharp
public override void GetProperties(IPropertyList list)
{
base.GetProperties(list);
// Accumulate any number of free-text lines. On dispose the block flushes via
// AddChunked, splitting across as many OPL properties as needed so none can
// overflow the legacy 2D client's per-property buffer (which would crash it).
using var block = list.TextBlock();
if (luck > 0)
{
block.Add($"Luck Bonus: +{luck}%"); // zero-alloc interpolation
}
block.Add("Cannot be repaired".AsSpan()); // plain text, no string allocation
// Already holding a '\n'-joined string? Skip the builder and chunk directly:
// list.AddChunked(description);
}
```
## What
Adds a safe path for emitting **variable-length, free-form (non-cliloc) tooltip text**:
- **`ObjectPropertyList.Add(ReadOnlySpan<char>)`** overloads — append raw text with no string allocation. Makes the old single-arg `Add(string)` redundant (a `string` binds to the span overload implicitly), so it's dropped.
- **`AddChunked(ReadOnlySpan<char>)`** on `IPropertyList` — splits newline-joined text at `\n` boundaries across as many passthrough-cliloc properties as needed, so no single property exceeds the cap.
- **`OplTextBlock`** (`ref struct`) + **`IPropertyList.TextBlock()`** — an ergonomic builder that accumulates `\n`-joined lines (with a zero-alloc interpolated `Add($"...")` overload) and flushes via `AddChunked` on dispose. Usage: `using var block = list.TextBlock();`.
- **`MaxArgumentLength` (504)** — per-property cap with a hard backstop that clamps + logs anything that slips through.
## Why
The legacy 2D client copies each OPL property's text into a fixed ~512-char (1024-byte) buffer. A single property longer than that smashes an adjacent world object's vtable on the client heap and crashes the client. `AddChunked`/`OplTextBlock` keep multi-line content safely under the cap instead of risking one oversized `Add`.
## Docs
- `dev-docs/property-lists.md` — new "Multi-Line Free Text" deep-dive section; corrected the stale `IPropertyList` listing.
- `dev-docs/claude-skills/modernuo-property-lists.md` — condensed pattern + anti-pattern.
## Tests
9 tests pass (`OplTextBlockTests`, `ObjectPropertyListSpanAddTests`): line joining, empty-line skipping, no-line no-op, zero-alloc interpolation, and long-content chunking staying under `MaxArgumentLength`. Full `UOContent` build is green, confirming dropping `Add(string)` breaks no call sites.
113 lines
3.8 KiB
C#
113 lines
3.8 KiB
C#
/*************************************************************************
|
|
* ModernUO *
|
|
* Copyright 2019-2026 - ModernUO Development Team *
|
|
* Email: hi@modernuo.com *
|
|
* File: OplTextBlock.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.Runtime.CompilerServices;
|
|
using Server.Text;
|
|
|
|
namespace Server;
|
|
|
|
// Accumulates '\n'-joined free-text lines and emits them on dispose via AddChunked, which splits
|
|
// into as many cycling passthrough entries as needed so no single OPL property exceeds the legacy
|
|
// client's per-property buffer (ObjectPropertyList.MaxArgumentLength).
|
|
// Use with `using var block = list.TextBlock();`. ref struct: single-threaded OPL build only.
|
|
public ref struct OplTextBlock
|
|
{
|
|
private readonly IPropertyList _list;
|
|
internal ValueStringBuilder _builder;
|
|
private bool _any;
|
|
|
|
internal OplTextBlock(IPropertyList list)
|
|
{
|
|
_list = list;
|
|
_builder = ValueStringBuilder.Create();
|
|
_any = false;
|
|
}
|
|
|
|
public void Add(scoped ReadOnlySpan<char> line)
|
|
{
|
|
if (line.IsEmpty)
|
|
{
|
|
return;
|
|
}
|
|
|
|
_builder.Append(line);
|
|
_builder.Append('\n', 1); // ValueStringBuilder has no single-char Append
|
|
_any = true;
|
|
}
|
|
|
|
// Zero-alloc interpolated overload: block.Add($"Luck Bonus: +{v}%").
|
|
public void Add([InterpolatedStringHandlerArgument("")] scoped ref OplInterpolationHandler handler)
|
|
{
|
|
var wrote = handler._wrote;
|
|
this = handler._block; // reconcile possibly-grown builder
|
|
if (wrote)
|
|
{
|
|
_builder.Append('\n', 1);
|
|
_any = true;
|
|
}
|
|
}
|
|
|
|
public void Dispose()
|
|
{
|
|
if (_any)
|
|
{
|
|
// Strip the trailing '\n' (Length >= 2 whenever _any: content + separator).
|
|
// AddChunked splits across multiple properties so a long block never overflows the
|
|
// legacy client's per-property tooltip buffer.
|
|
_list.AddChunked(_builder.AsSpan(0, _builder.Length - 1));
|
|
}
|
|
|
|
_builder.Dispose();
|
|
}
|
|
|
|
[InterpolatedStringHandler]
|
|
public ref struct OplInterpolationHandler
|
|
{
|
|
internal OplTextBlock _block;
|
|
internal bool _wrote;
|
|
|
|
public OplInterpolationHandler(int literalLength, int formattedCount, OplTextBlock block)
|
|
{
|
|
_block = block;
|
|
_wrote = false;
|
|
_block._builder.EnsureCapacity(_block._builder.Length + literalLength + formattedCount * 11);
|
|
}
|
|
|
|
public void AppendLiteral(string value)
|
|
{
|
|
_block._builder.Append(value);
|
|
_wrote = true;
|
|
}
|
|
|
|
public void AppendFormatted<T>(T value)
|
|
{
|
|
_block._builder.Append(value);
|
|
_wrote = true;
|
|
}
|
|
|
|
public void AppendFormatted<T>(T value, string format)
|
|
{
|
|
_block._builder.Append(value, format);
|
|
_wrote = true;
|
|
}
|
|
|
|
public void AppendFormatted(scoped ReadOnlySpan<char> value)
|
|
{
|
|
_block._builder.Append(value);
|
|
_wrote = true;
|
|
}
|
|
}
|
|
}
|