Skip to content

development.md

Latest commit

 

History

History
253 lines (157 loc) · 10.4 KB

development.md

File metadata and controls

253 lines (157 loc) · 10.4 KB

Development

After finishing the local setup you are ready to start developing Teiserver.

This guide should hopefully help you with getting started by showing you some helpful commands and giving you a short introduction to different Teiserver components.

The first things you want to do is check your setup is healthy by running the tests and checking the Teiserver services are up and running, see testing and running Teiserver.

Testing

Run mix test --exclude needs_attention.

If you set up your environment appropriately this should never fail, if it does review your local environment or submit a bug.

Running Teiserver

To run Teiserver locally you can use:

mix phx.server

Or run it in interactive mode with debugging enabled (a REPL is available):

iex --dbg pry -S mix phx.server

Warning

The encrypted services will only be available if you built your local certificates and configured the TEI_TLS_* environment variables accordingly.

When successful, the following services should be available:

Website

The website should be available via the URLs below:

Spring Lobby Server

Available at:

  • Plaintext: telnet localhost 8200
  • TLS: openssl s_client -connect localhost:8201

On successful connection you should receive an initial message from the server as below:

TASSERVER 0.38-33-ga5f3b28 * 8201 0

You can send plaintext messages according to the spring protocol. For example: sending PING should receive PONG.

Tachyon

You should first have a oauth token available, connecting for example with websocat:

  • Plaintext: websocat -H="Sec-WebSocket-Protocol: v0.tachyon" -H="Authorization: Bearer <token>" ws://localhost:4000/tachyon
  • SSL: websocat -k -H="Sec-WebSocket-Protocol: v0.tachyon" -H="Authorization: Bearer <token>" wss://localhost:8888/tachyon

Configuration

Most of the configuration takes place in config/config.exs, being overridden according to the current environment: config/{dev,test,prod}.exs.

After compilation and just before the application starts config/runtime.exs also executes.

Running a release build locally

It's useful to run the release build locally to best reproduce a "production" environment where development facilities are not available and interfering with our application (e.g. performance testing).

Configure teiserver.env appropriately and run:

MIX_ENV=prod mix release --overwrite
set -o allexport; source teiserver.env; set +o allexport
_build/prod/rel/teiserver/bin/teiserver start
# or if you also want a shell
_build/prod/rel/teiserver/bin/teiserver start_iex

Useful tools and commands

Fake data

You will probably want some testing data (users, matches etc.) to make development and testing easier.

Running the following command will generate a large amount of fake data and setup a root account for you:

mix teiserver.fakedata

The database will be populated with false data as if generated over a period of time and the root account will have full access to everything.

Note

Fake data is not perfect and might not be sufficient for your needs. You can modify and expand it by editing the fakedata mix task that generates it.

Resetting your user password

When running locally it's likely you won't want to connect the server to an email account, as such password resets need to be done a little differently.

Run your server with iex -S mix phx.server and then once it has started up use the following code to update your password.

user = Teiserver.Repo.get_by(Teiserver.Account.User, email: "root@localhost")
Teiserver.Account.update_user(user, %{"password" => "password"})

Ignore large mix format passes in git blame

In beyond-all-reason#304 we've started requiring compliance with mix format - this meant we had to use that on the entire codebase.

This obviously breaks git blame, but you can sidestep that by using

git config blame.ignoreRevsFile .git-blame-ignore-revs

The attached .git-blame-ignore-revs file contains a list of commit hashes which modify a large number of lines with trivial changes.

Note

See this blog post by Stefan Judis for reference.

Git hooks

The .githooks directory contains a pre-commit Git hook that will run mix format on staged files before they get commited. To use this (and other Git hooks) you have to first make them executable with

chmod +x .githooks/pre-commit

then use the following command to change the location where Git looks for hook scripts (from the default .git/hooks) to the .githooks directory

git config core.hooksPath .githooks

Working on Teiserver

Teiserver handles a lot: account creation and management, user ratings, balancing, moderation, Discord bot, microblogs, chat, telemetry and more with the introduction of Tachyon.

This section is intended as a short overview of the main Teiserver components.

Tachyon protocol

Tachyon is the new protocol under development, designed to replace the old Spring Lobby Protocol. Check this for a wider overview. In short:

  • The new client is BAR lobby, it'll replace the existing Chobby client
  • The new autohost starting games is Recoil autohost and will more or less replace SPADS, although a lot of what SPADS is currently doing will be done in Teiserver
  • Teiserver is still the same, although the Tachyon related code is isolated from the Spring one

For developping Tachyon, you should also run

mix teiserver.tachyon_setup

This setup the OAuth applications required for Tachyon.

There is also

mix teiserver.gen_token --user CheerfulBeigeKarganeth --app generic_lobby

which generates an access token valid for 24h. These help a lot when attempting to manually test the API.

Spring protocol

The Spring Lobby protocol is the old protocol, in use until everything is ready to fully switch to Tachyon.

Over time the protocol has been extended with additional commands, mainly for the needs of Beyond All Reason, most are also handled by the Chobby client.
The extensions add additional information to lobbies (e.g. team configurations and title updates), broadcast system events (e.g. shutdown) or make party management, user relationships management (e.g. friends, avoids) and reporting easier and possible through the client.

The documentation of the added commands is here.

The relevant code for Spring protocol and it's extensions is mostly in the this directory.

For testing Spring related features you will likely want to set up SPADS.

Discord bot

Teiserver also hosts a Discord bot.
It was originally introduced as a bridge between Discord and game #main channels but has since been expanded with additional features, some of which are: posting moderation action messages and new report messages in the relevant Discord channels, support for custom commands (e.g. looking up units and text callbacks, checking your account stats), linking your Discord account to Teiserver (for receiving lobby/game notifications on Discord, e.g. exiting join queue, game starting), updating player/lobby counter channels on Discord.

Important

The Discord bot is intended to be used only on a single Discord server per Teiserver instance.

Nostrum is the Elixir library used for interacting with Discord.

Most of the relevant Discord bridge bot code is in this directory.

If you want to develop the Discord bridge bot follow this setup guide.

APIs

Teiserver currently has 2 APIs: public API and SPADS API.

Public API

Available publicly without authentication, currently used for getting leaderboards.
Check Public Controller.

SPADS API

Protected and only used by SPADS autohosts to request player ratings, balance games and send end game data to Teiserver.
Check SPADS Controller.

Rating

Teiserver is using the Openskill rating system for rating players.

Note

For more information about Openskill and the rating and balancing system in general check out this BAR official guide.

The Elixir Openskill library used by Teiserver and Beyond All Reason is here.

Balancing

Teiserver is responsible for balancing games based on Openskill ratings. There are several balancing algorithms available, each with its own advantages and disadvantages.

Currently SPADS sends a balance request to Teiserver (over SPADS API) when it detects that the lobby state changed to require a rebalance or after a !balance command is used, Teiserver then balances the game using the default balance algorithm and returns the team configuration to SPADS.

Eventually we want to move the balance algorithms to some external solver which should be more performant and allow development of balance algorithms independently of Teiserver. No work has been done on this so far.

The balance alrogirhtms are located in this directory.

Main 3rd party dependencies

The main dependencies of the project are:

  • Phoenix framework, a web framework with a role similar to Django or Rails.
  • Ecto, database ORM
  • Ranch, a tcp server
  • Oban, a backend job processing framework.