Skip to content

feat(libsidecar-cpp): battleground queue operations for in-process sessions - #108

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

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

Conversation

@3kynox

@3kynox 3kynox commented Aug 30, 2026

Copy link
Copy Markdown
Contributor

Part of the in-process-session series (#105/#106/#107), independent of the others.

The matchmaking service owns battleground queues cluster-wide, and only the gateway talks to it on behalf of players. In-process sessions (server-side bots) therefore can't enter a queue, accept an invite, or confirm they entered a battleground — which makes it impossible to backfill battlegrounds with bots in cluster mode.

Five exports wrapping the existing matchmaking RPCs:

  • TC9EnqueueLocalPlayerToBattleground → EnqueueToBattleground (solo)
  • TC9EnqueueLocalGroupToBattleground → same RPC with partyMembers: leader plus members in ONE queue entry, so a whole group fill pops one full battleground instead of the matchmaking creating the match mid-batch
  • TC9BattlegroundQueueDataForLocalPlayer → BattlegroundQueueDataForPlayer, plus a registry lookup (ListAllGameServers, resolved once and cached) reporting whether the assigned battleground runs on THIS worldserver — the caller then either adds the bot locally or hands it off
  • TC9PlayerJoinedBattleground → the joined confirmation the gateway sends for real players, so the matchmaking's seat accounting stays exact
  • TC9RemovePlayerFromBattlegroundQueue → RemovePlayerFromQueue for leftover enqueues that were never invited, or out-of-bracket entries after a level up

No proto or Go changes — every RPC already exists (including partyMembers on the enqueue request). All calls are blocking (5 s deadline) and documented as not to be called from map update threads.

Verified: standalone CMake build, 38/38 ctest. Running in production: this is the path my cluster uses to keep battlegrounds populated with bots across 4 worldservers (queue → invite → seat → backfill on leave, together with #98-#100 on the matchmaking side).

…ssions

The matchmaking service owns battleground queues cluster-wide, and only
the gateway talks to it on behalf of players. In-process sessions
(server-side bots) therefore cannot enter a queue, accept an invite, or
confirm they entered a battleground - which makes it impossible to
backfill battlegrounds with bots in cluster mode.

Adds five exports wrapping the existing matchmaking RPCs:

- TC9EnqueueLocalPlayerToBattleground -> EnqueueToBattleground (solo)
- TC9EnqueueLocalGroupToBattleground  -> EnqueueToBattleground with
  partyMembers: leader plus members in ONE queue entry, so a whole
  group fill pops one full battleground instead of the matchmaking
  creating the match mid-batch
- TC9BattlegroundQueueDataForLocalPlayer -> BattlegroundQueueDataForPlayer,
  plus a registry lookup (ListAllGameServers) to report whether the
  assigned battleground runs on THIS worldserver
- TC9PlayerJoinedBattleground -> PlayerJoinedBattleground (the
  confirmation the gateway sends for real players)
- TC9RemovePlayerFromBattlegroundQueue -> RemovePlayerFromQueue
  (leftover enqueues never invited, or out-of-bracket after a level up)

All blocking calls (5s deadline), documented as not for map update
threads. No proto changes - every RPC already exists.
Copilot AI lite review requested due to automatic review settings August 30, 2026 16:34

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

Several new public APIs need input-validation and documentation alignment to prevent null-pointer crashes and accidental misuse (e.g., group member list semantics and team ID range).

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

Pull request overview

This PR extends libsidecar-cpp with battleground queue operations so in-process sessions (server-side bots without a gateway) can interact with the matchmaking service cluster-wide (enqueue solo/group, query invite assignment, confirm join, and remove from queue).

Changes:

  • Added matchmaking gRPC client wrappers for battleground queue operations plus a registry lookup helper for resolving game server addresses.
  • Added new exported C API functions in libsidecar.h/api.cpp that expose these matchmaking operations to the worldserver.
  • Implemented a one-time (per-process) resolution of the local worldserver’s public address to determine whether an assigned battleground is hosted locally.
File summaries
File Description
game-server/libsidecar-cpp/src/grpc/clients.h Adds new GrpcClients method declarations for battleground queue + registry address resolution.
game-server/libsidecar-cpp/src/grpc/clients.cpp Implements the new matchmaking/registry RPC wrappers used by in-process sessions.
game-server/libsidecar-cpp/src/api.cpp Exposes new C API entry points and performs local server-assignment determination for invites.
game-server/libsidecar-cpp/include/libsidecar.h Publishes the new exported API functions and documents expected usage constraints.
Review details
  • Files reviewed: 4/4 changed files
  • Comments generated: 6
  • 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 +94 to +98
/* Group enqueue: leader plus party members in ONE queue entry, so a whole
* group fill pops one full battleground instead of the matchmaking creating
* the match mid-batch. Blocking gRPC call. 0 on success. */
TC9_API int TC9EnqueueLocalGroupToBattleground(uint64_t leaderGUID, uint32_t leaderLvl,
uint32_t bgTypeID, uint32_t pvpTeamID, const uint64_t* memberGUIDs, int memberCount);
Comment on lines +86 to +88
// Group variant: one enqueue for a leader plus party members — the queue
// then treats them as one group, so a whole fill pops atomically
// instead of the match being created mid-batch.
Comment on lines +288 to +295
v1::EnqueueToBattlegroundRequest request;
request.set_api(LIB_VERSION);
request.set_realmid(realm_id);
request.set_leaderguid(player_guid);
request.set_leaderslvl(player_lvl);
request.set_bgtypeid(bg_type_id);
request.set_teamid(static_cast<v1::PVPTeamID>(team_id));

Comment on lines +327 to +336
v1::EnqueueToBattlegroundRequest request;
request.set_api(LIB_VERSION);
request.set_realmid(realm_id);
request.set_leaderguid(leader_guid);
request.set_leaderslvl(leader_lvl);
request.set_bgtypeid(bg_type_id);
request.set_teamid(static_cast<v1::PVPTeamID>(team_id));
for (int i = 0; i < member_count; ++i)
request.add_partymembers(member_guids[i]);

Comment on lines +448 to +453
if (!g_state.initialized || !g_state.grpc_clients) {
return -1;
}

return g_state.grpc_clients->EnqueueToBattleground(
g_state.realm_id, playerGUID, playerLvl, bgTypeID, pvpTeamID) ? 0 : -1;
Comment on lines +456 to +466
TC9_API int TC9EnqueueLocalGroupToBattleground(uint64_t leaderGUID, uint32_t leaderLvl,
uint32_t bgTypeID, uint32_t pvpTeamID, const uint64_t* memberGUIDs, int memberCount) {

if (!g_state.initialized || !g_state.grpc_clients) {
return -1;
}

return g_state.grpc_clients->EnqueueGroupToBattleground(
g_state.realm_id, leaderGUID, leaderLvl, bgTypeID, pvpTeamID,
memberGUIDs, memberCount) ? 0 : -1;
}
…oup semantics

Review follow-ups: both enqueue exports now reject a pvpTeamID other
than 1/2 (an invalid enum would otherwise reach the matchmaking
service) and the group variant rejects a null memberGUIDs with a
positive count instead of dereferencing it. The docstrings now state
that memberGUIDs excludes the leader - it travels as leaderGUID, same
contract as the gateway's PartyMembers field.
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