a fork of https://gitlab.com/vurpo/godot-matrix. Merge is desired.

Houkime e452be8527 note about 3.x branch 2 months ago
example 120ab6da39 redo ui so it works 2 months ago
.gitignore ef57af5e8f More user interaction and bugfixes and that good stuff 4 years ago
LICENSE f958416502 Add license 4 years ago
README.md e452be8527 note about 3.x branch 2 months ago
SCsub 56f6a6ccd9 fix-compilation-on-godot-3x 2 months ago
config.py 56f6a6ccd9 fix-compilation-on-godot-3x 2 months ago
matrix.cpp c3d9712d12 fixed log in into conduit 2 months ago
matrix.h 56f6a6ccd9 fix-compilation-on-godot-3x 2 months ago
matrixroom.cpp 56f6a6ccd9 fix-compilation-on-godot-3x 2 months ago
matrixroom.h da70ca2eae BREAKING: MatrixRoom::send_event now sends arbitrary event types 4 years ago
matrixuser.cpp 56f6a6ccd9 fix-compilation-on-godot-3x 2 months ago
matrixuser.h 047eda5906 User added and implemented 4 years ago
register_types.cpp 56f6a6ccd9 fix-compilation-on-godot-3x 2 months ago
register_types.h 834ad90afa Initial commit (makes an HTTP request) 4 years ago


Godot Engine module for interacting with the Matrix protocol

This is a module for integrating a Matrix client into your Godot game. You can use it for building a chat service into your game, matchmaking/lobbies, or whatever else you can come up with!

Matrix is an open protocol and network which can be used for persistent communication (for example IM).


(Note: when compiling, make sure that this folder is copied/linked to godot-source-dir/modules/matrix and that the godot branch 3.x is checked out (latest stable release probably works too)) (Note 2: before release, do not forget to build export templates with tools=no and to export using them) (Note 3: currently, it hangs if it cannot connect to the server. You can change the server in the MatrixClient node in the tree or via script.) (Note 4: DO NOT use http for anything remote. For local testing conduit server is the easiest) (Note 5: maybe https: will need to update certificates here, i need to check)

There is a new node called MatrixClient. This represents a client. Set the homeserver address in the inspector or using .set_hs_name(String name), then either log in using .login(String username, String password) or set the access token in the inspector or using .set_auth_token(String token). When you login you will get an access token for a session, and if you save this access token, you'll be able to continue using the same session at a later point. If the client is logged in (has an access token), calling .logout() will log out the current session.

Call .start_listening() to start receiving events from the Matrix server. The client will start long polling the homeserver for new events in the background. While this is happening, the sync_token in the MatrixClient will update periodically. If you don't want to receive the same old events a second time when you start up a new MatrixClient, save this sync token somewhere and restore it into the new MatrixClient. This will ensure you only receive the same event once.

You will receive all the events as signals (the signals will be emitted with the event as a Dictionary as the argument). MatrixClient currently has five different signals you can receive:

  • invited_to_room: your account was invited to a room.

  • left_room: you left a room (or were kicked/banned)

  • timeline_event: received a timeline event in a room. These include received messages and state changes (e.g. someone changed the room name/topic, someone joined/left), and you'd usually want to list these events in a chat window in a typical IM app.

  • state_event: the state changed in a room. You'll want to use this signal to update the UI (change the name, topic, user list etc.) if you're building an IM app, for example. (Some events are emitted as both timeline events and state events. This is because they both belong on the timeline of messages, and also to update the overall UI. You should react to both signals accordingly.)

  • ephemeral_event: Events which are not persistent. This includes typing notifications, online/away/offline status, and read receipts.

The format of the Dictionary you receive in all of these signals is a Matrix Event, as specified in the Matrix client-server API spec.

You can call .get_rooms() on the MatrixClient to get all the rooms it is currently a member of. This is a dictionary mapping of room IDs to MatrixRooms. If you only want to receive signals from one room instead of from all rooms, you can connect to timeline_event, state_event, and ephemeral_event on an individual MatrixRoom instead of on the MatrixClient. They behave the same way as described above.

You can leave a room using either the .leave_room(String room_id) method on the MatrixClient, or by calling .leave_room() on a MatrixRoom.

Sending events and state changes, and interacting with the server etc. is still very much a work-in-progress. Currently you can send text messages, by calling .send_text_message(String text) on a MatrixRoom.

There is an example Godot project in this repo, which contains a simple IM client to demonstrate how the module can be used (hardcoded to only chat in one room).

Matrix basics

Here are the basics of the Matrix protocol, from the client's perspective.

A Matrix client connects to a homeserver. The client can then communicate with other clients on the same homeserver, and usually (if federation is not disabled) with clients on other homeservers.

All communication happens in rooms. Communication is done by sending events to the room, which all members of the room then receive. Clients can also update the state of the room, for example change their display name and profile picture, change the name and topic of the room, or join, leave, invite, kick, or ban other members. Every member has a power level, which is a number which determines which of these things they are allowed to do in the room. Rooms are identified by their room ID (which looks something like !RtOeFVSpNUJHGLYYTh:vurpo.fi), and can have aliases which can also be used to identify a room (for example #matrix:matrix.org).

Everything that happens is an event (various kinds exist). Events are represented as Dictionaries in this module. An event has a type, a room ID, an event ID, a sender, and some other fields. The full specification of what an event looks like can be found in the Matrix client-server API spec. The homeserver saves full history of all events that have happened.


This module's design is heavily inspired by, and in some parts ported over from, the Matrix Python SDK. Thanks!