Tunnelcast for Unreal Gold
==========================

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 Unreal Gold with the OldUnreal 227i patch, and a
server token from the Tunnelcast Portal (https://www.tunnelcast.app).


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

  Tunnelcast.u            The Tunnelcast server mod
  JsonLib.u, EventBus.u   Supporting libraries
  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 Gold: you need your own legitimately licensed copy of the game.


Installing
----------

1. Stop the server.

2. Copy these four files into the server's System folder:

     Tunnelcast.u
     JsonLib.u
     EventBus.u
     Tunnelcast.ini

   If you are updating and already have a Tunnelcast.ini with your token in it, keep
   your own file and copy only the three .u files.

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

4. Open the server's ini (Unreal.ini unless you start the server with another one), find
   the [Engine.GameEngine] section and add this line below the ServerActors= lines that
   are already there:

     ServerActors=Tunnelcast.TunnelcastServerActor

   Add it once. Tunnelcast is a server actor on this game, not a mutator: do not put it
   in ?Mutator= on the command line.

5. Start the server. The server's console window and its log show a "Tunnelcast"
   banner with the version, then "Authentication successful" once it is connected.

Only the server needs these files. Players do not download anything.


Always stop the server before editing Tunnelcast.ini
----------------------------------------------------

Tunnelcast reads its settings when the server starts, and saves them back to
Tunnelcast.ini every time a map starts. A change you make while the server is running
is not picked up and can be overwritten. Stop the server, edit, then start it again.


Settings
--------

All of these are in Tunnelcast.ini under [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.

  bAutoReconnect=True
      Reconnect on its own when the connection is lost.

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

  MaxReconnectInterval=60
      The longest wait between two reconnect attempts, in seconds.

  ConnectTimeout=10
      Seconds a connection attempt may take before it is given up and tried again.

      These three are real seconds. The game speed does not change them.

  MaxQueuedEvents=1000
      How many events are kept while the connection is down, to be sent when it is
      back. When the list is full the oldest event is dropped. 0 means no limit.

  ChatSpectatorName=Discord
      The name that chat coming from Discord is shown under in the game. A line reads
      "Discord: <Name> message". Chat from the Portal is shown under "Web" and chat from
      other servers under "Network".

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

  bDebug=False
      Leave off. When on, a logged-in server admin can use Tunnelcast's debug console
      commands.

  bDebugDataFlow=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.

  RemoteProcessingEventBusSubscriberClass=...
  GameHandlers=...
      Advanced. Leave as is.

Under [Tunnelcast.Plugin_RelayNotice], a section Tunnelcast adds to the file itself
once the server has run:

  NoticeDelay=30
      Seconds after a player joins before they see the relay notice (see below).
      30 is the default. Anything below 0 counts as 0 and anything above 120 counts
      as 120.

  RepeatMinutes and SeenPlayers appear in the same section. Tunnelcast writes them
  itself. Do not edit them.


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

Five commands can be sent to your server from Discord and the Tunnelcast Portal: kick a
player, ban 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, 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.


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

This game gives a server no unique id for a player, so a player counts as the same
player when both their network address and their name match. A new name or a new
address gets the notice again. To remember who has seen it, Tunnelcast keeps a short
list in Tunnelcast.ini (SeenPlayers). Each entry is a one-way key made from the address
and the name, plus the time the notice was shown. No names or IP addresses are stored
in it, and entries are removed once the interval has passed.

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
    Tunnelcast is not being loaded. Check that the ServerActors= line from step 4 is in
    the [Engine.GameEngine] section of the ini the server really starts with, spelled
    exactly as shown. Also check that the three .u files are in System.

The log says "Add mutator Tunnelcast.TunnelcastServerActor" but there is no Tunnelcast banner
    Tunnelcast was added as a mutator (?Mutator=... on the command line, the way it is
    done on Unreal Tournament). On this game that loads the files and then does nothing:
    no banner, no connection, and no error. Remove it from the command line and add the
    ServerActors= line from step 4 instead.

"Tunnelcast is installed more than once on this server"
    The ServerActors=Tunnelcast.TunnelcastServerActor line is in the ini more than once.
    Only the first one runs. Stop the server and remove the extra lines.

"No token is set, so Tunnelcast is not connecting"
    Token= in Tunnelcast.ini is empty. Stop the server, add the token, 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 ... seconds"
    The server can't reach gateway.tunnelcast.app on TCP port 13000. Check the firewall
    and the HostName and Port settings.

My change to Tunnelcast.ini is gone
    It was edited while the server was running. Stop the server first.


Licences
--------

JsonLib and EventBus are open source under the MIT licence:
  https://github.com/Tunnelcast/jsonlib-unrealgold
  https://github.com/Tunnelcast/eventbus-unrealgold

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 is a trademark of
its owner.
