update readme

readme.md

@@ -1,20 +1,46 @@
 Some Python code for plumbing together a Matrix room and a Minecraft server chat
 
-Setup the app bridge first:
+This project is a fork of
-- Drop ServerWrapper.py and the registration.yaml onto your homeserver. 
+[paftree/matrixcraft-bridge](https://github.com/paftree/matrixcraft-bridge) that
-- Add it to your homeserver config, setup ports and keys and whatnot.
+cleans up the code and adds some new functionality, such as synchronizing Matrix
-- Run Serverwrapper.py
+presence with Minecraft login/logout events.
-- On first run, a server config json will be generated. Fill out accordingly and then run again.
 
-Then set up the server wrapper:
+Setup the application service (bridge part) first:
-- Drop ServerWrapper.py into the folder with your Minecraft .jar. 
+- Clone this repo on your homeserver.
-- Run once again to generate wrapper.json
+- Install the packages in `requirements.txt`
-- Fill it out.
+- Add registration.yaml to your homeserver config:
-- Start the Minecraft server, see example below
+```
+app_service_config_files:
+ - "/path/to/.../registration.yaml"
+```
+- There are two tokens that need to be added to `registration.yaml`. The
+   `as_token` should be saved and passed on the command line as
+`--appservice_token` to `service.py`.
+- Run `service.py` (ideally as e.g. a systemd service).
+  - `--matrix_server_name` is used to generate user IDs on the local server for
+    Minecraft users.
+  - `--matrix_api_port` should be the port you specify in `registration.yaml`.
+  - `--minecraft_wrapper_port` is the port you wish the service to bind to for
+    communicating with the Minecraft server. (If the Minecraft server is not
+    local, you should make sure to open this port in your firewall. Note that it
+    is not authenticated, so it may not be wise to allow all traffic through
+    this port.)
 
+Then set up the Minecraft server wrapper:
+- Clone this repo on your Matrix server host.
+- Install the packages in `requirements.txt`
+- Run `wrapper.py` as follows:
 
-`python .\ServerWrapper_v0.1.0.py java -Xmx1024M -Xms1024M -jar minecraft_server.1.11.2.jar`
+`python wrapper.py --matrix_server example.com --matrix_server_port 5001 java -Xmx1024M -Xms1024M -jar minecraft_server.1.11.2.jar`
-  
-The wraper looks in your cwd for anything with "minecraft_server" in the name to know to launch in wrapper mode
 
-This was hacked together over a weekend, so I make no promises. 
+  - `--matrix_server` should be the domain name or IP address which resolves to
+    your matrix server (could be different from `--matrix_server_name`).
+  - `--matrix_server_port` is the port you specified as
+    `--minecraft_wrapper_port` above.
+
+Quirks:
+ - You have to invite the appservice user (e.g. `minecraft_bridge`) to a room to
+   bridge that room with the Minecraft server
+ - Once the appservice user is invited, if you restart the appservice, you may
+   have to generate an event (e.g. type a message) to get the appservice to
+   bridge your room properly.