Users

A core.User is a client who has logged into the service, and can now join/leave/create/etc Rooms, and call any server actions and/or custom client actions you have created. A client who is not logged in as a User can still call your custom client actions, so keep that in mind! Also, if you do not plan on using the built-in SQL authentication features, it is highly recommended to make your own authentication mechanism unless the majority of your Users will be guests (and accounts do not matter so much).

⚠️ Warning: When you have a *core.User pointer in your code, DO NOT de-reference it. Instead, there are many methods for *User for retrieving any information about them you could possibly need. De-referencing them could cause data races (which will panic and stop the server) in the User fields that get locked for synchronizing access.

📘 Login and Logout

Logging in should be taken care of almost entirely by the client API. If you want to run your own code as a client is logging in, use the gopher.SetLoginCallback() method to set a callback that runs when a client attempts to log in. You can even use the callback to check the client's input and decide if the client should be able to log in or not.

Logging out can be taken care of by either the server or client API. You can kick a User from the server with the *User.Kick() method, or the *User.Logout() method if you want to log out a specific connection when using the ServerSettings.MultiConnect feature.

📘 Joining & Leaving Rooms

You can make a User join a Room with the [*User.Join()] method:

// Get a User by their name
user, userErr := core.GetUser("billyBob")
if userErr != nil {
	return userErr
}

// Get a Room
room, roomErr := core.GetRoom("someRoom")
if roomErr != nil {
	return roomErr
}

// Make User join the Room
joinErr := user.Join(room, "")
if joinErr != nil {
	return joinErr
}

The *User.Join() method takes in a User and a connection ID string as parameters. The connection ID is only used if you have ServerSettings.MultiConnect enabled, otherwise a blank string can be passed. You can get a connection ID for a client by making a custom client action, and having the client call that action. Your handler function for the custom client action will receive a actions.Client object, which is where you can get the connection ID for that client.

📘 User Variables

A User variable is exactly like a Room variable, but instead, the variable is attached to a User. The methods for getting and setting User variables are exactly the same as for Rooms: *User.SetVariable(), *User.SetVariables(), *User.GetVariable(), and *User.GetVariables(). If you haven't already, check out the usage section for Room Variables to get a better understanding of how to set User variables as well. When setting a User variable, you of course will be using a *User instead.

📘 Initiating and Revoking Room Invites

A client logged in as a User can create a private room from the client API if your server settings allow it. They can also invite and revoke other Users to their private rooms all on their own. But if you, for instance, make a private Room created by the server and it needs a roster, you can use the *Room.AddInvite() and *Room.RemoveInvite() methods. You can also force a User to invite another User to their private rooms with the *User.Invite() method:

// Get a User
user1, userErr1 := core.GetUser("billyBob")
if userErr1 != nil {
	return userErr1
}

// Get another User
user2, userErr2 := core.GetUser("billyBobJR")
if userErr2 != nil {
	return userErr2
}

// Make billyBob invite billyBobJR to their private room
invErr := user1.Invite(user2, "")
if invErr != nil {
	return invErr
}

📝 Note: When successfully invited to a private room, a User is added to an "invite list" which keeps track of who can join the room. You remove Users from the invite list by using the *Room.RemoveInvite() or *User.RevokeInvite() methods.

The *User.Invite() method takes in a User and a connection ID string as parameters. The connection ID is only used if you have ServerSettings.MultiConnect enabled, otherwise a blank string can be passed. You can get a connection ID for a client by making a custom client action, and having the client call that action. Your handler function for the custom client action will receive a actions.Client object, which is where you can get the connection ID for that client.

All the same goes for the *User.RevokeInvite() method to remove a User from another User's private room's invite list, except it takes in a string for the User's name:

// Get a User
user, userErr := core.GetUser("billyBob")
if userErr != nil {
	return userErr
}

// Make billyBob remove billyBobJR from their private room invite list
invErr := user.RevokeInvite("billyBobJR", "")
if invErr != nil {
	return invErr
}

📘 User Status

All Users have a "status". This is just an int that you can change with the *User.SetStatus() method.

user.SetStatus(core.StatusIdle)

You can either define the User statuses yourself, or use the built-in User statuses:

• core.StatusAvailable
• core.StatusInGame
• core.StatusIdle
• core.StatusOffline

📝 Note: When a User changes their status and you have SQL features enabled, all friends will be sent a status change message that you can capture with the client API. Read more about friending and capturing status changes in the client API documentation.

📘 Messaging

Chat and voice messaging for Users is taken care of entirely by the client API. Check out the documentation and usage for the client API you are using. To enable voice chat on the server, check out the Voice Chat section for Rooms.

You can send a data message directly to a user with the *User.DataMessage() method:

user.DataMessage("hello!", "")

The first parameter (the message) accepts and sends any data type compatible with JSON directly to the User. The second parameter (connID) is the connection ID of the client you wish to send to. The connection ID is only used if you have ServerSettings.MultiConnect enabled. A blank string will send the data message to all client connections on that User. You can get a connection ID for a client by making a custom client action, and having the client call that action. Your handler function for the custom client action will receive a actions.Client object, which is where you can get the connection ID for that client.