Skip to content

Networking: Give joined players IDs of their own - #381

Open
Kheartz wants to merge 6 commits into
developfrom
player_ids
Open

Kheartz wants to merge 6 commits into
developfrom
player_ids

Conversation

@Kheartz

@Kheartz Kheartz commented Nov 7, 2026 •

Copy link
Copy Markdown
Collaborator

A player was known to scripts and admins by its avatar's entity network ID. Every replicated entity draws from that one counter, so a server that spawns thousands of entities at startup hands its first player an ID in the thousands. With HogwartsMP's 4,005 loot spots under server authority, the first player after a fresh start got an ID around 4009.

Players now get a player ID of their own, numbered the way FiveM numbers server IDs. The first join after startup is 1 and each join takes the next number. A disconnected player's ID is not handed out again, so a reconnect gets a new one; only after 2^32 - 1 joins does the counter start over at 1, and then it skips IDs still held. Entity network IDs are unchanged.

Where What
NetworkServer AssignPlayerId, GetPlayerId (also on NetworkPeer, where it returns 0) and FindPlayerById, which gives the connection; its avatar is GetViewer(guid)
PlayerConnectionData playerId, assigned when the join is accepted, before OnPlayerConnect
Scripts player.playerId, server-only, beside ping and ip. player.id stays the entity network ID that TextLabel targets and handle transfer rely on
Console status lists joined players as [playerId] name (ping ms), and each join logs <name> joined as player N

The ID is given at join, not at admission, so a request that is refused or abandoned, or a client that leaves mid-download, never uses a number up. A PendingConnection has none yet, which connection_admission.md now says.

The fourth commit fixes a gap the review turned up, already in develop for identity. KickPlayer cleared the connection's state as soon as it asked MafiaNet to close it, but MafiaNet 0.24 reports that close a tick or more later, so a kicked player's disconnect handlers saw no player ID, Steam ID or name. A live connection now keeps its state until the close notification is handled; only the build gate closes at the kick.

This is a scripting-layer addition (MINOR): no RPC or wire format changes, and clients do not see player IDs. HogwartsMP already uses playerId as a parameter name for entity network IDs in a few APIs (pvp.getStats(playerId), relation.playerId); those want renaming when it adopts this, so the two cannot be mixed up.

player_ids covers numbering, no reuse, the wrap, the lookups and the 4,005-entity startup. Over loopback, it also checks that the ID and identity are still readable in the server's disconnect handler after a kick and after a client disconnect. A js_features case reads player.playerId from script. All 835 FrameworkTests and 3 client scripting tests pass with MSVC; it has not been run on a live HogwartsMP server yet.

Summary by CodeRabbit

  • New Features
    • Players now receive a connection-based player ID when they join. Scripts can access it through player.playerId; it is distinct from the entity network ID and is 0 when unavailable.
    • The server status command now displays joined players’ IDs, names, and ping times.
  • Bug Fixes
    • Player identity and ID remain available during disconnect handling, then are cleared after disconnection is processed.
  • Documentation
    • Clarified that pending connections do not receive a player ID unless they join.

A player was known by its avatar's entity network ID, drawn from the
counter every replicated entity shares, so a server that spawns
thousands of entities at startup gave its first player an ID in the
thousands.

PlayerIdAllocator numbers joined connections the way FiveM numbers
server IDs: 1 for the first join after startup, one higher for each
join after. A disconnected player's ID is not handed out again until
the counter wraps, and then IDs still held are skipped. NetworkServer
holds one per connection and releases it with the rest of the
connection's state. Entity network IDs are unchanged.
The ID is taken when the join is accepted, before the game builds the
avatar, so a request that is refused or abandoned never uses a number
up. PlayerConnectionData carries it to OnPlayerConnect, the join is
logged with it, and the status command lists joined players by it.
Server-only, beside ping and ip, so every game's Player subclass
inherits it. Player.id stays the entity network ID that TextLabel
targets and handle transfer rely on.
KickPlayer cleared the connection's identity, and now its player ID,
as soon as it asked MafiaNet to close the connection. MafiaNet reports
that close a tick or more later, as an ID_DISCONNECTION_NOTIFICATION,
and the disconnect handlers that run then (the game's
OnPlayerDisconnect, the scripts' playerDisconnect) found a kicked
player with no player ID, Steam ID or name.

A live connection now keeps that state until its notification is
handled; only the build gate closes at the kick. A guid with no live
connection gets no notification, so it is still cleared at once.
It is 0 whenever it is unavailable, not only once a player has left,
and an ID is reused after the counter wraps. PlayerConnectionData also
notes that OnPlayerDisconnect follows only for a player who reached
OnPlayerReady, so state keyed on the ID must not rely on it alone.
@coderabbitai

coderabbitai Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The server now assigns player IDs to joined connections. It retains connection identity and IDs through disconnect callbacks, exposes the ID through the scripting Player property, and lists joined players by ID in the status command.

Changes

Connection player ID flow

Layer / File(s) Summary
Player ID allocation
code/framework/src/networking/player_ids.h, code/tests/modules/player_ids_ut.h, code/tests/framework_ut.cpp
PlayerIdAllocator assigns nonzero IDs, supports lookups and release, and handles wraparound and exhaustion. Tests cover allocation behavior and register the test module.
Join and disconnect lifecycle
code/framework/src/networking/network_peer.h, code/framework/src/networking/network_server.*, code/framework/src/integrations/server/instance.*, code/tests/modules/player_ids_ut.h, docs/connection_admission.md
The server assigns an ID when a player joins. For connected or disconnecting peers, KickPlayer retains identity and ID state until disconnection handling; clearing client state releases the ID. Tests cover callback state and assignment independently of entity IDs. The admission docs state that pending requests have no player ID.
Player ID access and status
code/framework/src/scripting/builtins/player.*, code/framework/src/integrations/server/instance.cpp, code/tests/modules/js_features_ut.h
The server-side Player.playerId property returns the connection ID, or 0 when unavailable. The status command lists joined players by ID, name, and ping. Tests distinguish the player ID from the entity ID.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ClientJoin
  participant NetworkServer
  participant PlayerIdAllocator
  participant ScriptingPlayer
  ClientJoin->>NetworkServer: AssignPlayerId(guid)
  NetworkServer->>PlayerIdAllocator: Assign(guid)
  PlayerIdAllocator-->>NetworkServer: playerId
  ScriptingPlayer->>NetworkServer: GetPlayerId(guid)
  NetworkServer-->>ScriptingPlayer: playerId
Loading

Suggested reviewers: segfaultd, zpl-zak

Merge Risk: Minimal · up to e64a8

This change adds server-side player IDs that stay readable in disconnect handlers and are exposed to scripts as player.playerId. No concrete defect was confirmed. One edge case remains unverified: a kick issued in the brief window after a client's connection has closed but before the disconnect handler runs, which could clear the ID early. The change has not been run on a live server, but the risk is low.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title "Networking: Give joined players IDs of their own" matches the main change. The PR adds a server-side player ID, separate from the entity network ID, that is assigned to players when a join …
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title "Networking: Give joined players IDs of their own" matches the main change. The PR adds a server-side player ID, separate from the entity network ID, that is assigned to players when a join is accepted. The changeset adds PlayerIdAllocator, NetworkServer ID assignment and lookup, the playerId field in PlayerConnectionData, and the script-facing player.playerId property. The title is concise, specific, and free of noise.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

Cppcheck (2.22.0)

code/tests/framework_ut.cpp

Cppcheck timed out; analysis of this file is incomplete

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

A rabbit counts the players as they hop,
Each gets a number when they join the game.
The numbers wait through one last callback,
Then hop back free, ready for another name.
“Your script can read your number,” says the hare,
And leaves a nibble by the status screen.

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 544d8794-e07e-42c9-9ce1-688c24fa8c33
Commits

Reviewing files that changed from the base of the PR and between ccf0cb4 and e64a801.

Files selected for processing: 12

  • code/framework/src/integrations/server/instance.cpp
  • code/framework/src/integrations/server/instance.h
  • code/framework/src/networking/network_peer.h
  • code/framework/src/networking/network_server.cpp
  • code/framework/src/networking/network_server.h
  • code/framework/src/networking/player_ids.h
  • code/framework/src/scripting/builtins/player.cpp
  • code/framework/src/scripting/builtins/player.h
  • code/tests/framework_ut.cpp
  • code/tests/modules/js_features_ut.h
  • code/tests/modules/player_ids_ut.h
  • docs/connection_admission.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@Kheartz

Kheartz commented Nov 7, 2026

Copy link
Copy Markdown
Collaborator Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Player IDs now sit under _clientsMutex with the rest of the
per-connection state, and the kick's build-gate erase takes it too.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

1 participant