diff --git a/include/modlock/gameinterop/ability_owner_guard.h b/include/modlock/gameinterop/ability_owner_guard.h index b22d5d7a..820b2f3d 100644 --- a/include/modlock/gameinterop/ability_owner_guard.h +++ b/include/modlock/gameinterop/ability_owner_guard.h @@ -40,6 +40,9 @@ struct OwnedAbility { void* entity = nullptr; // index is the ability's entity index. uint32_t index = 0; + // handle is the ability's own handle, index and serial, or the invalid + // handle when its identity cannot prove one. + uint32_t handle = kInvalidEHandleIndex; // owner is the handle m_hOwnerEntity holds. uint32_t owner = kInvalidEHandleIndex; // state is what the handle names. @@ -62,22 +65,76 @@ using AbilityClasses = std::unordered_map; const BoundedReader& read, AbilityClasses& classes); +// HeldAbilities remembers, for each player slot, every ability the guard let +// through to that player's client, by index and serial. Such a client may +// hold the ability: the server counts an entity it sent as held, and clearing +// its bit later makes the client drop an entity the server still updates, +// which closes the client with "CopyExistingEntity: missing client entity". +// A record lasts until the ability leaves the world, another entity takes its +// index, or the slot's connection ends. +class MODLOCK_API HeldAbilities { + public: + // Track starts a pass for slot. A slot no connection occupies, or occupied + // by a connection of another generation than the one recorded, holds + // nothing. + void Track(int32_t slot, bool occupied, uint32_t generation); + + // Holds reports whether the client in slot may hold ability. An ability + // whose own handle is unknown is held when anything at its index is. + [[nodiscard]] bool Holds(int32_t slot, const OwnedAbility& ability) const; + + // Hold records that the client in slot receives ability. + void Hold(int32_t slot, const OwnedAbility& ability); + + // Prune forgets every record whose ability is not in abilities, the + // abilities in the world now, with the same handle. + void Prune(std::span abilities); + + // Count returns how many abilities the client in slot may hold. + [[nodiscard]] size_t Count(int32_t slot) const; + + private: + // Slot is one connection's records: the ability handle at each index. + struct Slot { + uint32_t generation = 0; + std::unordered_map handles; + }; + + std::unordered_map slots_; +}; + +// GuardedAbilities is what one pass of the guard did to one player's set. +struct GuardedAbilities { + // withheld lists the ownerless abilities it kept from the client. + std::vector withheld; + // kept lists the ownerless abilities it still sent, since the client may + // hold them. + std::vector kept; +}; + // WithholdOwnerless withholds from set each ability it sends whose owner is -// not a live entity it also sends, and returns those abilities. +// not a live entity it also sends, unless held says the client may already +// hold that ability. It records in held every ability the set still sends. +// held must be tracked for the set's slot first. // // The client resolves an ability's owner handle against the entities it // holds, and its ability code reads through the result without a null check: -// an ability that arrives without its owner crashes the client in the -// ability's post data update. The client creates -// every entity of an update before it runs their post data update callbacks, -// so an owner sent in the same update is enough. -[[nodiscard]] MODLOCK_API std::vector WithholdOwnerless( - TransmitSet& set, std::span abilities); +// an ability that arrives without its owner crashes the client. The crash +// dumps place the fault in the subclass change callback the client runs as it +// creates the ability. The client creates every entity of an update before it +// runs their post data update callbacks, so an owner sent in the same update +// is enough. An ability the client already holds is not created again, and +// clearing its bit would make the client drop an entity the server still +// counts as held, so it stays. +[[nodiscard]] MODLOCK_API GuardedAbilities +WithholdOwnerless(TransmitSet& set, std::span abilities, HeldAbilities& held); // AbilityOwnerGuard keeps every ability from a player whose update does not -// also send its owner, whatever the game or a mod did to the sets. It runs as -// the transmit hook's final handler, after every mod's handler, and only -// clears bits. It logs each ability it starts withholding from a player. +// also send its owner, whatever the game or a mod did to the sets, unless that +// player's client may already hold it. It runs as the transmit hook's final +// handler, after every mod's handler, and only clears bits. It logs each +// ability it starts withholding from a player, and each it keeps sending +// because the client may hold it. // Install and destruction belong to the engine thread. class MODLOCK_API AbilityOwnerGuard { public: diff --git a/src/gameinterop/ability_owner_guard.cc b/src/gameinterop/ability_owner_guard.cc index baab38ca..48242f38 100644 --- a/src/gameinterop/ability_owner_guard.cc +++ b/src/gameinterop/ability_owner_guard.cc @@ -10,6 +10,7 @@ #include #include +#include "modlock/gameinterop/connection_tracker.h" #include "modlock/gameinterop/entity_abi.h" namespace modlock::gameinterop { @@ -94,6 +95,17 @@ OwnerState OwnerStateOf(const void* entity_system, uint32_t handle, const Bounde return (*flags & kEfDeleteFlags) != 0 ? OwnerState::kDeleting : OwnerState::kLive; } +// HandleOf reads the handle of the entity at identity, index and serial, even +// while the game deletes it, or the invalid handle when it cannot be read. +uint32_t HandleOf(const uint8_t* identity, const BoundedReader& read) { + const auto stored = ReadValue(identity, kIdentityEHandleOffset, read); + const auto flags = ReadValue(identity, kIdentityFlagsOffset, read); + if (!stored || !flags) { + return kInvalidEHandleIndex; + } + return LiveHandleOf(*stored, *flags & ~kEfDeleteFlags).value_or(kInvalidEHandleIndex); +} + // IsAbilityClass reports whether entity_class binds a schema class deriving // from CCitadelBaseAbility, remembering the answer for the schema class. bool IsAbilityClass(const void* entity_class, const BoundedReader& read, AbilityClasses& classes) { @@ -149,6 +161,7 @@ std::vector FindOwnedAbilities(const void* entity_system, size_t o abilities.push_back(OwnedAbility{ .entity = identity->instance, .index = chunk * kMaxEntitiesInList + slot, + .handle = HandleOf(entries + slot * kIdentitySize, read), .owner = owner, .state = OwnerStateOf(entity_system, owner, read), }); @@ -157,20 +170,97 @@ std::vector FindOwnedAbilities(const void* entity_system, size_t o return abilities; } -std::vector WithholdOwnerless(TransmitSet& set, - std::span abilities) { - std::vector withheld; +void HeldAbilities::Track(int32_t slot, bool occupied, uint32_t generation) { + // A slot without its connection holds nothing. + if (!occupied) { + slots_.erase(slot); + return; + } + + // A new connection in the slot starts with nothing. + auto [entry, added] = slots_.try_emplace(slot); + if (!added && entry->second.generation != generation) { + entry->second.handles.clear(); + } + entry->second.generation = generation; +} + +bool HeldAbilities::Holds(int32_t slot, const OwnedAbility& ability) const { + const auto found = slots_.find(slot); + if (found == slots_.end()) { + return false; + } + const auto held = found->second.handles.find(ability.index); + if (held == found->second.handles.end()) { + return false; + } + return ability.handle == kInvalidEHandleIndex || held->second == ability.handle; +} + +void HeldAbilities::Hold(int32_t slot, const OwnedAbility& ability) { + // An untracked slot keeps no records. + const auto found = slots_.find(slot); + if (found == slots_.end()) { + return; + } + + // An unknown handle keeps a record of the ability before it. + auto [held, added] = found->second.handles.try_emplace(ability.index, ability.handle); + if (ability.handle != kInvalidEHandleIndex) { + held->second = ability.handle; + } +} + +void HeldAbilities::Prune(std::span abilities) { + // Index the abilities in the world by their entity index. + std::unordered_map present; + present.reserve(abilities.size()); + for (const auto& ability : abilities) { + present.insert_or_assign(ability.index, ability.handle); + } + + // Forget each record whose ability left the world or whose index another + // ability took. An unknown handle proves neither. + for (auto& [slot, records] : slots_) { + std::erase_if(records.handles, [&](const auto& record) { + const auto found = present.find(record.first); + if (found == present.end()) { + return true; + } + return found->second != kInvalidEHandleIndex && record.second != kInvalidEHandleIndex && + found->second != record.second; + }); + } +} + +size_t HeldAbilities::Count(int32_t slot) const { + const auto found = slots_.find(slot); + return found == slots_.end() ? 0 : found->second.handles.size(); +} + +GuardedAbilities WithholdOwnerless(TransmitSet& set, std::span abilities, + HeldAbilities& held) { + GuardedAbilities guarded; + const int32_t slot = set.Slot(); for (const auto& ability : abilities) { if (!set.Sends(ability.index)) { continue; } - if (ability.state == OwnerState::kLive && set.Sends(ability.owner)) { + + // Withhold an ownerless ability the client cannot hold yet; one it may + // hold stays, since clearing its bit drops it on the client only. + const bool owned = ability.state == OwnerState::kLive && set.Sends(ability.owner); + if (!owned && !held.Holds(slot, ability)) { + set.Withhold(ability.index); + guarded.withheld.push_back(ability); continue; } - set.Withhold(ability.index); - withheld.push_back(ability); + if (!owned) { + guarded.kept.push_back(ability); + } + held.Hold(slot, ability); } - return withheld; + return guarded; } // State is the guard's memory across passes, shared with its handler. @@ -187,9 +277,11 @@ struct AbilityOwnerGuard::State { bool reported_offset = false; bool reported_system = false; uint64_t pass = 0; - // seen holds the pass in which each (slot, ability index) withhold last + // seen holds the pass in which each (kind, slot, ability index) report last // happened. std::unordered_map seen; + // held records the abilities each player's client may hold. + HeldAbilities held; std::chrono::steady_clock::time_point minute{}; int lines = 0; size_t unlogged = 0; @@ -220,10 +312,12 @@ struct AbilityOwnerGuard::State { return owner_offset; } - // Log reports one withhold, unless it was logged within the last second or - // the minute's lines are spent. - void Log(int32_t slot, const OwnedAbility& ability) { - const uint64_t key = (uint64_t{static_cast(slot)} << 32) | ability.index; + // Log reports one withhold, or one ability kept because the client may + // hold it, unless the same report for that player and ability was logged + // within the last second or the minute's lines are spent. + void Log(int32_t slot, const OwnedAbility& ability, bool kept) { + const uint64_t key = + (uint64_t{kept} << 63) | (uint64_t{static_cast(slot)} << 32) | ability.index; auto [entry, added] = seen.try_emplace(key, pass); const bool lapsed = added || pass - entry->second > kRelogPasses; entry->second = pass; @@ -247,9 +341,11 @@ struct AbilityOwnerGuard::State { ++lines; char owner[16]; std::snprintf(owner, sizeof(owner), "0x%08x", ability.owner); - std::cerr << "[modlock] ability owner guard: withheld " << DesignerName(ability.entity) - << " (entity " << ability.index << ") from slot " << slot << ": owner " << owner - << ' ' << OwnerStateName(ability.state) + std::cerr << "[modlock] ability owner guard: " << (kept ? "kept " : "withheld ") + << DesignerName(ability.entity) << " (entity " << ability.index << ") " + << (kept ? "for slot " : "from slot ") << slot + << (kept ? ", whose client may hold it" : "") << ": owner " << owner << ' ' + << OwnerStateName(ability.state) << (ability.state == OwnerState::kLive ? ", not sent" : "") << '\n'; } @@ -271,9 +367,20 @@ struct AbilityOwnerGuard::State { return; } const auto abilities = FindOwnedAbilities(*system, *offset, &ReadNative, classes); + held.Prune(abilities); for (auto& set : sets) { - for (const auto& ability : WithholdOwnerless(set, abilities)) { - Log(set.Slot(), ability); + // A slot's records belong to its current connection. + const int32_t slot = set.Slot(); + const auto connection = ConnectionTracker::StateForSlot(slot); + held.Track(slot, connection.occupied, connection.generation); + + // Withhold what the client cannot hold yet, and report both kinds. + const auto guarded = WithholdOwnerless(set, abilities, held); + for (const auto& ability : guarded.withheld) { + Log(slot, ability, false); + } + for (const auto& ability : guarded.kept) { + Log(slot, ability, true); } } diff --git a/tests/gameinterop_ability_owner_guard_test.cc b/tests/gameinterop_ability_owner_guard_test.cc index 050167fd..2fbb06d6 100644 --- a/tests/gameinterop_ability_owner_guard_test.cc +++ b/tests/gameinterop_ability_owner_guard_test.cc @@ -1,6 +1,7 @@ // Contract tests for the ability owner guard: finding abilities and their -// owners in the entity list, and withholding an ability from a player whose -// update does not send its live owner. +// owners in the entity list, withholding an ability from a player whose update +// does not send its live owner, and never withholding one that player's client +// may already hold. #include #include @@ -17,6 +18,8 @@ namespace { using modlock::gameinterop::AbilityClasses; using modlock::gameinterop::FindOwnedAbilities; +using modlock::gameinterop::GuardedAbilities; +using modlock::gameinterop::HeldAbilities; using modlock::gameinterop::kIdentitySize; using modlock::gameinterop::kInvalidEHandleIndex; using modlock::gameinterop::kMaxEntitiesInList; @@ -155,6 +158,14 @@ struct World { } }; +// Withheld runs one pass for a client that holds nothing yet, as a joining +// client does, and returns what it withheld. +std::vector Withheld(TransmitSet& set, const std::vector& abilities) { + HeldAbilities held; + held.Track(set.Slot(), true, 1); + return WithholdOwnerless(set, abilities, held).withheld; +} + TEST(FindOwnedAbilities, ListsAbilitiesWithTheirLiveOwner) { // A pawn owns a slide and an item; the pawn itself is not an ability. World world; @@ -235,7 +246,7 @@ TEST(WithholdOwnerless, SendsAnAbilityWhoseOwnerIsSent) { FakeInfo info(0); TransmitSet set(info.bytes.data()); - EXPECT_TRUE(WithholdOwnerless(set, abilities).empty()); + EXPECT_TRUE(Withheld(set, abilities).empty()); EXPECT_TRUE(info.Sends(600)); EXPECT_TRUE(info.Sends(3)); } @@ -251,7 +262,7 @@ TEST(WithholdOwnerless, WithholdsAnAbilityWhoseOwnerIsNotSent) { FakeInfo info(4); info.Clear(3); TransmitSet set(info.bytes.data()); - const auto withheld = WithholdOwnerless(set, abilities); + const auto withheld = Withheld(set, abilities); ASSERT_EQ(withheld.size(), 2u); EXPECT_FALSE(info.Sends(600)); EXPECT_FALSE(info.Sends(601)); @@ -261,7 +272,7 @@ TEST(WithholdOwnerless, WithholdsAnAbilityWhoseOwnerIsNotSent) { // Another player who receives the pawn keeps its abilities. FakeInfo other(5); TransmitSet other_set(other.bytes.data()); - EXPECT_TRUE(WithholdOwnerless(other_set, abilities).empty()); + EXPECT_TRUE(Withheld(other_set, abilities).empty()); EXPECT_TRUE(other.Sends(600)); } @@ -278,7 +289,7 @@ TEST(WithholdOwnerless, WithholdsAnAbilityWhoseOwnerDoesNotResolve) { FakeInfo info(0); TransmitSet set(info.bytes.data()); - const auto withheld = WithholdOwnerless(set, abilities); + const auto withheld = Withheld(set, abilities); EXPECT_EQ(withheld.size(), 4u); for (uint32_t index : {10u, 11u, 12u, 13u}) { EXPECT_FALSE(info.Sends(index)) << index; @@ -298,11 +309,207 @@ TEST(WithholdOwnerless, LeavesAnythingElseAlone) { FakeInfo info(0); info.Clear(600); TransmitSet set(info.bytes.data()); - EXPECT_TRUE(WithholdOwnerless(set, abilities).empty()); + EXPECT_TRUE(Withheld(set, abilities).empty()); EXPECT_TRUE(info.Sends(3)); for (uint32_t index = 0; index < TransmitSet::kEntityCount; ++index) { EXPECT_EQ(info.Sends(index), index != 600) << index; } } +TEST(FindOwnedAbilities, ReadsEachAbilitysOwnHandle) { + // The handle carries the serial, even while the game deletes the ability. + World world; + const uint32_t pawn = world.entities.Place(3, world.pawn, 7, kInvalidEHandleIndex); + const uint32_t slide = world.entities.Place(600, world.slide, 2, pawn); + const uint32_t item = world.entities.Place(601, world.item, 9, pawn, 0x10); + + const auto abilities = world.Find(); + ASSERT_EQ(abilities.size(), 2u); + EXPECT_EQ(abilities[0].handle, slide); + EXPECT_EQ(abilities[1].handle, item); +} + +TEST(WithholdOwnerless, KeepsAnAbilityTheClientMayHold) { + // The client received the slide with its pawn, then the pawn left its set. + World world; + const uint32_t pawn = world.entities.Place(3, world.pawn, 7, kInvalidEHandleIndex); + world.entities.Place(600, world.slide, 2, pawn); + const auto abilities = world.Find(); + HeldAbilities held; + held.Track(4, true, 1); + + FakeInfo first(4); + TransmitSet first_set(first.bytes.data()); + const GuardedAbilities sent = WithholdOwnerless(first_set, abilities, held); + EXPECT_TRUE(sent.withheld.empty()); + EXPECT_TRUE(sent.kept.empty()); + EXPECT_EQ(held.Count(4), 1u); + + FakeInfo next(4); + next.Clear(3); + TransmitSet next_set(next.bytes.data()); + held.Track(4, true, 1); + const GuardedAbilities kept = WithholdOwnerless(next_set, abilities, held); + EXPECT_TRUE(kept.withheld.empty()); + ASSERT_EQ(kept.kept.size(), 1u); + EXPECT_EQ(kept.kept[0].index, 600u); + EXPECT_TRUE(next.Sends(600)); +} + +TEST(WithholdOwnerless, KeepsAnAbilityWhoseOwnerLeavesTheWorld) { + // The client holds the slide; then its pawn is deleted, then gone. + World world; + const uint32_t pawn = world.entities.Place(3, world.pawn, 7, kInvalidEHandleIndex); + world.entities.Place(600, world.slide, 2, pawn); + HeldAbilities held; + held.Track(0, true, 1); + FakeInfo first(0); + TransmitSet first_set(first.bytes.data()); + static_cast(WithholdOwnerless(first_set, world.Find(), held)); + + world.entities.Place(3, world.pawn, 7, kInvalidEHandleIndex, 0x10); + FakeInfo deleting(0); + TransmitSet deleting_set(deleting.bytes.data()); + EXPECT_EQ(WithholdOwnerless(deleting_set, world.Find(), held).kept.size(), 1u); + EXPECT_TRUE(deleting.Sends(600)); + + world.entities.Detach(3); + FakeInfo gone(0); + TransmitSet gone_set(gone.bytes.data()); + EXPECT_EQ(WithholdOwnerless(gone_set, world.Find(), held).kept.size(), 1u); + EXPECT_TRUE(gone.Sends(600)); +} + +TEST(WithholdOwnerless, NeverRecordsAnAbilityItWithheld) { + // An ability first sent without its owner stays withheld on every pass. + World world; + const uint32_t pawn = world.entities.Place(3, world.pawn, 7, kInvalidEHandleIndex); + world.entities.Place(600, world.slide, 2, pawn); + const auto abilities = world.Find(); + HeldAbilities held; + for (int pass = 0; pass < 3; ++pass) { + held.Track(4, true, 1); + FakeInfo info(4); + info.Clear(3); + TransmitSet set(info.bytes.data()); + EXPECT_EQ(WithholdOwnerless(set, abilities, held).withheld.size(), 1u) << pass; + EXPECT_FALSE(info.Sends(600)) << pass; + } + EXPECT_EQ(held.Count(4), 0u); +} + +TEST(WithholdOwnerless, KeepsRecordsForEachPlayerApart) { + // Slot 4 received the slide with its pawn; slot 5 never did. + World world; + const uint32_t pawn = world.entities.Place(3, world.pawn, 7, kInvalidEHandleIndex); + world.entities.Place(600, world.slide, 2, pawn); + const auto abilities = world.Find(); + HeldAbilities held; + held.Track(4, true, 1); + FakeInfo first(4); + TransmitSet first_set(first.bytes.data()); + static_cast(WithholdOwnerless(first_set, abilities, held)); + + held.Track(5, true, 1); + FakeInfo other(5); + other.Clear(3); + TransmitSet other_set(other.bytes.data()); + EXPECT_EQ(WithholdOwnerless(other_set, abilities, held).withheld.size(), 1u); + EXPECT_FALSE(other.Sends(600)); +} + +// HeldSlide sets up a slot 4 client that received the slide at 600 with its +// pawn at 3, and returns the abilities of that pass. +std::vector HeldSlide(World& world, HeldAbilities& held) { + const uint32_t pawn = world.entities.Place(3, world.pawn, 7, kInvalidEHandleIndex); + world.entities.Place(600, world.slide, 2, pawn); + auto abilities = world.Find(); + held.Track(4, true, 1); + FakeInfo info(4); + TransmitSet set(info.bytes.data()); + static_cast(WithholdOwnerless(set, abilities, held)); + return abilities; +} + +// WithheldWithoutPawn runs a pass for slot 4 with the pawn at 3 not sent, and +// reports whether it withheld the ability at 600. +bool WithheldWithoutPawn(const std::vector& abilities, HeldAbilities& held, + uint32_t generation) { + held.Track(4, true, generation); + FakeInfo info(4); + info.Clear(3); + TransmitSet set(info.bytes.data()); + static_cast(WithholdOwnerless(set, abilities, held)); + return !info.Sends(600); +} + +TEST(HeldAbilities, ANewConnectionInTheSlotHoldsNothing) { + // A player who joins into the slot never received what the last one did: + // the guard withholds the ownerless slide from them, as on any join. + World world; + HeldAbilities held; + const auto abilities = HeldSlide(world, held); + EXPECT_TRUE(WithheldWithoutPawn(abilities, held, 2)); + EXPECT_EQ(held.Count(4), 0u); +} + +TEST(HeldAbilities, ADisconnectForgetsTheSlot) { + World world; + HeldAbilities held; + const auto abilities = HeldSlide(world, held); + held.Track(4, false, 1); + EXPECT_EQ(held.Count(4), 0u); + EXPECT_TRUE(WithheldWithoutPawn(abilities, held, 1)); +} + +TEST(HeldAbilities, AnUntrackedSlotHoldsNothing) { + // Without a connection record the guard withholds as it always did. + World world; + const uint32_t pawn = world.entities.Place(3, world.pawn, 7, kInvalidEHandleIndex); + world.entities.Place(600, world.slide, 2, pawn); + const auto abilities = world.Find(); + HeldAbilities held; + FakeInfo first(4); + TransmitSet first_set(first.bytes.data()); + static_cast(WithholdOwnerless(first_set, abilities, held)); + EXPECT_EQ(held.Count(4), 0u); + + FakeInfo next(4); + next.Clear(3); + TransmitSet next_set(next.bytes.data()); + EXPECT_EQ(WithholdOwnerless(next_set, abilities, held).withheld.size(), 1u); +} + +TEST(HeldAbilities, ForgetsAnAbilityThatLeftTheWorld) { + World world; + HeldAbilities held; + HeldSlide(world, held); + world.entities.Detach(600); + held.Prune(world.Find()); + EXPECT_EQ(held.Count(4), 0u); +} + +TEST(HeldAbilities, ForgetsAnIndexAnotherAbilityTook) { + // A new item at the slide's index is a new entity on the client: the guard + // withholds it while its owner is not sent. + World world; + HeldAbilities held; + HeldSlide(world, held); + const uint32_t pawn = world.entities.Place(3, world.pawn, 7, kInvalidEHandleIndex); + world.entities.Place(600, world.item, 3, pawn); + const auto abilities = world.Find(); + EXPECT_TRUE(WithheldWithoutPawn(abilities, held, 1)); + held.Prune(abilities); + EXPECT_EQ(held.Count(4), 0u); +} + +TEST(HeldAbilities, KeepsAnAbilityStillInTheWorld) { + World world; + HeldAbilities held; + const auto abilities = HeldSlide(world, held); + held.Prune(abilities); + EXPECT_EQ(held.Count(4), 1u); + EXPECT_FALSE(WithheldWithoutPawn(abilities, held, 1)); +} + } // namespace