modules.api.engine.players

The curated player surface. Wraps the raw UserIdentity component proxy in a view that exposes only the safe authoring API: .isLocal / .avatar / .ready / .userId / .identity / .displayName.

.avatar is the visible body's entity REF (a live proxy), or nil until a body is bound — act on it directly (player.avatar.position = { x, y, z }). Want the id? player.avatar.id. Assign a live entity ref to bind it as the body — player.avatar = entityRef (assign nil to clear) is the one path that binds a body to the player.

.entity / .entityId / .id / .component are intentionally REFUSED. The identity entity is a internal anchor with no world presence — reach the visible body via player.avatar. Position writes always target the avatar.

Used by every layers.active.players.localPlayer / onLocalReady / playerJoined / playerLeft call site so user scripts can't reach past the curated wrapper into the underlying component proxy.