CocosCreator Universal Framework Design Network

Preface

It is relatively simple to initiate an http request in Cocos Creator, but many games hope to maintain a long connection with the server so that the server can actively push messages to the client, rather than always initiating requests by the client. This is especially true for games with high real-time requirements. Here we will design a general network framework that can be easily applied to our projects.

Using websocket

Before implementing this network framework, let's first understand websocket. Websocket is a full-duplex network protocol based on TCP that allows web pages to create persistent connections and conduct two-way communication. Using websocket in Cocos Creator can be used in H5 web games, and also supports native platforms Android and iOS.

Constructing a websocket object

When using websocket, the first step should be to create a websocket object. The constructor of the websocket object can pass in two parameters, the first is the url string, and the second is the protocol string or string array, which specifies the acceptable sub-protocols. The server needs to select one of them to return before establishing a connection, but we generally don't use it.

The url parameter is very important and is mainly divided into 4 parts: protocol, address, port, and resource.

For example, ws://echo.websocket.org:

• Protocol: Required. The default protocol is ws. If secure encryption is required, use wss.
• Address: Required, can be an IP or domain name, of course it is recommended to use the domain name.
• Port: Optional. If not specified, the default port for ws is 80 and the default port for wss is 443.
• Resource: Optional, usually a resource path following the domain name, we basically don’t need it.

Websocket Status

Websocket has 4 states, which can be queried through the readyState property:

• 0 CONNECTING The connection has not been established.
• 1 OPEN The WebSocket connection is established and communication is possible.
• 2 CLOSING The connection is undergoing a closing handshake, or the close() method has been called.
• 3 CLOSED The connection has been closed.

WebSocket API

Websocket has only two APIs, void send( data ) to send data and void close( code, reason ) to close the connection.

The send method receives only one parameter - the data to be sent, which can be any of the following four types: string | ArrayBufferLike | Blob | ArrayBufferView.

If the data to be sent is binary, we can specify the binary type through the binaryType property of the websocket object. binaryType can only be set to "blob" or "arraybuffer", and the default is "blob". If we want to transfer relatively fixed data such as files for writing to disk, use blob. If you want to transfer objects that are processed in memory, use the more flexible arraybuffer. If you want to construct a blob from other non-blob objects and data, you need to use the blob constructor.

When sending data, the official has 2 suggestions:

• Check if the readyState of the websocket object is OPEN, and send only if it is.
• Check if the bufferedAmount of the websocket object is 0, and send it only if it is (to avoid message accumulation, this property indicates the length of data accumulated in the websocket buffer after calling send but not actually sent out).

The close method accepts two optional parameters. Code represents the error code. We should pass in 1000 or an integer between 3000 and 4999. Reason can be used to indicate the reason for closing. The length cannot exceed 123 bytes.

Websocket callback

Websocket provides 4 callback functions for us to bind:

• onopen: called after the connection is successful.
• onmessage: called when a message comes in: the passed in object has a data attribute, which may be a string, blob or arraybuffer.
• onerror: called when a network error occurs: the passed object has a data attribute, which is usually a string describing the error.
• onclose: called when the connection is closed: the object passed in has attributes such as code, reason, wasClean, etc.

Note: When a network error occurs, onerror will be called first and then onclose. No matter what the reason for the connection closing, onclose will be called.

Echo Example

The following is the code of the echo demo on the websocket official website. You can write it into an html file and open it with a browser. After opening, a websocket connection will be automatically created. When the connection is established, a message "WebSocket rocks" will be actively sent. The server will return the message, trigger onMessage, print the information to the screen, and then close the connection. For details, please refer to: http://www.websocket.org/echo.html17

The default URL prefix is ​​wss. Because wss is out of order, you can only connect using ws. If ws is also out of order, you can try connecting to this address ws://121.40.165.18:8800, which is a free websocket test URL in China.

Design Framework

A general network framework needs to be able to support the different requirements of various projects on the premise of being universal. According to experience, the common requirements are as follows:

• Due to differences in user protocols , games may transmit json, protobuf, flatbuffer or custom binary protocols.
• Due to the differences in underlying protocols, we may use websocket, or wx.websocket for WeChat games, or even on the native platform we hope to use protocols such as tcp/udp/kcp.
• Login authentication process: We should perform login authentication before using long connection, and different games have different login authentication methods.
• Network exception handling, such as how long is the timeout, what is the performance after the timeout, whether the UI should be blocked when requesting and waiting for the server response, how is the performance after the network is disconnected, whether it reconnects automatically or the player clicks the reconnect button to reconnect, and whether the messages during the network disconnection period are resent after reconnection? And so on.
• Processing of multiple connections : Some games may need to support multiple different connections, generally no more than 2. For example, a main connection is responsible for processing business messages such as the lobby, and a battle connection is directly connected to the battle server, or connected to the chat server.

Based on the above requirements, we split the functional modules to ensure high cohesion and low coupling of the modules.

ProtocolHelper protocol processing module - When we get a buffer, we may need to know the protocol or ID corresponding to this buffer. For example, when we pass in the response processing callback during the request, the common practice may be to use an auto-incrementing ID to distinguish each request, or to use the protocol number to distinguish different requests. These are what developers need to implement. We also need to get the length of the packet from the buffer? What is the reasonable range of package length? What does a heartbeat packet look like, etc.

Socket module - implements the most basic communication function. First, define the Socket interface class ISocket, define interfaces such as connection, closing, data receiving and sending, and then subclasses inherit and implement these interfaces.

NetworkTips network display module - realizes the display of status such as connecting, reconnecting, loading, network disconnection, etc., as well as the shielding of UI.

NetNode network node - the so-called network node, in fact, its main responsibility is to connect the above functions in series and provide users with an easy-to-use interface.

NetManager manages a singleton of network nodes - we may have multiple network nodes (multiple connections), so a singleton is used here for management. It is also more convenient to use a singleton to operate network nodes.

ProtocolHelper

A simple IProtocolHelper interface is defined here as follows:

export type NetData = (string | ArrayBufferLike | Blob | ArrayBufferView); // protocol helper interface export interface IProtocolHelper
{    
    getHeadlen(): number; // Returns the length of the packet header getHearbeat(): NetData; // Returns a heartbeat packet getPackageLen(msg: NetData): number; // Returns the length of the entire packet checkPackage(msg: NetData): boolean; // Check whether the packet data is legal getPackageId(msg: NetData): number; // Returns the packet id or protocol type }

Socket

A simple ISocket interface is defined here, as shown below:

//Socket interface export interface ISocket {    
    onConnected: (event) => void; //Connection callbackonMessage: (msg: NetData) => void; //Message callbackonError: (event) => void; //Error callbackonClosed: (event) => void; //Close callbackconnect(ip: string, port: number); //Connection interfacesend(buffer: NetData); //Data sending interfaceclose(code?: number, reason?: string); //Close interface}

Next, we implement a WebSock, which inherits from ISocket. We only need to implement the connect, send and close interfaces. Send and close are both simple encapsulation of websocket, while connect needs to construct a url according to the passed in IP, port and other parameters to create websocket and bind the callback of websocket.

export class WebSock implements ISocket {    
    private _ws: WebSocket = null; // websocket object onConnected: (event) => void = null;    
    onMessage: (msg) => void = null;    
    onError: (event) => void = null;    
    onClosed: (event) => void = null;   
    connect(options: any) {        
    if (this._ws) {            
        if (this._ws.readyState === WebSocket.CONNECTING) {                
            console.log("websocket connecting, wait for a moment...")                
            return false;
        }
    }
    let url = null;        
    if(options.url) {           
        url = options.url;        
    } else {            
        let ip = options.ip;            
        let port = options.port;            
        let protocol = options.protocol;            
        url = `${protocol}://${ip}:${port}`;           
    }        
        this._ws = new WebSocket(url);       
        this._ws.binaryType = options.binaryType ? options.binaryType : "arraybuffer";        
        this._ws.onmessage = (event) => {           
        this.onMessage(event.data);        
    };        
        this._ws.onopen = this.onConnected;        
        this._ws.onerror = this.onError;        
        this._ws.onclose = this.onClosed;       
        return true;    
    }    
    send(buffer: NetData) {        
    if (this._ws.readyState == WebSocket.OPEN) {           
        this._ws.send(buffer);           
        return true;       
    }       
    return false;    
    }    
    close(code?: number, reason?: string) {        
    this._ws.close();    
    }
}

NetworkTips

INetworkTips provides a very useful interface, reconnection and request switches. The framework will call them at the right time. We can inherit INetworkTips and customize our network-related prompt information. It should be noted that these interfaces may be called **multiple times**.

// Network Tips interface export interface INetworkTips {    
    connectTips(isShow: boolean): void;    
    reconnectTips(isShow: boolean): void;    
    requestTips(isShow: boolean): void;
}

NetNode

NetNode is the most critical part of the entire network framework. A NetNode instance represents a complete connection object. Based on NetNode, we can easily expand it. Its main responsibilities are:

Connection maintenance

• Connection establishment and authentication (whether to authenticate and how to authenticate are determined by the user's callback)
• Data retransmission after disconnection and reconnection
• The heartbeat mechanism ensures that the connection is valid (the heartbeat packet interval is configured, and the content of the heartbeat packet is defined by ProtocolHelper)
• Closing the connection

Data transmission

• Support disconnection retransmission and timeout retransmission
• Support unique sending (avoid repeated sending at the same time)

Data Reception

• Support continuous monitoring
• Support request-response mode

Interface display

• Customizable network delay, short-term reconnection and other status performance
• First, we define two enumerations, NetTipsType and NetNodeState, and the NetConnectOptions structure for use by NetNode.
• Next are the member variables of NetNode. NetNode variables can be divided into the following categories:
• NetNode's own state variables , such as ISocket object, current state, connection parameters, etc.
• Various callbacks , including connection, disconnection, protocol processing, network prompts, etc.
• Various timers , such as heartbeat and reconnection related timers.
• Both the request list and the listen list are used to process received messages.

Next, we will introduce the network-related member functions. First, let's look at the initialization and:

• The init method is used to initialize NetNode, mainly to specify processing objects such as Socket and protocol.
• The connect method is used to connect to the server.
• The initSocket method is used to bind the Socket callback to the NetNode.
• The updateNetTips method is used to refresh the network tips.

The onConnected method is called after the network connection is successful, and the authentication process automatically begins (if _connectedCallback is set). After the authentication is completed, the onChecked method needs to be called to make NetNode enter a communicative state. In the case of unauthenticated, we should not send any business requests, but requests such as login verification should be sent to the server. Such requests can be forced to be sent to the server with the force parameter.

Receiving any message will trigger onMessage. First, the data packet will be verified. The verification rules can be implemented in your own ProtocolHelper. If it is a legal data packet, we will update the heartbeat and timeout timers - re-time, and finally find the processing function of the message in _requests and _listener. Here, we search through rspCmd. rspCmd is taken from getPackageId of ProtocolHelper. We can return the command or sequence number of the protocol, and we can decide how the request and response correspond.

onError and onClosed are called when the network fails and is closed. Regardless of whether there is an error or not, onClosed will be called eventually. Here we execute the disconnection callback and do the automatic reconnection processing. Of course, you can also call close to close the socket. The difference between close and closeSocket is that closeSocket just closes the socket - I still want to use the current NetNode and possibly restore the network with the next connect. And close clears all states.

There are three ways to initiate a network request :

The send method simply sends data. If the network is currently disconnected or verification is in progress, it will enter the _request queue.

The request method passes the callback in the form of a closure when making a request. The callback will be executed when the response to the request comes back. If there are multiple identical requests at the same time, the responses of these N requests will be returned to the client in sequence, and the response callbacks will also be executed in sequence (only one callback will be executed at a time).

requestUnique method, if we do not want to have multiple identical requests, we can use requestUnique to ensure that there is only one request of each type at the same time.

The reason why we use traversal _requests to ensure that there is no duplication here is that we will not accumulate a large number of requests in _requests, and timeout or abnormal retransmission will not cause a backlog of _requests, because the retransmission logic is controlled by NetNode, and when the network is disconnected, we should block users from initiating requests. At this time, there will generally be a full-screen mask - a prompt such as network fluctuations.

We have two types of callbacks. One is the request callback mentioned above. This callback is temporary and is usually cleaned up immediately with the request-response-execution. The _listener callback is permanent and needs to be managed manually, such as listening when opening a certain interface, closing it when leaving, or listening at the beginning of the game. Suitable for processing active push messages from the server.

Finally, there are timers related to heartbeat and timeout. We send a heartbeat packet every _heartTime, and if we do not receive a packet returned by the server every _receiveTime, we determine that the network is disconnected.

For the complete code, you can enter the source code to view it!

NetManager

NetManager is used to manage NetNode. This is because we may need to support multiple different connection objects, so we need a NetManager to manage NetNode. At the same time, as a singleton, NetManager can also facilitate us to call the network.

export class NetManager {
	private static _instance: NetManager = null;
	protected _channels: {
		[key: number]: NetNode
	} = {};
	public static getInstance(): NetManager {
		if (this._instance == null) {
			this._instance = new NetManager();
		}
		return this._instance;
	} // Add Node and return ChannelID    
	public setNetNode(newNode: NetNode, channelId: number = 0) {
		this._channels[channelId] = newNode;
	} // Remove Node    
	public removeNetNode(channelId: number) {
		delete this._channels[channelId];
	} // Call Node connection public connect(options: NetConnectOptions, channelId: number = 0): boolean {
		if (this._channels[channelId]) {
			return this._channels[channelId].connect(options);
		}
		return false;
	} // Call Node to send public send(buf: NetData, force: boolean = false, channelId: number = 0): boolean {
		let node = this._channels[channelId];
		if (node) {
			return node.send(buf, force);
		}
		return false;
	} // Initiate a request and call the specified callback function when the result is returned public request(buf: NetData, rspCmd: number, rspObject: CallbackObject, showTips: boolean = true, force: boolean =
		false, channelId: number = 0) {
		let node = this._channels[channelId];
		if (node) {
			node.request(buf, rspCmd, rspObject, showTips, force);
		}
	} // Same as request, but before requesting, it will first determine whether there is already rspCmd in the queue. If there is a duplicate, it will be returned directly public requestUnique(buf: NetData, rspCmd: number, rspObject: CallbackObject, showTips: boolean = true, force:
		boolean = false, channelId: number = 0): boolean {
		let node = this._channels[channelId];
		if (node) {
			return node.requestUnique(buf, rspCmd, rspObject, showTips, force);
		}
		return false;
	} // Call Node to close public close(code ? : number, reason ? : string, channelId: number = 0) {
		if (this._channels[channelId]) {
			return this._channels[channelId].closeSocket(code, reason);
		}
	}

Test Examples

Next, we use a simple example to demonstrate the basic use of the network framework. First, we need to assemble a simple interface for display, 3 buttons (connect, send, close), 2 input boxes (enter the URL, enter the content to be sent), and a text box (display the data received from the server), as shown in the figure below.

This example connects to the official websocket address echo.websocket.org. This server will return all the messages we send to it to us as is.

Next, implement a simple Component. A new NetExample.ts file is created here. The task is very simple. During initialization, NetNode is created and the default receiving callback is bound. In the receiving callback, the text returned by the server is displayed in msgLabel. Next is the implementation of several interfaces for connection, sending and closing:

// Uncritical code omitted @ccclassexport
default class NetExample extends cc.Component {
	@property(cc.Label)
	textLabel: cc.Label = null;
	@property(cc.Label)
	urlLabel: cc.Label = null;
	@property(cc.RichText)
	msgLabel: cc.RichText = null;
	private lineCount: number = 0;
	onLoad() {
		let Node = new NetNode();
		Node.init(new WebSock(), new DefStringProtocol());
		Node.setResponeHandler(0, (cmd: number, data: NetData) => {
			if (this.lineCount > 5) {
				let idx = this.msgLabel.string.search("\n");
				this.msgLabel.string = this.msgLabel.string.substr(idx + 1);
			}
			this.msgLabel.string += `${data}\n`;
			++this.lineCount;
		});
		NetManager.getInstance().setNetNode(Node);
	}
	onConnectClick() {
		NetManager.getInstance().connect({
			url: this.urlLabel.string
		});
	}
	onSendClick() {
		NetManager.getInstance().send(this.textLabel.string);
	}
	onDisconnectClick() {
		NetManager.getInstance().close();
	}
}

After the code is completed, mount it under the Canvas node of the scene (other nodes are also OK), and then drag the Label and RichText in the scene to the property panel of our NetExample:

The running effect is as follows:

summary

As you can see, the use of Websocket is very simple. We will encounter various requirements and problems during the development process. We need to implement a good design and solve the problems quickly.

On the one hand, we need to have a deep understanding of the technology we use. How is the underlying protocol transmission of websocket implemented? What is the difference between tcp and http? Can UDP be used for transmission based on websocket? When sending data using websocket, do I need to sub-packetize the data stream myself (the websocket protocol ensures the integrity of the packet)? Is there any accumulation of send buffer when sending data (check bufferedAmount)?

In addition, we need to understand our usage scenarios and needs. The more thorough our understanding of the needs, the better the design. Which requirements are project-specific and which are generic? Are common requirements mandatory or optional? Should we encapsulate different changes into classes or interfaces and implement them using polymorphism? Or provide configuration? Callback binding? Event notification?

We need to design a good framework to suit the next project and optimize iterations in each project, so that we can build deep experience and improve efficiency.

The above is the detailed content of the network of CocosCreator general framework design. For more information about the network of CocosCreator framework design, please pay attention to other related articles on 123WORDPRESS.COM!