Developers Manual > Cocos2d-x > How To > User Contributed Tutorials > User Tutorial-Console Tutorial

Console Tutorial

Contributed By: Lef

NOTE: Console doesn't supported on WINRT and Windows Phone

Console Example

Introduction

If you have ever played Counter-Strike or other game from Valve, you probably know what Console is (Valve page)
Image Title
"The console provides a command-line interface for the advanced configuration...", it means that you can change any in-game variable without code recompilation, plus you can see logs and other useful data.
In cocos2dx was added cool new feature "Console" that does the same job! And it's really easy to add Console to your game.

Implementation

OK, first, let's create new project. I hope you are already familiar with creating a new project, otherwise, just read this page.
Now open the project and go to AppDelegate.cpp, find applicationDidFinishLaunching method and before scene creation add the following code

1
2
auto console = director->getConsole();
console->listenOnTCP(1234);

Pretty easy, huh? We get global instance of console and say "listen to all connections on port 1234".
That's it! You added console to your game.
Build and Run.

Nothing changes, isn't it? If you look closer, you will see new log in output console cocos2d: Console: listening on 0.0.0.0 : 1234.
To connect to your game in OS X and Linux you should open Terminal and run command telnet 0.0.0.0 1234, in Windows use a cmd or powershell window. If you don't have telnet installed you should be able to enable it:
Go to Control Panel -> Programs and Features -> Turn Windows features on or off -> Telnet Client
Image Title
NOTE: if you run game on real device or another computer, instead of 0.0.0.0 type in your device local IP address, something like 192.168.0.122
Image Title
What happens? Now Terminal is connected to your game.

Built-in commands

Let's see some basic built-in commands. Type in connected with your game Terminal help
Image Title
First column contains command name, second command description.

Let's try the basic command: turn on and off FPS counter. Typing in fps without arguments, we will be able to see if FPS counter is "on" or "off".
If you want hide FPS counter, type fps off and the counter will disappear.
If you want see all logs from CCLOG(...) in Terminal, type debugmsg on.

There are much more good built-in commands, try them all!

User commands

Built-in commands are good, but you can also add your own commands.
Open Helloworld.cpp, at the top add includes

1
2
3
4
5
6
7
8
9
#if (CC_TARGET_PLATFORM != CC_PLATFORM_WIN32)
    #include <unistd.h>
    #include <sys/types.h>
    #include <sys/socket.h>
    #include <netdb.h>
#else
    #include <io.h>
    #include <WS2tcpip.h>
#endif

Then go to init method and right after return true; add this code

1
2
3
4
5
6
struct Console::Command command ={
    "label",
    "Change or print the current label string. Args: [<label string>]",
    [label](int fd, const std::string& args) {
        // add callback code here
    }};

Don't be afraid, this is very simple. First of all, we define new variable with type of Console::Command. What is Console::Command? This is simple structure with three fields: string with command name, string with command description and callback function

1
2
3
4
5
struct Command {
    std::string name;
    std::string help;
    std::function<void(int, const std::string&)> callback;
};

Now you understand how do we initialize our command? We set our command name to "label",
description to "Change or print the current label string. Args: [<label string>]" and empty callback function.

Let's look closer at callback function. This is lambda function with two arguments: first - file descriptor, use it if you want to send response and second - args, any text after command name, for example if we type in terminal label test 1 2 3, args will be equal to test 1 2 3.

Don't forget to add command to console using the code below

1
2
auto console = Director::getInstance()->getConsole();
console->addCommand(command);

Build and Run.
Now if you type help you will be able to see, that the new command was added to commands list.
Image Title
But if we call our command, nothing happens because our callback function is empty.
Let's add some logic

1
2
3
4
5
6
7
8
9
10
if (args.length()==0)
{
    const std::string& str = label->getString();
    send(fd, str.c_str(), str.length(), 0);
    send(fd, "\n", 1, 0);
}
else
{
    label->setString(args);
}

What does this code do? If you just type label, our callback function will send response with label's text, otherwise we set label's text with args value.

Conclusion

Now you have great tool in your pocket that can helps your with debugging and controlling your game.
Youtube:
IMAGE ALT TEXT HERE
Tutorial sources on Github
Feel free to ask me anything, i love feedback!
English isn't my native language, if you find grammatical mistakes, please write back

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.