Custom Client Actions

A custom client action is an action on the server that you define and supply a handler function to run when a client calls that custom action. Your handler functions can also chose whether or not to respond to the client with some data. If an error occurred while running your handler, you can send the error back to the client via message/ID format for easily defining and checking errors on the client side.

📘 Creating a Custom Client Action

To create your own custom client action, use the actions.New() method before starting your server (during your server set-up), or the action will not be created and an error will be returned:

package main

import (
	"github.com/hewiefreeman/GopherGameServer"
	"github.com/hewiefreeman/GopherGameServer/actions"
)

func main() {

	// ...

	// Make a custom action
	err := actions.New("helloWorld", actions.DataTypeString, actionHelloWorld)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Start the server
	gopher.Start(nil)
}

func actionHelloWorld(actionData interface{}, client *actions.Client) {
	fmt.Println("Hello, " + actionData.(string) + "!")
}

I started off by creating a new custom client action and then ran the server. The action's name is "helloWorld", it accepts only strings as it's data type, and will run the function actionHelloWorld() when called. Now, a client can call the "helloWorld" action with a string attached as [input] from the client API, and the console will print, "Hello, [input]!".

Custom client actions can only accept types compatible with JSON. These types are defined in the actions package:

• actions.DataTypeBool: bool data type
• actions.DataTypeInt: int, int32, and int64 data types
• actions.DataTypeFloat: float32 and float64 data types
• actions.DataTypeString: string data type
• actions.DataTypeArray: []interface{} data type
• actions.DataTypeMap: map[string]interface{} data type
• actions.DataTypeNil: nil data type

Notice the handler function actionHelloWorld() in the above example takes in two parameters: actionData and client. actionData is the input from the client API, and will always match the data type you supplied when creating the action. If the client API didn't supply the correct data type, they will receive back an error and your handler function will not be ran. client is an *actions.Client object that represents the client who ran the action. You can get any information you need about the Client with it's methods:

• *Client.Action(): The name of the action the client took.
• *Client.ConnectionID(): The connection ID of the client (when using ServerSettings.MultiConnect feature)
• *Client.User(): The User object of the client

📘 Responding to a Custom Client Action

Responding to a client from a custom client action is easy. Just use the *Client.Respond() method. Let's see how we could have responded to the example we used before:

func actionHelloWorld(actionData interface{}, client *actions.Client) {
	client.Respond("Hello, " + actionData.(string) + "!", actions.NoError())
}

The first parameter supplied to *Client.Respond() is the data you want to send back to the client. It can be any data type compatible with JSON. The second parameter supplied is an actions.ClientError, which represents an error that happened while running your handler. You create ClientErrors with the actions.NewError(), or if no error should be thrown, use the actions.NoError() method as shown above.

NewError() takes in two parameters: a message string, and ID int. You can define the messages and IDs however you wish.

📝 Note: When supplying a NewError() to *Client.Respond(), only the error will be sent to the client. Any data you entered for the first parameter will be discarded, so it's best to pass nil as the first argument when responding with a ClientError.