From 69ba9486b661386112d2d1ab76f2c6e80598738f Mon Sep 17 00:00:00 2001 From: Erik Date: Mon, 3 Aug 2026 18:57:17 +0200 Subject: [PATCH] feat(chat): port retail's @pklite client command (EnterPkLite 0x028F) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit acdream never implemented @pklite. It is a CLIENT command in retail, not a server one — ACE has no pklite text-command handler — so typing it forwarded as inert chat text that the server ignored. Retail: ClientCommunicationSystem::DoPKLite @0x0057A490 rejects with WeenieError 0x507 when ACCWeenieObject::IsPlayerKiller @0x0058C910 is true (that returns true when EITHER the PK bit 0x20 OR the PKLite bit 0x2000000 is set), prints "Please see @help pklite for more..." and sends nothing if given any argument text, and otherwise calls CM_Character::Event_EnterPKLite @0x006A13F0 — a bare 12-byte parameterless game action, opcode 0x28F, the same shape as Event_LoginCompleteNotification beside it. Verb string at 0x007E16B0, help text at 0x007DF0C8, failure string at 0x007D31E8; one verb, no alias. HasPlayerFlag is a tri-state (null = the local PublicWeenieDesc has not arrived). The existing arena gates compare `== false` because they reject on a known-FALSE flag; retail's DoPKLite gates the other way, rejecting on known-TRUE. So this case compares `== true` on either bit: an indeterminate description sends rather than blocks, which matches retail trusting the server instead of inventing a client-side suppression rule. Landed as its own commit because it is retail-faithful on its own merits, but the motivation is C4 route 2: ACE advances SequenceType.ObjectForcePosition in exactly two places, and the only reachable one is Player.HandleActionEnterPkLite's entry-collision bump (allow_pkl_bump, default on). Every admin teleport advances ObjectTeleport instead, so @teleto-style displacement exercises route 3, not route 2. Without this command route 2 has no connected acceptance gate at all. Gates: complete Release solution 10,867 passed / 4 skipped / 0 failed (9966b531 baseline 10,858/4/0; +9 = the 9 tests added). Coverage includes both known-true rejections, the known-false success case, the tri-state unknown case, the 12-byte wire envelope, and @pklite resolving as ClientHandled rather than falling through to the server-text path. Co-Authored-By: Claude Opus 5 --- .../Net/LiveSessionCommandRouter.cs | 3 +- .../Net/LiveSessionRuntimeFactory.cs | 3 +- src/AcDream.App/UI/ClientCommandController.cs | 28 ++++++-- .../Messages/ClientCommandRequests.cs | 6 ++ src/AcDream.Core.Net/WorldSession.cs | 7 ++ .../ClientCommandId.cs | 1 + .../Panels/Chat/RetailClientCommandCatalog.cs | 10 +++ .../Net/LiveSessionCommandRouterTests.cs | 3 +- .../UI/ClientCommandControllerTests.cs | 65 ++++++++++++++++++- .../Messages/ClientCommandRequestsTests.cs | 1 + .../WorldSessionChatTests.cs | 13 ++++ .../Panels/Chat/ChatCommandRouterTests.cs | 12 ++++ .../Chat/RetailClientCommandCatalogTests.cs | 2 + 13 files changed, 146 insertions(+), 8 deletions(-) diff --git a/src/AcDream.App/Net/LiveSessionCommandRouter.cs b/src/AcDream.App/Net/LiveSessionCommandRouter.cs index 278e6f10..757ec2a1 100644 --- a/src/AcDream.App/Net/LiveSessionCommandRouter.cs +++ b/src/AcDream.App/Net/LiveSessionCommandRouter.cs @@ -340,7 +340,8 @@ internal sealed class LiveSessionCommandRouter : ILiveSessionCommandRouting ClearDesiredComponents: () => InvokeClient(static b => b.ClearDesiredComponents()), HasOpenVendor: () => ReadClient(static b => b.HasOpenVendor(), false), FillComponentBuyList: (componentId, targetCount) => - InvokeClient(b => b.FillComponentBuyList(componentId, targetCount))); + InvokeClient(b => b.FillComponentBuyList(componentId, targetCount)), + EnterPkLite: () => InvokeClient(static b => b.EnterPkLite())); private bool InvokeClient(Action invoke) { diff --git a/src/AcDream.App/Net/LiveSessionRuntimeFactory.cs b/src/AcDream.App/Net/LiveSessionRuntimeFactory.cs index 9ef28c63..8977a972 100644 --- a/src/AcDream.App/Net/LiveSessionRuntimeFactory.cs +++ b/src/AcDream.App/Net/LiveSessionRuntimeFactory.cs @@ -376,7 +376,8 @@ internal sealed class LiveSessionRuntimeFactory session.SendClearDesiredComponents(); }, HasOpenVendor: () => false, - FillComponentBuyList: (_, _) => { }), + FillComponentBuyList: (_, _) => { }, + EnterPkLite: session.SendEnterPkLite), _domain.Communication.Chat, _domain.Communication.TurbineChat, PlayerGuid: () => _player.Identity.ServerGuid, diff --git a/src/AcDream.App/UI/ClientCommandController.cs b/src/AcDream.App/UI/ClientCommandController.cs index 08eef64d..35baf83c 100644 --- a/src/AcDream.App/UI/ClientCommandController.cs +++ b/src/AcDream.App/UI/ClientCommandController.cs @@ -57,7 +57,8 @@ public sealed class ClientCommandController Func LastTeller, Action ClearDesiredComponents, Func HasOpenVendor, - Action FillComponentBuyList); + Action FillComponentBuyList, + Action EnterPkLite); private readonly Bindings _bindings; @@ -94,6 +95,22 @@ public sealed class ClientCommandController else _bindings.TeleportToPkLiteArena(); break; + // ClientCommunicationSystem::DoPKLite @ 0x0057A490 rejects with + // WeenieError 0x507 when ACCWeenieObject::IsPlayerKiller @ + // 0x0058C910 is true — that is, when EITHER the PK bit (0x20) OR + // the PKLite bit (0x2000000) is already set. Unlike the arena + // gates above (which reject on a known-false flag and so already + // send on an indeterminate one), this gate must reject only on a + // known-TRUE flag: an unknown/indeterminate PublicWeenieDesc + // still sends, matching retail's send-and-let-the-server-decide + // default for a description that has not arrived yet. + case ClientCommandId.EnterPkLite: + if (HasPlayerFlag(EntityCollisionFlags.IsPK) == true + || HasPlayerFlag(EntityCollisionFlags.IsPKLite) == true) + _bindings.ShowWeenieError(0x0507u); + else + _bindings.EnterPkLite(); + break; case ClientCommandId.HouseRecall: _bindings.TeleportToHouse(); break; @@ -652,9 +669,12 @@ public sealed class ClientCommandController + "@afk msg - Set the message that will be sent to players that send you directed chat while you are in AFK mode. Issuing \"@afk msg\" with no message will set your AFK message back to the default. Your custom AFK message is limited to 192 characters.\n"; /// - /// Null means the local PublicWeenieDesc has not arrived yet. Retail only - /// rejects when it has a player object and the required bit is absent, so - /// unknown follows the same send-and-let-the-server-decide path. + /// Tri-state: null means the local PublicWeenieDesc has not arrived yet. + /// Callers must gate on the direction retail actually rejects in — some + /// gates (the arena recalls) reject on a known-false flag, others (@pklite) + /// reject on a known-true flag — so an unknown flag always falls through + /// to sending, matching retail's send-and-let-the-server-decide default + /// for a description that has not arrived yet. /// private bool? HasPlayerFlag(EntityCollisionFlags flag) { diff --git a/src/AcDream.Core.Net/Messages/ClientCommandRequests.cs b/src/AcDream.Core.Net/Messages/ClientCommandRequests.cs index 022817af..a9bd06aa 100644 --- a/src/AcDream.Core.Net/Messages/ClientCommandRequests.cs +++ b/src/AcDream.Core.Net/Messages/ClientCommandRequests.cs @@ -14,6 +14,7 @@ public static class ClientCommandRequests public const uint MarketplaceOpcode = 0x028Du; public const uint PkArenaOpcode = 0x0027u; public const uint PkLiteArenaOpcode = 0x0026u; + public const uint EnterPkLiteOpcode = 0x028Fu; public const uint HouseRecallOpcode = 0x0262u; public const uint MansionRecallOpcode = 0x0278u; public const uint QueryAgeOpcode = 0x01C2u; @@ -54,6 +55,11 @@ public static class ClientCommandRequests public static byte[] BuildPkLiteArena(uint sequence) => BuildParameterless(sequence, PkLiteArenaOpcode); + // CM_Character::Event_EnterPKLite @ 0x006A13F0 — 12-byte parameterless + // game action, opcode 0x28F, identical shape to Event_LoginCompleteNotification. + public static byte[] BuildEnterPkLite(uint sequence) => + BuildParameterless(sequence, EnterPkLiteOpcode); + public static byte[] BuildHouseRecall(uint sequence) => BuildParameterless(sequence, HouseRecallOpcode); diff --git a/src/AcDream.Core.Net/WorldSession.cs b/src/AcDream.Core.Net/WorldSession.cs index a56ce33d..ca01d9ed 100644 --- a/src/AcDream.Core.Net/WorldSession.cs +++ b/src/AcDream.Core.Net/WorldSession.cs @@ -2102,6 +2102,13 @@ public sealed class WorldSession : IDisposable SendGameAction(ClientCommandRequests.BuildPkLiteArena(seq)); } + /// Send retail @pklite / Enter PK Lite request (0x028F). + public void SendEnterPkLite() + { + uint seq = NextGameActionSequence(); + SendGameAction(ClientCommandRequests.BuildEnterPkLite(seq)); + } + /// Send retail personal-house recall (0x0262). public void SendTeleportToHouse() { diff --git a/src/AcDream.UI.Abstractions/ClientCommandId.cs b/src/AcDream.UI.Abstractions/ClientCommandId.cs index 654cc7b6..eca4138a 100644 --- a/src/AcDream.UI.Abstractions/ClientCommandId.cs +++ b/src/AcDream.UI.Abstractions/ClientCommandId.cs @@ -12,6 +12,7 @@ public enum ClientCommandId MarketplaceRecall, PkArenaRecall, PkLiteArenaRecall, + EnterPkLite, HouseRecall, MansionRecall, QueryAge, diff --git a/src/AcDream.UI.Abstractions/Panels/Chat/RetailClientCommandCatalog.cs b/src/AcDream.UI.Abstractions/Panels/Chat/RetailClientCommandCatalog.cs index 4f6610d2..3e872fae 100644 --- a/src/AcDream.UI.Abstractions/Panels/Chat/RetailClientCommandCatalog.cs +++ b/src/AcDream.UI.Abstractions/Panels/Chat/RetailClientCommandCatalog.cs @@ -50,6 +50,14 @@ public static class RetailClientCommandCatalog "/pklarena", "/pklarena (/pla) - Teleports a PKLite player to the PKLite Arena."); + // ClientCommunicationSystem::DoPKLite/HelpPKLite @ 0x0057A490/0x0057A540. + // Retail registers exactly one verb string ("pklite" @ 0x007E16B0) — no + // alias, unlike most of this catalog. + private static readonly Definition PkLite = NoArguments( + ClientCommandId.EnterPkLite, + "/pklite", + "@pklite - Sets your status to Player Killer Lite. Type @help pklite for more details."); + private static readonly Definition HouseRecall = NoArguments( ClientCommandId.HouseRecall, "/house recall", @@ -207,6 +215,7 @@ public static class RetailClientCommandCatalog ["pka"] = PkArena, ["pklarena"] = PkLiteArena, ["pla"] = PkLiteArena, + ["pklite"] = PkLite, ["hor"] = HouseRecall, ["hr"] = HouseRecall, ["hom"] = MansionRecall, @@ -310,6 +319,7 @@ public static class RetailClientCommandCatalog Marketplace.HelpText, PkArena.HelpText, PkLiteArena.HelpText, + PkLite.HelpText, HouseRecall.HelpText, MansionRecall.HelpText, QueryAge.HelpText, diff --git a/tests/AcDream.App.Tests/Net/LiveSessionCommandRouterTests.cs b/tests/AcDream.App.Tests/Net/LiveSessionCommandRouterTests.cs index e59daf1c..d2fd1978 100644 --- a/tests/AcDream.App.Tests/Net/LiveSessionCommandRouterTests.cs +++ b/tests/AcDream.App.Tests/Net/LiveSessionCommandRouterTests.cs @@ -374,5 +374,6 @@ public sealed class LiveSessionCommandRouterTests LastTeller: () => null, ClearDesiredComponents: () => { }, HasOpenVendor: () => false, - FillComponentBuyList: (_, _) => { }); + FillComponentBuyList: (_, _) => { }, + EnterPkLite: () => { }); } diff --git a/tests/AcDream.App.Tests/UI/ClientCommandControllerTests.cs b/tests/AcDream.App.Tests/UI/ClientCommandControllerTests.cs index 5802ad2b..2ac59d71 100644 --- a/tests/AcDream.App.Tests/UI/ClientCommandControllerTests.cs +++ b/tests/AcDream.App.Tests/UI/ClientCommandControllerTests.cs @@ -58,6 +58,68 @@ public sealed class ClientCommandControllerTests Assert.Equal([0x0560u], errors); } + [Fact] + public void EnterPkLite_NonPk_SendsTheRetailGameAction() + { + var calls = new List(); + var errors = new List(); + var controller = NewController(calls, errors, playerBitfield: 0x8u); + + controller.Execute(new ExecuteClientCommandCmd( + ClientCommandId.EnterPkLite, string.Empty)); + + Assert.Equal(["pklite"], calls); + Assert.Empty(errors); + } + + [Fact] + public void EnterPkLite_AlreadyPk_ShowsRetailFailureWithoutSending() + { + var calls = new List(); + var errors = new List(); + // 0x20 = ACCWeenieObject::IsPK bit only. + var controller = NewController(calls, errors, playerBitfield: 0x20u); + + controller.Execute(new ExecuteClientCommandCmd( + ClientCommandId.EnterPkLite, string.Empty)); + + Assert.Empty(calls); + Assert.Equal([0x0507u], errors); + } + + [Fact] + public void EnterPkLite_AlreadyPkLite_ShowsRetailFailureWithoutSending() + { + var calls = new List(); + var errors = new List(); + // 0x2000000 = ACCWeenieObject::IsPKLite bit only. + var controller = NewController(calls, errors, playerBitfield: 0x2000000u); + + controller.Execute(new ExecuteClientCommandCmd( + ClientCommandId.EnterPkLite, string.Empty)); + + Assert.Empty(calls); + Assert.Equal([0x0507u], errors); + } + + [Fact] + public void EnterPkLite_UnknownPlayerDescription_SendsRatherThanRejects() + { + // Tri-state decision: retail's DoPKLite only rejects when + // IsPlayerKiller() is TRUE. An indeterminate PublicWeenieDesc (not + // yet arrived) must send, not reject -- the opposite direction from + // the arena recalls, which gate on the flag being known-true. + var calls = new List(); + var errors = new List(); + var controller = NewController(calls, errors, playerBitfield: null); + + controller.Execute(new ExecuteClientCommandCmd( + ClientCommandId.EnterPkLite, string.Empty)); + + Assert.Equal(["pklite"], calls); + Assert.Empty(errors); + } + [Fact] public void MissingPlayerDescription_DoesNotInventAClientRejection() { @@ -314,6 +376,7 @@ public sealed class ClientCommandControllerTests () => lastTeller, () => calls.Add("clearcomps"), () => vendorOpen, - (category, price) => calls.Add($"fillcomps:{category}:{price}"))); + (category, price) => calls.Add($"fillcomps:{category}:{price}"), + () => calls.Add("pklite"))); } } diff --git a/tests/AcDream.Core.Net.Tests/Messages/ClientCommandRequestsTests.cs b/tests/AcDream.Core.Net.Tests/Messages/ClientCommandRequestsTests.cs index 4804b64f..6142171a 100644 --- a/tests/AcDream.Core.Net.Tests/Messages/ClientCommandRequestsTests.cs +++ b/tests/AcDream.Core.Net.Tests/Messages/ClientCommandRequestsTests.cs @@ -10,6 +10,7 @@ public sealed class ClientCommandRequestsTests { ClientCommandRequests.BuildMarketplace, ClientCommandRequests.MarketplaceOpcode }, { ClientCommandRequests.BuildPkArena, ClientCommandRequests.PkArenaOpcode }, { ClientCommandRequests.BuildPkLiteArena, ClientCommandRequests.PkLiteArenaOpcode }, + { ClientCommandRequests.BuildEnterPkLite, ClientCommandRequests.EnterPkLiteOpcode }, { ClientCommandRequests.BuildHouseRecall, ClientCommandRequests.HouseRecallOpcode }, { ClientCommandRequests.BuildMansionRecall, ClientCommandRequests.MansionRecallOpcode }, { ClientCommandRequests.BuildSuicide, ClientCommandRequests.SuicideOpcode }, diff --git a/tests/AcDream.Core.Net.Tests/WorldSessionChatTests.cs b/tests/AcDream.Core.Net.Tests/WorldSessionChatTests.cs index 3c2601f3..c90c06c2 100644 --- a/tests/AcDream.Core.Net.Tests/WorldSessionChatTests.cs +++ b/tests/AcDream.Core.Net.Tests/WorldSessionChatTests.cs @@ -89,4 +89,17 @@ public sealed class WorldSessionChatTests Assert.NotNull(captured); Assert.Equal(InteractRequests.BuildTeleToLifestone(1), captured); } + + [Fact] + public void SendEnterPkLite_EmitsRetailGameAction() + { + using var session = NewSession(); + byte[]? captured = null; + session.GameActionCapture = body => captured = body; + + session.SendEnterPkLite(); + + Assert.NotNull(captured); + Assert.Equal(ClientCommandRequests.BuildEnterPkLite(1), captured); + } } diff --git a/tests/AcDream.UI.Abstractions.Tests/Panels/Chat/ChatCommandRouterTests.cs b/tests/AcDream.UI.Abstractions.Tests/Panels/Chat/ChatCommandRouterTests.cs index 54093d80..87b33be3 100644 --- a/tests/AcDream.UI.Abstractions.Tests/Panels/Chat/ChatCommandRouterTests.cs +++ b/tests/AcDream.UI.Abstractions.Tests/Panels/Chat/ChatCommandRouterTests.cs @@ -87,6 +87,18 @@ public class ChatCommandRouterTests Assert.Contains(log.Snapshot(), entry => entry.Text == "Usage: /lifestone"); } + [Fact] + public void PkLiteAlias_ResolvesAsClientHandled_NotTheServerTextPath() + { + var (vm, _, bus) = Fixture(); + + var outcome = ChatCommandRouter.Submit("@pklite", vm, bus, ChatChannelKind.Say); + + Assert.Equal(SubmitOutcome.ClientHandled, outcome); + var command = Assert.IsType(Assert.Single(bus.Published)); + Assert.Equal(ClientCommandId.EnterPkLite, command.Command); + } + [Fact] public void UnknownSlashVerb_RoutesThroughExplicitServerCommand() { diff --git a/tests/AcDream.UI.Abstractions.Tests/Panels/Chat/RetailClientCommandCatalogTests.cs b/tests/AcDream.UI.Abstractions.Tests/Panels/Chat/RetailClientCommandCatalogTests.cs index b66d82ae..87dcb439 100644 --- a/tests/AcDream.UI.Abstractions.Tests/Panels/Chat/RetailClientCommandCatalogTests.cs +++ b/tests/AcDream.UI.Abstractions.Tests/Panels/Chat/RetailClientCommandCatalogTests.cs @@ -28,6 +28,8 @@ public sealed class RetailClientCommandCatalogTests [InlineData("/pka", ClientCommandId.PkArenaRecall)] [InlineData("/pklarena", ClientCommandId.PkLiteArenaRecall)] [InlineData("/pla", ClientCommandId.PkLiteArenaRecall)] + [InlineData("/pklite", ClientCommandId.EnterPkLite)] + [InlineData("@pklite", ClientCommandId.EnterPkLite)] [InlineData("/hor", ClientCommandId.HouseRecall)] [InlineData("/hr", ClientCommandId.HouseRecall)] [InlineData("/hom", ClientCommandId.MansionRecall)]