Installation

Disco can be installed from crates.io or manually installed from GitHub.

Creates.io

Assuming you already have the rust toolchain installed, you can simply install disco by running

cargo install disco-rpc

To allow Lua to call external C libraries, the unsafe feature flag also needs to be enabled.

cargo install disco-rpc --features unsafe

GitHub

Prebuilt binaries are currently provided for x86_64-linux-gnu both with and without the unsafe flag. Disco can also be built from source via cargo

git clone https://github.com/KaitlynEthylia/Disco
cd Disco
cargo install --path .

As with the crates.io installation, --features unsafe my optionally be appended to the final command.

Usage

Running the command disco will automatically look for a Lua file to read configuration from as described in the configuration section. There are a handful of arguments that may be passed to the command to adjust how it runs.

Naturally, the -h, --help and -V, --version flags exist. As well, there is a -p --print-config-path flag, which will prevent the programme from running and print the location that it would otherwise look for a configuration file. The other flags that actually affect the programme are:

-c, --config : Overrides the default path to look for configuration.
-i, --client-id <CLIENT_ID>: Sets the ID of the application to connect as. Takes precedent over Lua configuration.
-r, --retry-after : If connecting to Discord fails, retry after DELAY seconds [default: 0]
-q, --quiet: Don't print any text to the console.

Configuration

Disco will look for a config file by first seeing if one has been given in the command line via the -c flag. If not, it will look at the DISCO_CONFIG environment variable. If that is not set, it will then check $XDG_CONFIG_HOME/disco.lua and lastly $HOME/disco.lua.

If it still cannot find a config file, it will error. There is no default configuration.

The rich presence is made up of a series of variable that can be set in the config file.

the types Timestamp, Image, and Button are not part of lua, they each represent:

Each of these variables can be set in 3 different ways:

• It can be set simply by assigning the variable the value. We will call this a 'static' variable, because its value will not change throughout the programme.

State = "Some Text"

• It can be set via a table. The second element being a function that returns the value, and the first element being the number of seconds between successive calls of this function. This we will call a 'polled' variable.

State = { 60, function()
    return os.date("%H:%M")
end }

Here it runs the os.date() function every 60 seconds to get the system time.

• Lastly, it can be set via a coroutine. This coroutine will continually be resumed, and should yield a value to set each time.

State = coroutine.create(function()
    for i = 1, 10, 1 do
        coroutine.yield("Number: " .. i)
    end
end)

In this example, the coroutine counts up to ten and then stops returning. Once it stops, the final value remains. This example is contrived, but a more complex example can be seen in the example section

Disco may also call external lua libraries, however, if that library requires C libraries, the unsafe feature flag will need to be enabled.

-- requires the `http` library to be installed, as well as the
-- `unsafe` feature to be enabled.
local request = require 'http.request'

local _, stream = request.new_from_uri('https://api.rot26.org/encrypt/test'):go()
State = stream:get_body_as_string()

Example

Here is my personal configuration that I use on my Arch Linux + Hyprland setup so show some details. This isn't exactly what I use but I have modified it slightly to demonstrate some features that I didn't use, such as polling.

-- ID of the client I created for ArchLinux via
-- https://discord.com/developers/applications
ClientID = 1137762526541656105

-- Display the rich presence
Active = true

-- Show what time it is on my machine on the first line, rerun
-- the function every 60 seconds.
Details = { 60, function()
	return "My Time: " .. os.date("%H:%M")
end }

-- Plug into the Hyprland socket to show which window is currently
-- active, and update every time I switch window.
State = coroutine.create(function()
	local handle = io.popen([[
		socat -u UNIX-CONNECT:/tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock - |
		stdbuf -o0 awk -F '>>|,' '/^activewindow>>/{ $2 = toupper(substr($2, 1, 1)) substr($2, 2); print $2}'
	]])
	if not handle then return end
	for line in handle:lines() do
		coroutine.yield("Using: " .. line)
	end
end)

-- Display the Arch Linux logo
LargeImage = {
	'https://seeklogo.com/images/A/arch-linux-logo-3C25E68BA9-seeklogo.com.png',
	text = 'Arch Linux',
}

-- Include the Hyprland logo in the corner
SmallImage = {
	'https://i.imgur.com/PanwaBQ.png',
	text = 'Hyprland',
}

-- A really cool button
Button1 = {
	'Press This Button!',
	url = 'https://youtu.be/dQw4w9WgXcQ',
}

Before Release

Things that intend to be done before i could be happy calling this a 1.0.0 project.

• Provide extra utilitly functions to make some tasks easier.
• Test compaility on non x86_64-linux-gnu machines, and fix where possible.
• Provide bash, zsh, and fish completions with the releases.
• Provide template systemd and potentially runit and openrc services for running on startup.
• Fix bugs that are more than likely to show up, and provide friendlier error handling.

None of these goals are particularly quick and easy, so they are likely to only end up completed if enough interest is shown in the tool.