Bridging to Matrix - Revision history

Maze2: /* Prerequisites */ not necessarily Synapse

2024-08-01T10:41:37Z

Prerequisites: not necessarily Synapse

Maze2: /* AAGRINDER server configuration */ fix typo

2024-08-01T10:40:52Z

AAGRINDER server configuration: fix typo

Maze: /* Appservice registration */ fix typo

2024-05-15T15:27:15Z

Appservice registration: fix typo

Maze: These dependencies are now optional too

2022-10-18T15:47:58Z

These dependencies are now optional too

Maze: Instructions to bridge to Matrix using appservice or bot

2022-09-08T12:31:14Z

Instructions to bridge to Matrix using appservice or bot

New page

AAGRINDER in-game chat can be bridged to [[wikipedia:Matrix_(protocol)|Matrix]]. There are two ways to achieve this: setting up a Matrix appservice, or setting up a Matrix bot.

== Setting up AAGRINDER Matrix Appservice ==

AAGRINDER can be bridged to Matrix as an appservice. An appservice is a component ("plugin") of your Matrix homeserver, able to create new accounts to represent in-game users. This is the recommended way to bridge AAGRINDER to Matrix.

=== Prerequisites ===

You will need a Matrix Synapse homeserver.

In the AAGRINDER server directory, run the following command to install the optional dependencies:

'''npm install matrix-bot-sdk sharp'''

=== AAGRINDER server configuration ===

In your '''config.json''' in the AAGRINDER server directory, set the following configuration parameters:
* set '''matrix_room_id''' to the ID of the room where you would like bridged messages to appear (begins with a "!")
* set '''matrix_homeserver_url''' to the full URL to your Synapse instance (eg. '''<nowiki>https://matrix.myawesomedomain.net</nowiki>''')
* set '''matrix_appservice_enabled''' to '''true'''
* set '''matrix_appservice_id''' to '''aagrinder''' (unless you already have an appservice with this ID)
* set '''matrix_appservice_url''' to the URL where the AAGRINDER server will be accessible from Synapse, port included. This might be for example '''<nowiki>http://localhost:8433</nowiki>''', or, if Synapse will be running in Docker, something like '''<nowiki>http://172.17.0.1:8433</nowiki>'''
* set '''matrix_appservice_domain''' to the name of your Matrix homeserver name, for example '''myawesomedomain.net'''
* set '''matrix_appservice_bindadress''' to the address where AAGRINDER will be listening for requests from Synapse. This might be '''localhost''', or, if Synapse will be running in Docker, something like '''172.17.0.1'''
* set '''matrix_appservice_port''' to the port number on which AAGRINDER will be listening for requests from Synapse. The default is 8433.

=== Appservice registration ===

Generate your appservice registration file by running the following command in the AAGRINDER server direcory:

'''npm run registration'''

'''mx-aagrinder-registration.yaml''' will be created. Verify that the bind address is correct (see previous section).

Copy the AAGRINDER registration file to an accessible directory for the Matrix server (for example next to '''homeserver.yaml''').

Edit '''homeserver.yaml'''. Add the path to the AAGRINDER registration file in the section '''app_service_config_files'''.

Restart Synapse and AAGRINDER.

== Setting up AAGRINDER Matrix bot ==

AAGRINDER can be bridged to Matrix through a bot user. The bot is a regular Matrix account. The AAGRINDER server will have the access token of the account and will be able to control it.

Please note that this method has not been tested in a long time because the appservice way is better. You really should run your own Matrix server, even if you have it only for the AAGRINDER bridge.

=== Prerequisites ===

You will need a new Matrix account that you are not using for anything else. Join the room where you would like the bridged messages to appear.

In the AAGRINDER server directory, run the following command to install the optional dependencies:

'''npm install matrix-bot-sdk sharp'''

=== AAGRINDER server configuration ===

In your '''config.json''' in the AAGRINDER server directory, set the following configuration parameters:
* set '''matrix_room_id''' to the ID of the room where you would like bridged messages to appear (begins with a "!")
* set '''matrix_homeserver_url''' to the full URL to your Synapse instance (eg. '''<nowiki>https://matrix.example.com</nowiki>''')
* set '''matrix_bot_enabled''' to '''true'''
* set '''matrix_bot_access_token''' to the Matrix account's access token, which you can extract from any Matrix client where the account is currently logged in.

Restart AAGRINDER for changes to take effect.

@@ Line 7: / Line 7: @@
 === Prerequisites ===
-You will need a Matrix Synapse homeserver.
+You will need a Matrix homeserver with support for appservices, for example Synapse.
 In the AAGRINDER server directory, run the following command to install the optional dependencies:

@@ Line 21: / Line 21: @@
 * set '''matrix_appservice_id''' to '''aagrinder''' (unless you already have an appservice with this ID)
 * set '''matrix_appservice_url''' to the URL where the AAGRINDER server will be accessible from Synapse, port included. This might be for example '''<nowiki>http://localhost:8433</nowiki>''', or, if Synapse will be running in Docker, something like '''<nowiki>http://172.17.0.1:8433</nowiki>'''
-* set '''matrix_appservice_domain''' to the name of your Matrix homeserver name, for example '''myawesomedomain.net'''
+* set '''matrix_appservice_domain''' to the name of your Matrix homeserver, for example '''myawesomedomain.net'''
 * set '''matrix_appservice_bindadress''' to the address where AAGRINDER will be listening for requests from Synapse. This might be '''localhost''', or, if Synapse will be running in Docker, something like '''172.17.0.1'''
 * set '''matrix_appservice_port''' to the port number on which AAGRINDER will be listening for requests from Synapse. The default is 8433.

@@ Line 27: / Line 27: @@
 === Appservice registration ===
-Generate your appservice registration file by running the following command in the AAGRINDER server direcory:
+Generate your appservice registration file by running the following command in the AAGRINDER server directory:
 '''npm run registration'''

@@ Line 11: / Line 11: @@
 In the AAGRINDER server directory, run the following command to install the optional dependencies:
-'''npm install matrix-bot-sdk sharp'''
+'''npm install matrix-bot-sdk sharp uuid js-yaml'''
 === AAGRINDER server configuration ===