Skip to content

Client Actions

Jump to bottom
Dominique Debergue edited this page Jul 29, 2019 · 19 revisions

The gopherClient.connect() function is one of many actions the client can send to the server. Here, I will list all gopherClient actions linked to the section that describes it's usage:

There are also a few more gopherClient information helper functions that will come in handy:

  • isConnected(): Returns true if the client is connected to the server
  • isLoggedIn(): Returns true if the client is logged in as a User
  • isGuest(): Returns true if the client is logged in as a guest User
  • getUserName(): Returns the client's current User name as a string
  • getRoom(): Returns the client User's current room's name as a string
  • getFriends(): Returns an object of friend objects (Ex: {"bob": {name: "bob", requestStatus: 0, status: 0}, ...})
  • getStatus(): Returns the client User's status as a status ID integer
  • statusName(statusID): Returns the name of a status by it's statusID integer
  • voiceSupport(): Returns true if the client's browser supports the voice chat features

📘 Login & Logout

Logging the client in and out is easy. Just use the gopherClient.login() and gopherClient.logout() functions:

gopherClient.login("My Name", "", false, false, null);
gopherClient.logout();

The login() function takes in 5 parameters: userName string, password string, rememberMe boolean, isGuest boolean, and customCols object. The userName parameter accepts a string that logs the client in under that name, and the fourth parameter isGuest logs the user in as a guest. The password, rememberMe, and customCols are used with the SQL features.

logout() takes no parameters and immediately logs the client out from their current User.

Login & Logout Event Listeners

When the server is done logging the client in or out, it sends back a response with either a success message or error. You can capture the error and success messages with the events.login and events.logout listeners:

gopherClient.addEventListener(gopherClient.events.login, onLogin);
gopherClient.addEventListener(gopherClient.events.logout, onLogout);

function onLogin(userName, error){
	if(error != null){
		console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
	}else{
		console.log("Logged in as: "+userName);
	}
}

function onLogout(success, error){
	if(!success){
		console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
	}else{
		console.log("You have been logged out");
	}
}

If one of these event listeners has an error that is not null, an error occurred while logging in or out. error is an object with id being an integer representing an error ID, and m being a string with a message about what went wrong.

📘 Rooms

Joining and leaving

To join a room the client must be logged in, a room to join must exist on the server, and if the room is private, the client User needs to be on the invite list. You can use the joinRoom() and leaveRoom() functions:

gopherClient.joinRoom("roomName");
gopherClient.leaveRoom();

The joinRoom() function takes one parameter, being the name of the room the client wishes to join. leaveRoom() will immediately remove the client from their current room.

Similar to logging in and out, you can make event listeners for joining and leaving rooms with the events.joined and events.left listeners:

gopherClient.addEventListener(gopherClient.events.joined, joinedRoom);
gopherClient.addEventListener(gopherClient.events.left, leftRoom);

function joinedRoom(roomName, error){
	if(error != null){
		console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
	}else{
		console.log("Joined '"+roomName+"'");
	}
}

function leftRoom(roomName, error){
	if(error != null){
		console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
	}else{
		console.log("Left '"+roomName+"'");
	}
}

Another User joins or leaves

Similarly, if the client is in a room with BroadcastUserEnter or BroadcastUserLeave enabled, they will receive an events.userJoined or events.userLeft event that you can capture when another User enters/leaves their current room:

gopherClient.addEventListener(gopherClient.events.userJoined, userJoinedRoom);
gopherClient.addEventListener(gopherClient.events.userLeft, userLeftRoom);

function userJoinedRoom(userName, isGuest){
	console.log("'"+userName+"' has joined the room");
}

function userLeftRoom(userName){
	console.log("'"+userName+"' has left the room");
}

userName is a string which is the name of the entering/leaving User, and isGuest is a boolean that's true if the User entering the room is a guest.

Creating and deleting

To create and delete rooms, a client must be logged in, and the server's rules (UserRoomControl - and don't forget RoomType rules) must allow it. With that in mind, you can use the createRoom() and deleteRoom() functions:

gopherClient.createRoom("name", "type", true, 0);
gopherClient.deleteRoom("name");

createRoom() takes four parameters: roomName string, roomType string, isPrivate boolean, and maxUsers integer. roomName is the name of the room to create, roomType is the type of room to create, isPrivate makes the room private when true, and maxUsers is a number representing the maximum amount of users that can join.

deleteRoom() only needs one parameter roomName (string), which is the name of the room to delete

📝 Note: A client must be the owner of a room in order to delete it or send/revoke invitations

You can set event listeners for when the room is either created or deleted with the events.roomCreate and events.roomDelete listeners:

gopherClient.addEventListener(gopherClient.events.roomCreate, createdRoom);
gopherClient.addEventListener(gopherClient.events.roomDelete, deletedRoom);

function createdRoom(roomName, error){
	if(error != null){
		console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
	}else{
		console.log("Created room '"+roomName+"'");
	}
}

function deletedRoom(roomName, error){
	if(error != null){
		console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
	}else{
		console.log("Deleted room '"+roomName+"'");
	}
}

Sending, revoking, and receiving invitations

Clients can only send and revoke invites for the room they are currently in. Clients must also be the owner of the room to send and revoke invitations to it. With that in mind, you can send/revoke invitations with the sendInvite() and revokeInvite() functions:

gopherClient.sendInvite("name");
gopherClient.revokeInvite("name");

Both functions accept one parameter: a string which is the name of the User the client wishes to send an invite to, or revoke the invite from.

You can set event listeners for when the client sends/revokes an invitation with the events.invited and events.inviteRevoked listeners:

gopherClient.addEventListener(gopherClient.events.invited, invited);
gopherClient.addEventListener(gopherClient.events.inviteRevoked, revokedInvite);

function invited(success, error){
	if(!success){
		console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
	}else{
		console.log("Invite was sent");
	}
}

function revokedInvite(success, error){
	if(!success){
		console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
	}else{
		console.log("Invite revoked");
	}
}

Similarly, when the client receives an invite to a room, you can catch it with a events.inviteReceived listener:

gopherClient.addEventListener(gopherClient.events.inviteReceived, receivedInvite);

function receivedInvite(userName, roomName){
	console.log("Invite from '"+userName+"' to the room '"+roomName+"'");
}

📘 User Variables

When a client is logged in as a User, they can set/change their own User variables with setUserVariable() for one at a time, and setUserVariables() for more than one at a time:

gopherClient.setUserVariable("y", 50.4);
gopherClient.setUserVariables({x: 30, z: 27.43});

setUserVariable() accepts a variable name and value, and setUserVariables() accepts an object with as many values as you wish to set.

If the value gets set on the server without error, the client API will receive the value(s) back from the server and stored locally in RAM. This is where the getUserVariable() function gets it's values from, not the server. You can use getUserVariable() to get successfully set variables:

var myUserVar = gopherClient.getUserVariable("x");

📘 Messaging

Chat

When a client is logged in as a User and in a room, they can send a chat message to all other Users in the room with the chatMessage() function:

gopherClient.chatMessage("Hello world!");

📝 Note: The parameter passed to chat message can be of type String, Object, or Array, and will be received by all Users in the room in the same fashion.

The client API for all Users (including the sending User) will then receive the message that you can catch with the events.chatMessage listener:

gopherClient.addEventListener(gopherClient.events.chatMessage, gotChatMessage);

function gotChatMessage(userName, message){
	console.log("'"+userName+"': "+message);
}

Private

A client who is logged in as a User can send a private message to another User at any time with the privateMessage() function:

gopherClient.privateMessage("bob", "Yo!");

This send a message to the User named "bob" with the message "Yo!". The sending client will also receive the message from the server after being successfully sent.

📝 Note: The message can be of type String, Object, or Array, and will be received by the User in the same fashion.

When a client User receives a private message, it can be captured with the events.privateMessage listener:

gopherClient.addEventListener(gopherClient.events.privateMessage, gotPrivateMessage);

function gotPrivateMessage(from, to, message){
	console.log("'"+from+"' sent a message to '"+to+"': "+message);
}

📘 Executing Custom Client Actions

You can execute a custom client action with the customClientAction() function:

gopherClient.customClientAction("customAction", "some data");

customClientAction() accepts the name of the action, and data to pass to the action. The data can be of type null, Boolean, Number, String, Object, or Array.

When a custom client action sends a response back from the server, you can catch it with the events.customAction listener:

gopherClient.addEventListener(gopherClient.events.customAction, customActionResponse);

function customActionResponse(responseData, actionName, error){
	// ...
}

responseData is the data the custom client action sent back, and actionName is the name of the action that sent the data. error is null unless there was an error taking action, in which case responseData would then be null.

If you notice there is lacking information, missing features, or bad explanations, please open an issue. All requests are acceptable and will be taken into consideration, so don't be afraid to ask or report something!

Clone this wiki locally