Skip to content

feat(libsidecar-cpp): publish character lifecycle events for in-process sessions - #105

Open
3kynox wants to merge 2 commits into
walkline:masterfrom
3kynox:feat/libsidecar-cpp-inprocess-lifecycle
Open

3kynox wants to merge 2 commits into
walkline:masterfrom
3kynox:feat/libsidecar-cpp-inprocess-lifecycle

Conversation

@3kynox

@3kynox 3kynox commented Aug 30, 2026

Copy link
Copy Markdown
Contributor

First of a small series contributing the in-process-session support I run in production (playerbots living inside the worldserver, ~1100 concurrent sessions).

Sessions that exist only inside the worldserver process have no gateway, so nothing publishes their logged-in/logged-out events or their zone/level updates — charserver keeps them out of /who, and guildserver/groupserver caches go stale for them.

This adds four exports the worldserver can call on their behalf:

  • TC9CharacterLoggedIn / TC9CharacterLoggedOut — publish gw.char.logged-in / gw.char.logged-out with the same {v,t,p} envelope the gateway uses. The sidecar fills RealmID and uses its servers-registry ID as GatewayID, so charserver's existing purge-on-gateway-death path also cleans these up when the game server dies.
  • TC9CharacterZoneChanged / TC9CharacterLevelChanged — feed a new CharacterUpdatesBarrier that batches and merges per character (mirroring apps/gateway/service/characters-updates-barrier.go, including the 1000-updates cap per event) and flushes gw.char.chars-updates every 5 s.

The declarations document the contract: only call these for sessions WITHOUT a gateway connection, otherwise events are duplicated.

No proto or Go service changes — consumers already handle these subjects. Verified: standalone CMake build, all 38 ctest tests pass; this exact code has been running on my 4-worldserver cluster for weeks.

Follow-ups coming: a vitals lane on top of this barrier (group frames for cross-server members), group/guild ops for in-process sessions, and the battleground queue suite.

…ss sessions

Sessions that live inside the worldserver process (server-side bots,
tools) have no gateway, so nothing publishes their logged-in/logged-out
events or their zone/level updates: charserver keeps them out of /who,
and guildserver/groupserver caches go stale for them.

New exports let the worldserver publish on their behalf:
- TC9CharacterLoggedIn / TC9CharacterLoggedOut publish gw.char.logged-in
  and gw.char.logged-out with the same envelope the gateway uses; the
  sidecar fills RealmID and uses its servers-registry ID as GatewayID so
  charserver purges the entries when this game server dies.
- TC9CharacterZoneChanged / TC9CharacterLevelChanged feed a
  CharacterUpdatesBarrier that batches and merges per character (same
  semantics as the gateway CharactersUpdatesBarrier, same 1000-updates
  cap per event) and flushes gw.char.chars-updates every 5s.

Callers must only use these for sessions WITHOUT a gateway connection,
otherwise events are duplicated - documented on the declarations.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The new updates barrier has a shutdown/stop edge case that can silently drop queued updates, and the cross-realm RealmID behavior for the new events is currently ambiguous.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds a gateway-compatible event publishing path to libsidecar-cpp so in-process sessions (e.g., server-side bots without a gateway connection) still emit character lifecycle events and periodic zone/level updates for downstream consumers (charserver /who, guildserver, groupserver).

Changes:

  • Adds four new C exports to publish gw.char.logged-in, gw.char.logged-out, and to queue zone/level changes for batched publishing.
  • Introduces a CharacterUpdatesBarrier that merges per-character updates and flushes gw.char.chars-updates every 5 seconds with a 1000-updates-per-event cap.
  • Wires the barrier lifecycle into TC9InitLib / TC9GracefulShutdown and updates the build to compile the new source file.
File summaries
File Description
game-server/libsidecar-cpp/src/events/updates-barrier.h Declares the new CharacterUpdatesBarrier interface for batched/merged character updates.
game-server/libsidecar-cpp/src/events/updates-barrier.cpp Implements the barrier worker thread, merge behavior, and capped flushing logic.
game-server/libsidecar-cpp/src/api.cpp Adds gateway-subject publishing helpers, initializes/stops the barrier, and exposes new C API functions for in-process sessions.
game-server/libsidecar-cpp/include/libsidecar.h Documents and exposes the new C API exports for character login/logout and zone/level updates.
game-server/libsidecar-cpp/CMakeLists.txt Includes updates-barrier.cpp in the library build sources.
Review details

Suppressed comments (1)

game-server/libsidecar-cpp/src/events/updates-barrier.cpp:57

  • UpdateZone/UpdateLevel accept updates even when the barrier has been stopped. Those updates will never be flushed because the background thread is no longer running (and Stop() may already have performed its final flush). Guarding on running_ avoids silently accumulating/dropping updates during/after shutdown.
void CharacterUpdatesBarrier::UpdateZone(uint64_t charGUID, uint32_t mapID, uint32_t areaID, uint32_t zoneID) {
    std::lock_guard<std::mutex> lock(mutex_);
    auto& upd = pending_[charGUID];
    upd.map = mapID;
    upd.area = areaID;
    upd.zone = zoneID;
}

void CharacterUpdatesBarrier::UpdateLevel(uint64_t charGUID, uint8_t level) {
    std::lock_guard<std::mutex> lock(mutex_);
    pending_[charGUID].level = level;
}
  • Files reviewed: 5/5 changed files
  • Comments generated: 3
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment on lines +59 to +70
void CharacterUpdatesBarrier::run() {
for (;;) {
{
std::unique_lock<std::mutex> lock(mutex_);
cv_.wait_for(lock, interval_, [this] { return !running_; });
if (!running_) {
return;
}
}
flush();
}
}
Comment on lines +76 to +79

payload["RealmID"] = g_state.realm_id;
payload["GatewayID"] = g_state.assigned_server_id;

Comment on lines +30 to +44
void CharacterUpdatesBarrier::Stop() {
{
std::lock_guard<std::mutex> lock(mutex_);
if (!running_) {
return;
}
running_ = false;
}
cv_.notify_all();
if (thread_.joinable()) {
thread_.join();
}
// Flush leftovers so updates emitted during shutdown are not lost.
flush();
}
…st it

Review follow-ups: Stop() returned early when the barrier was not
running, so updates queued before Start or after a first Stop (e.g. a
call racing shutdown, delivered by the destructor's Stop) were silently
dropped - it now joins the thread only when needed and flushes
unconditionally. Adds a gtest suite covering per-character merging,
the 1000-updates batch split, and both stopped-flush paths.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants