ModernUO/Projects/UOContent.Tests/Tests/Engines/Spawners/SpawnerEntryOwnershipTests.cs
Kamron Batman a52ce6ef70
refactor(spawners): subclass-owned entries, lifecycle hooks, per-entry Disabled flag (#2621)
## Summary

Moves spawner entry storage out of the abstract `BaseSpawner` into the concrete owner, so a spawner subclass can store its own entry type while every stock code path keeps working. Motivation: an out-of-tree spawner (ModernSpawner) needs `ModernSpawnerEntry : SpawnerEntry` with extra fields; today `BaseSpawner` owns `List<SpawnerEntry>` and a family of non-virtual members, and the serialization generator constructs list elements from the declared element type, so storage has to live in the class that declares the concrete list.

### What changed

- **`BaseSpawner` v13** no longer owns `_entries`. It reads entries through an abstract view and mutates them through an owner contract (`BaseSpawner.Entries.cs`):
  `Entries` (`IReadOnlyList<SpawnerEntry>`, `[IgnoreDupe]`), `EntrySpan` (`ReadOnlySpan<SpawnerEntry>` for hot loops), `CreateEntry`, `AddEntryCore`, `RemoveEntryCore`, `ClearEntriesCore`, `AdoptEntries`, `CloneEntry`, `TransferSpawned`, plus public `RemoveAllEntries()`, `CopyEntriesTo(target)` and protected `RebuildSpawned()`. Every loop inside `BaseSpawner` is an indexed `for` over `EntrySpan`.
- **`Spawner` v2** owns `[SerializedIgnoreDupe] List<SpawnerEntry> _entryList` (generated `EntryList`, protected). `ProximitySpawner`/`RegionSpawner` inherit it unchanged. The `Spawned` rebuild and timer re-arm moved from the base `[AfterDeserialization]` (which runs before derived fields are read) into `Spawner`'s.
- **Save migration**: `MigrateFrom(V12Content)` (and the v10/v11/legacy readers) hand the old list to the owner via `AdoptEntries`; `Spawner.MigrateFrom(V1Content)` restores its own fields and leaves the adopted list alone. Three v12/v1/v0 save blobs captured before the change are committed as fixtures and loaded by tests.
- **Lifecycle hooks** (`BaseSpawner.Hooks.cs`, all no-op by default): `OnStarted`, `OnStopped`, `OnBeforeSpawn(entry)` veto, `OnConfigureSpawned(entry, spawned)` before positioning, entry-aware `GetSpawnPosition(entry, spawned, map)`, `OnSpawned(entry, spawned)`, `OnSpawnedDeath(entry, spawned, killer)`. `BaseCreature.OnDeath` calls `NotifySpawnedDeath` before base death (which deletes the mobile and unlinks the spawner). `Start()` and the `NextSpawn` setter share one start core so `OnStarted` fires on both.
- **`SpawnerEntry` v2**: per-entry `Disabled` (XmlSpawner's entry "lock"), stored inverted so the common case writes nothing in binary or JSON; skipped by weighted selection, live spawns untouched; toggle button per row in `SpawnerGump`. `SetParent` is public and `Parent` is protected so an out-of-tree entry subclass can adopt and dirty-track.
- **DTO**: `SpawnerDto` loses `Entries`; each concrete record declares its own `entries` at the same JSON order, so `Distribution/Data/Spawns/**` is byte-identical. Import adopts the deserialized entry objects instead of recreating them through `AddEntry`, which is what preserves subtype fields (and `disabled`).

### Breaking changes and behaviour changes

- **API:** `BaseSpawner.Entries` is `IReadOnlyList<SpawnerEntry>` instead of `List<SpawnerEntry>`. The generated `AddToEntries`/`RemoveFromEntries`/`InsertIntoEntries`/`RemoveFromEntriesAt`/`ClearEntries` helpers on `BaseSpawner` are gone; use `AddEntry`/`RemoveEntry`/`RemoveAllEntries`/`CopyEntriesTo`. `RemoveAllEntries()` deletes the entries' live spawns as well as the entries (the old generated `ClearEntries()` only cleared the list), which is why it has a new name rather than the old one.
- `SpawnerControllerGump` "copy entries" now goes through `CopyEntriesTo`, which deletes the target's live spawns (previously it cleared the list and left the spawns orphaned) and is a no-op when source == target (previously that wiped the source).
- `RemoveEntry` with an entry the spawner does not own is now a no-op (previously it deleted that entry's spawns).
- `Respawn()` honours `Disabled` because it calls `Spawn()`; `Spawn(int index)`, `RemoveSpawn`, and `RemoveSpawns` ignore it.
- Copying entries between spawners no longer forces a 1-second first spawn; the target re-arms on its normal delay.
- Subclasses that own a different entry list than `Spawner`'s must call `RebuildSpawned()` from their own `[AfterDeserialization]` (`Spawner`'s call runs before their list is read) and, when converting adopted entries into their own type, carry live spawns across with `TransferSpawned`. The in-repo test subclass demonstrates both.

### Performance

Manual harness (`Benchmark_SpawnPath_Manual`, skipped by default): 100k calls, entries all full so `Spawn()` does selection only.

| Path | Before (4bad0cc9e) | After |
|---|---|---|
| `Spawn()` 1 entry | 48.7 ns | 53.2 ns (within run-to-run noise) |
| `Spawn()` 10 entries | 243.7 ns | 153.1 ns |
| `Spawn()` 50 entries | 1077.6 ns | 645.1 ns |
| `Remove()` 10 entries | 139.6 ns | 83.6 ns |

Hooks are no-ops for stock spawners; `OnMovement` is untouched.

### Tests

- `SpawnerEntryOwnershipTests` (add/remove/clear, start after stop, dupe, copy, self-copy, foreign-entry removal, Disabled binary/JSON)
- `SpawnerHookTests` (hook order for mobiles and items, veto, death notification, `NextSpawn` start, a subclass with its own `List<TestEntry>` round-tripping and duping)
- `SpawnerSaveMigrationTests` (v12 fixtures through `Spawner`, `ProximitySpawner`, `RegionSpawner`; new-format byte-identical round trip with a live spawn reference)
- `SpawnerDtoEntryTests` (compact JSON position of `entries`, `disabled` only when set, import adopts the deserialized objects)
- Existing DTO/JSON/spawn-data tests unchanged. UOContent.Tests 801 passed, Server.Tests 869 passed. Migration schemas regenerated (`BaseSpawner.v13`, `Spawner.v2`, `SpawnerEntry.v2`).

Coverage caveats, stated plainly: v10, v11 and the pre-codegen legacy reader could not be captured as fixtures by the current code; each changed only `_entries = …` → `AdoptEntries(…)` into the same sink the v12 fixtures exercise, and is covered by review. The captured v12 fixtures carry no live spawns, so re-linking live `ISpawnable` references is proven by the new-format round trip, not by a legacy blob. The `SpawnerGump` toggle layout could not be checked in a client; the delete button moved from x=38 to x=46 to make room.
2026-09-11 17:41:08 -07:00

243 lines
7.4 KiB
C#

using System;
using System.Diagnostics;
using System.Linq;
using System.Text.Json;
using Server;
using Server.Engines.Spawners;
using Server.Tests;
using Server.Text;
using Xunit;
namespace UOContent.Tests.Engines.Spawners;
[Collection("Sequential UOContent Tests")]
public class SpawnerEntryOwnershipTests
{
[Fact]
public void Disabled_DefaultsFalse_AndRoundTripsBinary()
{
var spawner = new Spawner(1, TimeSpan.FromMinutes(1), TimeSpan.FromMinutes(2), 0, default, "Rabbit", "Bird");
Assert.False(spawner.Entries[0].Disabled);
Assert.True(spawner.Entries[0].Enabled);
spawner.Entries[1].Disabled = true;
var bytes = SpawnerBlob.Write(spawner);
var loaded = SpawnerBlob.Read<Spawner>(bytes, (Serial)0x40001234);
Assert.Equal(2, loaded.Entries.Count);
Assert.False(loaded.Entries[0].Disabled);
Assert.True(loaded.Entries[1].Disabled);
spawner.Delete();
loaded.Delete();
}
[Fact]
public void Disabled_IsOmittedFromJsonWhenFalse_AndWrittenWhenTrue()
{
var entry = new SpawnerEntry("Rabbit");
var json = JsonSerializer.Serialize(entry, SpawnerJsonSerializer.Options);
Assert.DoesNotContain("disabled", json);
entry.Disabled = true;
json = JsonSerializer.Serialize(entry, SpawnerJsonSerializer.Options);
Assert.Contains("\"disabled\": true", json);
}
[Fact]
public void AddRemoveClear_OperateOnOwnerList()
{
var spawner = new Spawner();
Assert.Empty(spawner.Entries);
var a = spawner.AddEntry("Rabbit", 100, 2, false);
var b = spawner.AddEntry("Bird", 50, 1, false, "Hue 33", null);
Assert.Equal(2, spawner.Entries.Count);
Assert.Same(a, spawner.Entries[0]);
Assert.Equal("Hue 33", spawner.Entries[1].Properties);
spawner.RemoveEntry(a);
Assert.Single(spawner.Entries);
Assert.Same(b, spawner.Entries[0]);
spawner.RemoveAllEntries();
Assert.Empty(spawner.Entries);
spawner.Delete();
}
[Fact]
public void Start_WorksAfterStop_WhenOwnerHasEntries()
{
var spawner = new Spawner(1, TimeSpan.FromMinutes(1), TimeSpan.FromMinutes(2), 0, default, "Rabbit");
Assert.True(spawner.Running);
spawner.Stop();
Assert.False(spawner.Running);
spawner.Start();
Assert.True(spawner.Running);
spawner.Delete();
}
[Fact]
public void Dupe_ClonesEntriesIntoIndependentList()
{
var source = new Spawner(1, TimeSpan.FromMinutes(1), TimeSpan.FromMinutes(2), 0, default, "Rabbit", "Bird");
source.Entries[1].Disabled = true;
var copy = new Spawner();
source.Dupe(copy);
Assert.Equal(2, copy.Entries.Count);
Assert.NotSame(source.Entries[0], copy.Entries[0]);
Assert.Equal("Bird", copy.Entries[1].SpawnedName);
Assert.True(copy.Entries[1].Disabled);
Assert.NotEqual(source.Guid, copy.Guid);
source.AddEntry("Orc", 100, 1, false);
Assert.Equal(2, copy.Entries.Count);
source.Delete();
copy.Delete();
}
[Fact]
public void CopyEntriesTo_ReplacesTargetEntries()
{
var source = new Spawner(1, TimeSpan.FromMinutes(1), TimeSpan.FromMinutes(2), 0, default, "Rabbit");
var target = new Spawner(1, TimeSpan.FromMinutes(1), TimeSpan.FromMinutes(2), 0, default, "Orc", "Troll");
source.CopyEntriesTo(target);
Assert.Single(target.Entries);
Assert.Equal("Rabbit", target.Entries[0].SpawnedName);
Assert.NotSame(source.Entries[0], target.Entries[0]);
source.Delete();
target.Delete();
}
[Fact]
public void CopyEntriesTo_Self_IsNoOp()
{
var spawner = new Spawner(1, TimeSpan.FromMinutes(1), TimeSpan.FromMinutes(2), 0, default, "Rabbit", "Bird");
var first = spawner.Entries[0];
var second = spawner.Entries[1];
spawner.CopyEntriesTo(spawner);
Assert.Equal(2, spawner.Entries.Count);
Assert.Same(first, spawner.Entries[0]);
Assert.Same(second, spawner.Entries[1]);
spawner.Delete();
}
[Fact]
public void RemoveEntry_ForeignEntry_IsIgnored()
{
var a = new Spawner(1, TimeSpan.FromMinutes(1), TimeSpan.FromMinutes(2), 0, default, "Rabbit");
var b = new Spawner(1, TimeSpan.FromMinutes(1), TimeSpan.FromMinutes(2), 0, default, "Bird");
var foreign = b.Entries[0];
var spawned = new Item(0x1f13);
foreign.AddToSpawned(spawned);
a.RemoveEntry(foreign);
Assert.Single(a.Entries);
Assert.Equal("Rabbit", a.Entries[0].SpawnedName);
Assert.Single(b.Entries);
Assert.Same(foreign, b.Entries[0]);
Assert.False(spawned.Deleted);
Assert.Single(foreign.Spawned);
spawned.Delete();
a.Delete();
b.Delete();
}
// Manual: remove the Skip, run, and read the numbers from the thrown assertion.
[Fact(Skip = "manual benchmark")]
public void Benchmark_SpawnPath_Manual()
{
const int iterations = 100_000;
const int warmup = 1_000;
var report = new ValueStringBuilder(stackalloc char[512]);
report.Append('\n', 1);
foreach (var entryCount in new[] { 1, 10, 50 })
{
var spawner = new Spawner(1000, TimeSpan.FromMinutes(5), TimeSpan.FromMinutes(10));
spawner.MoveToWorld(new Point3D(1500, 1500, 0), Map.Felucca);
// SpawnedMaxCount = 0 keeps every entry full, so Spawn() does selection only.
for (var i = 0; i < entryCount; i++)
{
spawner.AddEntry("Rabbit", 100, 0, false);
}
for (var i = 0; i < warmup; i++)
{
spawner.Spawn();
}
var sw = Stopwatch.StartNew();
for (var i = 0; i < iterations; i++)
{
spawner.Spawn();
}
sw.Stop();
var nsPerCall = sw.Elapsed.TotalMilliseconds * 1_000_000.0 / iterations;
report.Append(
$"Spawn() entries={entryCount,2}: {nsPerCall,8:F1} ns/call ({iterations} iterations, {sw.ElapsedMilliseconds} ms total)\n"
);
spawner.Delete();
}
{
var spawner = new Spawner(1000, TimeSpan.FromMinutes(5), TimeSpan.FromMinutes(10));
spawner.MoveToWorld(new Point3D(1500, 1500, 0), Map.Felucca);
for (var i = 0; i < 10; i++)
{
spawner.AddEntry("Rabbit", 100, 1, false);
}
spawner.Spawn();
Assert.Single(spawner.Spawned);
var rabbit = spawner.Spawned.Keys.First();
for (var i = 0; i < warmup; i++)
{
spawner.Remove(rabbit);
}
var sw = Stopwatch.StartNew();
for (var i = 0; i < iterations; i++)
{
spawner.Remove(rabbit);
}
sw.Stop();
var nsPerCall = sw.Elapsed.TotalMilliseconds * 1_000_000.0 / iterations;
report.Append(
$"Remove(ISpawnable) entries=10: {nsPerCall,8:F1} ns/call ({iterations} iterations, {sw.ElapsedMilliseconds} ms total)\n"
);
(rabbit as Mobile)?.Delete();
spawner.Delete();
}
var summary = report.ToString();
report.Dispose();
throw new Xunit.Sdk.XunitException(summary);
}
}