Skip to main content

users System

Tracks connected users in your A-Frame multiplayer scene using Colyseus.

Overview​

The users system automatically maintains a list of all connected players. It listens to Colyseus events and updates when users join, leave, or change their data. When the multiplayer connection is ready, it also loads the players that are already in the world.

Getting the User List​

const usersSystem = document.querySelector("a-scene").systems.users;
const users = usersSystem.getUsersList();

// users = [{id: 'abc123', username: 'Alice', el: <a-entity>, playerData: {...}}, ...]

Listening for Changes​

document.querySelector("a-scene").addEventListener("users-changed", (evt) => {
  const users = evt.detail.users;
  console.log(`${users.length} users online`);
});

User Object​

{
  id: 'abc123',          // Colyseus session ID
  username: 'Alice',     // Display name
  el: <a-entity>,        // A-Frame entity (may be null)
  playerData: {...}      // Colyseus player data (may be undefined)
}

API​

getUsersList()​

Returns array of all connected users.

const users = this.el.sceneEl.systems.users.getUsersList();

Event: users-changed​

Fired on the scene when a user joins, leaves, or their data changes. The event does not bubble.

scene.addEventListener("users-changed", (evt) => {
  const users = evt.detail.users;
});

Check if User is Online​

const users = scene.systems.users.getUsersList();
const isOnline = users.some((u) => u.username === "Alice");

Notes​

  • User entities (el) may be null if not yet spawned
  • Usernames are resolved from playerData.userName, playerData.name, playerData.displayName, or the entity's player-info display name, in that order. If none is set, the username is User_ followed by the first four characters of the session ID.