Tunnelcast for Unreal Tournament 4
==================================

Tunnelcast relays your server's chat, joins and match events to Discord and to the
Tunnelcast Portal.

This is an unofficial community tool. It is not affiliated with or endorsed by Epic Games.

You need a dedicated server running the Unreal Tournament 4 pre-alpha, on Windows or
Linux, and a server token from the Tunnelcast Portal (https://www.tunnelcast.app).


What's in this package
----------------------

  Windows\Tunnelcast\     The Tunnelcast plugin for a Windows server
  Linux\Tunnelcast\       The Tunnelcast plugin for a Linux server
  Tunnelcast.ini          Configuration template (add your server token)
  README.txt              This file

This package contains only Tunnelcast's own code. It does not contain any files from
Unreal Tournament 4: you need your own copy of the game server.

The Linux build is new and has had less testing than the Windows build so far.


Installing
----------

1. Stop the server.

2. Copy the Tunnelcast folder for your platform (Windows\Tunnelcast or Linux\Tunnelcast)
   into the server's UnrealTournament/Plugins/ folder, so you end up with
   UnrealTournament/Plugins/Tunnelcast/Tunnelcast.uplugin.

3. Copy Tunnelcast.ini into the server's config folder:

     Windows:  UnrealTournament/Saved/Config/WindowsServer/
     Linux:    UnrealTournament/Saved/Config/LinuxServer/

   If you are updating and already have a Tunnelcast.ini with your token in it, keep
   your own file and copy only the plugin folder. (If you skip this step, Tunnelcast
   writes the file there itself the first time the server starts.)

4. Open Tunnelcast.ini and put your server token after Token= so the line reads
   Token=your-token-here (no quotes, no spaces).

5. Start the server. The log shows "Tunnelcast 0.1.0 loaded", then
   "authenticated with the relay" once it is connected.

There is nothing to add to the command line or to a mutator list: Tunnelcast loads
with the server. Only the server needs these files. Players do not download anything.

Tunnelcast reads its settings when the server starts. Stop the server, edit
Tunnelcast.ini, then start it again.


Settings
--------

All of these are in Tunnelcast.ini under [/Script/Tunnelcast.TunnelcastSettings]. The
value shown is the default.

  Token=
      Your server token from the Tunnelcast Portal. While it is empty Tunnelcast does
      not connect, and says so in the server log.

  HostName=gateway.tunnelcast.app
  Port=13000
      Where Tunnelcast connects to. Leave as is. The server must be allowed to make
      outgoing TCP connections to this address and port.

  ReconnectInterval=5
      Seconds to wait before the first reconnect attempt. The wait doubles after every
      failed attempt, up to one minute.

  bAllowRemoteControl=True
  +DisabledRemoteCommands=
      See "Remote control" below.

  bRelayHubInstances=False
      See "Hubs" below.

  bDebug=False
      Leave off. When on, everything sent and received is written to the server log.
      The token is left out, but the log grows quickly.


Remote control
--------------

These commands can be sent to your server from Discord and the Tunnelcast Portal: kick
a player, ban a player, unban a player, switch the map, restart the map, and restart
the server. You decide how much of that your server accepts:

  bAllowRemoteControl=False
      Refuses every remote command.

  +DisabledRemoteCommands=kick
      Refuses one command. Use one line per command you want to refuse:
      kick, ban, unban, switchmap, restartmap, restartprocess.
      +DisabledRemoteCommands=* refuses all of them.

A refused command is written to the server log and nothing else happens.

"Restart server" (restartprocess) makes the server exit. It does not start it again.
Run the server from a restart loop or a service wrapper that starts it again when it
exits, or refuse the command with +DisabledRemoteCommands=restartprocess.


Hubs
----

Install Tunnelcast on the hub, with the hub's own token. The hub lobby relays who joins
and leaves it, and reports every match it is running (map, mode, state, time, team
scores and players), so your live status in Discord shows each match on its own card.

The match servers a hub starts load the same plugin and the same Tunnelcast.ini. They
stay silent, because the hub already reports them. The same goes for a dedicated server
that joins a hub (started with ?Hub=...?HubKey=...), even when it has a token of its
own. To have such a server relay as a server of its own, set bRelayHubInstances=True
in its Tunnelcast.ini and give it its own token. Never turn this on for match servers
that share the hub's Tunnelcast.ini.


Relay notice
------------

Tunnelcast tells every player that chat on your server is relayed. About 30 seconds
after they join, only that player sees:

  [Tunnelcast] Chat here is relayed to Discord, networked servers, and the web portal. It is public.

The text is fixed. It can't be changed or turned off. A player your server hasn't told
yet always sees it.

You choose how often a returning player sees it again in the Tunnelcast Portal, on
your server's Relay Settings tab, under Relay Notice: on every join (a map change counts
as a join), or after 1 hour up to 30 days (24 hours by default).
Step by step: https://www.tunnelcast.app/guides/relay-notice

To remember who has seen it, Tunnelcast keeps a short list in
UnrealTournament/Saved/Tunnelcast/relay-notice.txt. Each entry is a one-way key made
from the player and their name, plus the time the notice was shown. No names or IP
addresses are stored in it.

You are responsible for informing your players that their chat is relayed. The notice
helps, but it doesn't replace that. See the Terms of Service:
https://www.tunnelcast.app/terms


Troubleshooting
---------------

Nothing about Tunnelcast in the server log
    The plugin is not being loaded. Check that the folder is at
    UnrealTournament/Plugins/Tunnelcast/ (not one folder deeper) and that you copied
    the folder for the right platform.

"no relay token is configured"
    Token= in Tunnelcast.ini is empty, or the file is not in the config folder from
    step 3. Stop the server, fix it, start it again.

"authentication rejected"
    The line says why. Usually the token was copied incompletely, or it belongs to
    another server. Stop the server, copy the token again from the Portal, start it again.

It keeps saying "reconnecting in ... s"
    The server can't reach gateway.tunnelcast.app on TCP port 13000. Check the firewall
    and the HostName and Port settings.

"This process is a hub match instance and bRelayHubInstances is off"
    This is a match server of a hub, and its matches are reported by the hub. See "Hubs".


Licences
--------

Using Tunnelcast is subject to the Terms of Service at https://www.tunnelcast.app/terms


Tunnelcast is not affiliated with or endorsed by Epic Games. Unreal and Unreal
Tournament are trademarks of their owner.
