1. Development Environment

1.1. Installing iFun Engine

iFun Engine runs on Ubuntu 16.04 LTS or 14.04 LTS (64bit) or CentOS 6 or 7 (64bit). Game developer can develop using the traditional C++ toolchain or CLion IDE (if working directory on a Linux desktop machine.)

Tip

Also possible to develop on MS Windows using Visual Studio. This requires an external plug-in named VisualGDB . Please refer to Developing on MS Windows for more information.

1.1.1. Ubuntu 16.04 LTS or 14.04 LTS (64bit)

First, you need a Ubuntu 14.04 / 16.04 box. If you have one, yet, you can get one from your favorite IaaS cloud service provider such as Amazon Web Services and Azure. Or, you can install one as a local virtual machine using VMware or VirtualBox (In this case, you may need an Ubuntu install image from Ubuntu releases page)

Important

Please make sure your Ubuntu box is 64bit. iFun Engine does not support 32bit Ubuntu.

After installing Ubuntu, you need to add iFun Engine’s apt repository. This can be easily done through iFun Engine auto-setup package. Please download the package and double click on it to install. If you prefer Linux shells, you can do like this:

$ wget https://ifunfactory.com/engine/funapi-apt-setup.deb
$ sudo dpkg -i funapi-apt-setup.deb

Note

You may need to install wget with HTTPS capability first, if your Ubuntu is not equipped with the tool. Please run the following command first if you see such an error message.

$ sudo apt-get install wget apt-transport-https

Tip

If you are behind a firewall preventing outgoing traffic

The guideline mentioned above needs to contact following servers:

  • www.ifunfactory.com (54.65.9.158; subject to change)
  • keyserver.ubuntu.com (PGP key server; optional)

If your data center has strict policy on outgoing traffic, the guideline may not work for you. In this case, you can manually add iFun Engine’s PGP key and set up an apt repository.

Save the PGP key as ifunfactory.gpg.key.

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1

mQENBFHLrjgBCACzI7l8y1nygGN1b0XwgEDdBZGUlaTZhyHs1Y2VLBmYm3dgyRHp
qLfHhVGZm1FXzT1X7GlGgQRV+GsyeXNUHWcY794UwZMCM4h0mGDGXX1eR2objUNZ
tVE9VzoXwKwnu7mKJGXgSm+olZKQ43wPnr7Keyap42yKSJv3GBkMmfKjwnjTooLk
g62wwpJa3AOZBBqLwHKt0BYVRT/7ILXJnW4NqDoQPeT1y3Iqt1KxsaR1Ik+byh3g
UUvDqgFRXPW+HDkB265MbQgXHmPTGih8j7ygZz1dM5pJQ//bMqNHmbDPZSwLt0Wb
yB6UNbO9W5ZENCz4h7+3utYAvwERqdZ/nxKZABEBAAG0L0Z1bmFwaSBTdXBwb3J0
IDxmdW5hcGktc3VwcG9ydEBpZnVuZmFjdG9yeS5jb20+iQE4BBMBAgAiBQJRy644
AhsDBgsJCAcDAgYVCAIJCgsEFgIDAQIeAQIXgAAKCRCj9+/dSTj/5jzNB/45CD2R
Bv8CrB+ErIVeFjXuhqYwg2fuAdQcXbVpla5rhrvHjGEbCl35kKqEPFP09YvWReIi
i3kK1yF7zNxyk/9N3GUZpIEgbyEuNVjkizPjrs+DWx0j6oZZQLrsEflUMxfALAmr
v3n6fB6XeCk2Hd83XBoqZSHKfzLPFUynS7e2/Vte4UVKbgFPsypPXazYrqvq4ej2
bnHva6/aUakti+A+l8Cs0kf2WzrwOp47PcceT5N0/mwF5XslwaiqH6q+6iGNLdj0
9hjzRcdZ5My/Do6rGXcFJJY17U72HGFTUCU8RXZRTBY2EfjAV6zQlKlaO/Aw0eWX
7UMXUhc+CLv+aZOxuQENBFHLrjgBCAC/xHRd1tH2zs8nplyI3EYRyWqF82waGIyK
SnV/pJ4CCc2YuECnQV0RvoOtZiuwmB3CuNTSEEyAfwU/K3tMsvczMN04MjQGvSA1
4it7xIkg24Qcx0O46JBwvihR4sZ8O/j6X/nVV4pN4zUg5PQh///yn/R7mVH2sWVW
WE5ZpZ1G/eA/fSiqdmZPOjFW9SWsVgPXvyKCM0b5lCjMlbwZspx8YGblJtDqCtWW
Ip2RnGTCSkSo4kRauDU+iGYojUsgsmUSxjtdGZHa41g5HDRoIcL3e40UYe3el7Sx
Aa+lV529kHAZCWtDfS7MoqtE7gvHSGoJAK+2nCAEfw1mz0Ja+XELABEBAAGJAR8E
GAECAAkFAlHLrjgCGwwACgkQo/fv3Uk4/+Y36Qf/VPov5n+h4pEzKspA6hHezD4J
rw9rVCQ/BvidBerV4VvL+oH5ghBV5QeAvd2TyccuKdZJsikAM9wUM1MS+Y4Akno7
vgIKO/7sGGkbAkgSG4vvfG4W9EQ0GqFycaTl9zpiNUrUri5vGNK2PC6p9uXxXmdQ
3iHe1c5+5jvLKCzOdC+Er2E949PzsMuI2L4viNp72J6ilm62RJ+/Pg1rOaRmTH1H
ax7L3Hwsy0GXeubKaeDizvBeKcv6e08DqI2TCllmd8NkR6OSLuks4yHDU1ztAa0c
+RcnddKag+TCYwto617oMZvCPaic/d6AjW3OL48PFNUPpfBeZEJ8B8tm16HxaQ==
=p+5n
-----END PGP PUBLIC KEY BLOCK-----

Then install the GPG key like this:

$ sudo apt-key add ifunfactory.gpg.key
OK

Finally, save the repository line below as /etc/apt/source.list.d/ifunfactory.list.

deb [arch=amd64] https://www.ifunfactory.com/apt/ trusty non-free foreign

Note

Substitute trusty with xenial if using 16.04 Xenial

After setting up the apt repository, update the package list and install funapi1-dev.

$ sudo apt-get update
$ sudo apt-get install funapi1-dev

The command above installs the iFun Engine development package and its run-time package along with packages on which iFun Engine depends.

If you are planning to run MySQL and Apache Zookeeper for iFun Engine’s distribution feature, install them, too. This is typically the case where you set up per-developer development environment on a single machine.

$ sudo apt-get install mysql-server
$ sudo service mysql start

$ sudo apt-get install zookeeper zookeeperd
$ sudo service zookeeper start

Important

The installation process automatically acquires a temporary license valid for 7 days. You can obtain a trial license valid for 6 months from the Trial license application page. Do not forget to check it out.

1.1.2. CentOS 6 or 7 (64bit)

Installing on CentOS is similar to on Ubuntu. All the steps are the same, but you will use yum, instead of apt, as a package manager.

First get a CentOS machine. As with the Ubuntu case, you can get one from IaaS provider like AWS, or install one as a virtual machine on your workstation. (In case you need a installation image, please visit CentOS download page .

Important

Please make sure you have 64bit CentOS 6 or 7. Older CentOS versions are not supported. And 32bit is not supported, either.

To add iFun Engine’s yum repository, install iFun Engine auto-setup package for CentOS . Download and double click on the package. Or you can install using shell commands like this:

$ sudo yum install epel-release wget
$ wget https://ifunfactory.com/engine/funapi-yum-setup.rpm
$ sudo rpm -Uvh funapi-yum-setup.rpm

After adding the repositories, update package lists and install funapi1-devel.

$ sudo yum update
$ sudo yum install funapi1-devel

The install command above will install iFun Engine’s development package and run-time package as well as all the packages on which iFun Engine depends.

You also need MySQL as a user data storage and Zookeeper to enable iFun Engine’s distribution feature. If you’re planning to run your development machine on a single machine, install them at the moment.

For CentOS 6:

$ sudo yum install mysql-server
$ sudo service mysqld start

$ sudo yum install zookeeper
$ sudo service zookeeper start

For CentOS 7:

$ sudo yum install mariadb-server
$ sudo systemctl enable mariadb
$ sudo systemctl start mariadb

$ sudo yum install zookeeper
$ sudo systemctl enable zookeeper
$ sudo systemctl start zookeeper

Important

The installation process automatically acquires a temporary license valid for 7 days. You can obtain a trial license valid for 6 months from the Trial license application page. Do not forget to check it out.

1.1.3. Working with MS Visual Studio on Windows

If you are not very familiar with the Linux development environment, you may want to take a look at VisualGDB . It is a Visual Studio plug-in that enables to work from Windows Visual Studio with a remote Linux development machine. Regarding development on Windows, you can find details from Development on MS Windows.

1.2. Creating a new project

Game development with iFun Engine boils down to creating a dynamic library, including the game logic, in a form readable by the iFun Engine framework. However, starting this from scratch requires a steep learning curve, and even when familiar with the framework could get tedious. Thus, iFun Engine provides template code and scripts to simplify the creation of new projects.

Running the following command in the terminal generates a new project called my_project .

$ funapi_initiator my_project

The new project exists in a directory suffixed with ‘-source’ . For example, in the example above the directory is my_project-source. The game development team can share this directory by adding to an SVN repository or a GIT repository.

iFun Engine games created by this method are configured to be built with cmake in the Linux shell or within CLion . The generated source directory structure and build instructions are explained in more detail in the following sections.

1.3. Source directory structure

The source directory generated previously contains the following files.

  • VERSION: contains the version number of the generated game. This file is used to determine the version when packaging your game server. More details explained in Package management.

  • DEBIAN: contains the DEB package information when zipping the generated game in a DEB package. Thus, you must list all dependency information here in the Depends field, if your game server additionally depends on other DEB packages.

  • README: Game developers can add internal information about the game source in this file.

  • LICENSE: Explain the rights for the game here, e.g. for free games.

  • setup_build_environment: This is the script to generate the build directory from the source directory. Depending on the options, you can create CLion build environment or command line build environment.

  • CMakeLists.txt: This is the top-level cmake input file for the project. You will tune cmake variables in this file to control how your game server is built and packaged. If you need to add/remove source files, you should modify src/CMakeLists.txt below.

  • src/: Most of your game code that you’ll add or remove will live in this directory.

    • CMakeLists.txt: This is the cmake input file used by game developers to add or remove source files. Simply add or remove files by modifying variables ADDITIONAL_CPP_SOURCES, ADDITIONAL_PROTO_SOURCES, and ADDITIONAL_LIBRARIES in the file.

    • my_project_types.h: This file contains the type definitions for the iFun Engine game.

    • my_project_loggers.json: This is the game project’s activity logger definition file. More details on the activity logger are here.

    • my_project_server.cc: This is the “main” of the game. As explained in the Component model, iFun Engine games do not have a main function, but one or more game server components . This file defines the game server component.

    • event_handlers.h: my_project_server.cc registers the events that the game processes and the handlers for the client message. These handlers can be defined in arbitrary locations, but games created with funapi_initiator declare the event handlers in event_handlers.h. You can rename/split the file behavior if you want.

    • event_handlers.cc: Contains the implementation of the event handlers declared in event_handlers.h above.

    • MANIFEST.json: This file includes dependencies and configuration for components, including the game server component defined in my_project_server.cc. Through this file you can change the server parameters such as the number of threads in the game, service port, transport protocol, etc. See here for more information about MANIFEST.json.

    • object_model/: This directory contains game object definition files. Details in here.

      • example.json: This is an example game object definition file. Details here.

1.4. Build using command line tools

Previously, you went through how to generate the source directory. The source is in cmake, so you can immediately build with cmake as usual. However, it is best to have separate source and build directories to prevent unnecessary build files from entering the source repository during team development. iFun Engine provides a standard mechanism for this. For users who want to use traditional make in a shell, run setup_build_environment in the source directory as below.

$ my_project-source/setup_build_environment --type=makefile

The command above generates a directory called my_project-build. This directory contains debug and release subdirectories for debug and release builds, respectively. Run make inside your desired directory. For example, the following generates a debug build.

$ cd my_project-build/debug
$ make

1.5. Build in the GUI environment

For developers more comfortable with an IDE environment than the command line, iFun Engine supports CLion on Linux and Visual Studio with VisualGDB on Windows. You can find more details from here:

1.6. Launcher

A iFun Engine game is not a single executable, but a dynamic library (shared object in Linux) recognized by the iFun Engine placeholder executable, /usr/bin/funapi_runner. Therefore, you must use funapi_runner to start your game. However, specifying all the parameters for funapi_runner is very tedious, so a iFun Engine project created by funapi_initiator also has a launcher generated. The launcher is a wrapper for calling funapi_runner with the necessary environment variables and parameters set up for the iFun Engine game.

No matter how you build your project, a ‘-local‘ executable file (e.g., my_project-local) is created after a build. This is the launcher for local development. To run the program manually from the shell, you need to execute this launcher. Debugging or running from CLion or Visual Studio should be done after properly configure the tools according to this launch script.

When running the server with the launcher, use the logtostderr flag if you want to log to the console.

$ ./my_project-local --logtostderr

1.7. Switching Between Distribution Types

iFun Engine is distributed in two different distribution types: stable and experimental. By default, the stable distribution is configured to use once iFun Engine is installed. This can be changed by the bundled utility command named funapi_select_repo.

1.7.1. Checking the current distribution type

The distribution type that is currently configured to use and one from which the installed iFun Engine came can be checked as a follow:

$ funapi_select_repo
Current repository: stable
Current package: funapi1-runtime_1.0.0-1661xenial: stable

The command output describes that the repository for the stable version is configured to use and the iFun Engine installed on the machine is also from the repository.

Note

As described below, the repository currently in use can differ from the repository from which the current iFun Engine installation came, since we can switch between the repositories.

1.7.2. Changing the distribution type

As described earlier, iFun Engine has two distribution types. Stable is the most up-to-date, reliable version but lacks the most recent features. Experimental includes recent features. You can switch between the distribution types by funapi_select_repo.

Please note that the experimental distribution has been selected as highlighted and we updated the packages list. If you run funapi_select_repo without any argument, it shows the current distribution type. .. code-block:: bash

$ funapi_select_repo Current repository: experimental Installed funapi1-runtime does not belong to stable repository Current package: funapi1-runtime_1.0.0-1661xenial: experimental

Then, you can install a specific version using apt-get upgrade or yum update.

Tip

iFun Engine’s version string includes a build number. Since experimental is promoted to stable after stabilization period, experimental packages have higher build number than stable does.

So, switching from the stable to the experimental will seamlessly upgrade the packages for higher build number. But vice versa (i.e., switching from the experimental to the stable) may not automatically upgrade packages. In this case, you need to explicitly give a version string after the package name.

  1. For Ubuntu: $ sudo apt-get install funapi1-dev=<version> funapi1-runtime=<version> libfunapi1-mongodblogger=<version> python-funapi1-dev=<version>
  2. For Centos: $ sudo yum install funapi1-devel-<version> funapi1-runtime-<version> python-funapi1-devel-<version>

To move back to the stable, please do like this:

$ sudo funapi_select_repo stable

1.8. Uninstalling iFun Engine

To uninstall iFun Engine, use apt-get as when you were installing. The following command removes all iFun Engine-related packages.

$ sudo apt-get purge funapi1-*

Attention

Wait! If you are uninstalling because of some difficulties with iFun Engine, please email us about it.