Create mods with your friends! Go online with the WORLD BUILDER
10/05/2015
10/05/2015

Overview

The EMERGENCY 5 online editor consists of two parts:

  • The online editor client
  • The online editor server

While the online editor client is identical to the offline editor, you first have to create a server. In case you joined a mod project for which someone else created and hosts an online editor server, you can skip the part about setting up a server.

There are only a few differences in the offline and online editor client you need to know about:

  • When working with the online editor client, you don't need to save your work. Every operation is automatically submitted to the online editor server which is responsible for the rest of the management.
  • When using the online editor client, NEVER manipulate data inside "em5game/data" directly. Do only use the online editor client to work on data. Otherwise the online editor server will not be notified about any changes, other users will not see your changes and the work is for naught.
  • You can set up user rights that can be used to limit what a user can do. Inside the preferences dialog you’ll see your current user rights given to you by the online editor server administrator.
  • By selecting entities, you lock them. No one else will be able to select and edit those locked entities. Entities locked by other users are visually marked by a colored square – move your mouse cursor over such a locked entity and in you’ll see the name of the user which currently has the lock on the entity in your status bar.
  • Undo/redo also works when using the online editor client. As long as an entity is inside your undo history, you’ll still lock it. Be polite and erase your undo history from time to time. Press the corresponding button in the toolbar to do so.
  • By using the asset history, it's possible to revert an asset to a previous asset revision.

Online Editor Client

WARNING

  • Do NOT put your Online Editor Client in the same place as your offline game directory unless you want to risk losing data. If you want to edit content via the online editor client, please copy your game directory FIRST.

 

Enabling the EMERGENCY 5 online editor

By default, the EMERGENCY 5 editor is configured as offline editor. In order to make it possible to connect to an editor server, open the file "bin\editor.app" with an text editor and change

  • "EditorServerHostPort": "offline:4242"

to

  • "EditorServerHostPort": ""

 

When starting the editor, you will now see the connect dialog. There's an auto-connect feature, so if you don't see the connect dialog and still end up in the offline editor, disconnect the editor by pressing "Menu -> File -> Disconnect". The connect dialog will appear.

 

Connecting to an EMERGENCY 5 online editor server

In the connect dialog, you have to enter the server address and port.

 

The offline and online editor clients are identical. Basically, there are three options: Offline, local and remote server.

  • Offline: An editor client will become an offline editor client by "connecting" to an offline editor server (you don't need to create one in this case) by writing "offline" into the editor server address field. The port does not matter for the offline editor.
  • Local: In case the online editor server is set up on the same computer as the online editor client, there's no need for an Internet connection. For example: If the local online editor server is running on port 4042, the editor server address would be "localhost:4042".
  • Remote: For cooperative work, this is the common use case. You need to know the server address and port to be able to connect to it. For example, a server address could be "mytestem5onlineeditorserver.de," where the online editor server instance is available over port 4042.

After successfully connecting to an online editor server, the next dialog you will see is the login dialog were you have to put in your user name and the password you received from the online editor server administrator. The last step is choosing a map to work on in the project map dialog and you're ready to go.

Online editor server and online editor client version mismatch
When the online editor server and online editor client are not the same version, you can't connect for security reasons by default. If you know what you're doing, you can skip this security version check feature by opening the "qsf_editor_settings.json" file inside your user directory and setting the following:

"
},
"qsf::editor::DeveloperSettingsGroup":
{
   "IgnoreEditorServerHostPort": "true",
   "IgnoreEditorServerVersionCheck": "true"
},
"qsf::editor::RenderingSettingsGroup":
{
"
Setting "IgnoreEditorServerVersionCheck" to "true" disables the version check, setting "IgnoreEditorServerHostPort" to "true" also disables the hard wired server connection.


Online Editor Server

  • Note: This section is meant for online editor server administrators.
  • WARNING
    • The online editor server needs its own work directory. DO NOT put it in your EMERGENCY 5 installation directory unless you want to risk data loss. Here’s why: For the server, the directory "em5game/data" is just a dump of assets. THE SERVER CAN AND WILL DELETE FILES IT DOESN’T RECOGNIZE.
    • The editor server is managing asset revisions. If you plan on using the online editor server not only for a quick experiment, we highly recommend at least 50 GB of free disk space.

The EMERGENCY 5 SDK is shipped with a pre-configurated editor server you can find inside "/editor_server". The online editor server is an MS Windows console application running on a computer and communicates over a port with the world. The executable is located at "/editor_server/bin/x64r/qsf_editor_server.exe". Creating an online editor server instance consists of the following steps:

  • Starting the online editor server application by using e.g. "start_editor_server.bat".
  • Setting up the server with initial data to not start with a completely blank server

Starting the Online Editor Server Application

The online editor server stores its data inside the "/editor_server/server" directory. When starting the online editor server for the first time, the server directory will be created automatically as well as an administrator user account named "admin". The password is automatically generated and will be written into the log, which you can find in "/editor_server/server/etc/log" directory after booting up the server for the first time. Inside the server log, look for something like "[QSF info] Generated new password for user "admin": "Y34Bwzoy5qKPCHUbicOg0lBqsDNy0NLa"".

Ensure that the application will not be blocked by the Windows firewall. This topic is part of server administration 101. Google will guide you if you don’t know how Windows Firewall works. The port the online editor server is available over can be configured inside "/editor_server/server/etc/qsf_editor_server_settings.json” by using a text editor. For example, you can set "AssetServerPort" to 4042 (which is the default setting). If your server address is "mytestem5onlineeditorserver.de", an online editor client user would then use "mytestem5onlineeditorserver.de:4042" to connect to this online editor server. As soon as you can read "QSF started server 0.0.0.0 at port 4042" inside the MS Windows command prompt, you the online editor server is now up-and-running and users can connect to it.

In order to add new online editor users, start the online editor client and log in with your admin account. When using your admin account, you have access to the server management dialog which is found in the file menu. This server management dialog enables you to edit users which are stored in the file "/editor_server/server/users/users.json".

On shutdown, the server will automatically save the latest asset revisions in "/editor_server/data" which is used by the offline editor and the game. In case you want to switch a project from online editing mode to offline editing-mode, you can easily do so by just continuing to use the offline editor client. When switching a project back into online editing mode, you have to create and set up a new server.

 

Setting up the server with initial data

It's possible to set up a newly created server with content that has been edited via the offline editor. When logged into the online editor server with an administrator account the first time, the server is automatically set up with the initial data of the client. This is a lot of data, so it might take a while.

Notes

  • In case errors like "missing local file" come up, please use the asset maintenance (menu -> file -> asset maintenance) to locate and resolve the issues so that the asset database is in an consistent state.

 

Making the online editor server available over the Internet

Use Google to find information about “port forwarding”

You have to do a port forwarding for the port specified as "AssetServerPort" in the configuration with protocol UDP with target ip/hostname the IP/hostname of the PC which is hosting the asset server

You have to do it manually if you don't want to use forwarding via UPNP or it doesn't work (e.g. the firewall/router doesn't support forwarding via UPNP)

In order to enable port forwarding via UPNP, open the "server\etc\qsf_editor_server_settings.json" configuration file and change the value "qsf::editor::server::ServerSettingsGroup" -> "EnablePortForwardingViaUpnp" to "true". For security reasons, this option is disabled by default.