Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Apeuriox/lazybot-renewal/llms.txt

Use this file to discover all available pages before exploring further.

Before you install Lazybot, confirm that every dependency listed here is in place. Lazybot is a Spring Boot 4 application that runs on Java 21 with preview features enabled, talks to a MySQL-compatible database, calls the osu! v2 API, and optionally connects to Discord via JDA and to QQ via a Shiro-compatible OneBot endpoint. Two native JNI libraries — rosu-jni and resvg-jni — are distributed outside of Maven Central and must be installed into your local Maven repository before the project will compile.

​
Runtime Platform

​
Java 21

Lazybot targets Java 21 and is compiled with --enable-preview. The same flag, along with --enable-native-access=ALL-UNNAMED, is required at runtime to load the JNI libraries and use preview language features. 
java --enable-preview --enable-native-access=ALL-UNNAMED -jar lazybot.jar
Both flags are pre-configured in pom.xml for the Spring Boot Maven plugin and the Surefire test runner, so they are applied automatically when you use ./mvnw during development. You must pass them manually when launching the JAR directly or writing a systemd unit file.

​
Required Services

​
MySQL (or compatible)

Lazybot stores user bindings, badge data, card points, and other persistent state in a relational database. The default schema name used in the configuration template is lazybot_schema. MariaDB is a compatible drop-in replacement.
SettingDefault
Drivercom.mysql.cj.jdbc.Driver
Schemalazybot_schema
Connection pool max lifetime120000 ms (2 minutes)
Create the schema and apply the bundled script.sql before starting Lazybot for the first time (see Setup).

​
API Credentials

​
osu! API (Required)

Register an OAuth application at https://osu.ppy.sh/home/account/edit to obtain a client ID and client secret. The application’s callback URL must match the lazybot.oauth.redirect-uri value in your application.yaml.
Config keyDescription
lazybot.client_idOAuth application client ID
lazybot.client_secretOAuth application client secret
lazybot.oauth.redirect-uriRedirect URI registered with osu!
lazybot.scopesfriends.read identify public
The scopes required by Lazybot are friends.read identify public. Make sure your osu! OAuth application is configured to allow all three when registering.

​
Discord Bot (Conditional)

If you intend to run Lazybot on Discord, create a bot application at the Discord Developer Portal and obtain the bot token, application ID, and OAuth2 secret. These map to the discord.bot.* keys in application.yaml. Discord integration is disabled by default (lazybot.global.discord.enabled: false). Enable it explicitly in your configuration.

​
QQ / OneBot (Conditional)

QQ integration uses Shiro, a Spring Boot starter for the OneBot protocol. You need a Shiro-compatible QQ bot (such as Lagrange or similar) configured to connect to Lazybot’s WebSocket endpoint at the path defined by shiro.ws.server.url (default: /lazybot). Tencent integration is enabled by default (lazybot.global.tencent.enabled: true).
Discord and QQ/Tencent can be independently enabled or disabled via the lazybot.global.discord.enabled and lazybot.global.tencent.enabled configuration keys. You do not need to deploy both platforms simultaneously.

​
Native Maven Libraries

Two JNI libraries are used by Lazybot but are not published to Maven Central. They must be installed into your local Maven repository using mvn install:install-file before running ./mvnw clean package. The library JARs are included in the lib/ directory of the repository.

​
rosu-jni

Rosu-JNI by HollisMeynell provides osu! difficulty and performance-point calculation via a Rust-backed JNI binding. 
mvn install:install-file \
  -Dfile=lib/rosu-jni-0.1.8.jar \
  -DgroupId=org.rosu \
  -DartifactId=rosu-java \
  -Dversion=0.1.8 \
  -Dpackaging=jar
At runtime, Lazybot resolves the native .so/.dll library using the ROSU_LIB_PATH environment variable. Set this to the directory that contains the extracted native library file.

​
resvg-jni

Resvg-JNI by Zh_jk wraps the resvg SVG renderer, which Lazybot uses to convert SVG score card templates into PNG images significantly faster than the Apache Batik fallback. 
mvn install:install-file \
  -Dfile=lib/resvg-jni-0.1.4.jar \
  -DgroupId=me.aloic \
  -DartifactId=resvg-jni \
  -Dversion=0.1.4 \
  -Dpackaging=jar
The RESVG_DIR environment variable points to the directory where the resvg render-process library cache is written. If unset, Lazybot creates a temporary directory automatically.

​
Environment Variables Summary

VariablePurposeRequired
LAZYBOT_DIRWorking directory for Lazybot cache files (avatars, map backgrounds, static assets)No — falls back to a system temp directory
RESVG_DIRDirectory for the resvg render-process library cacheNo — falls back to a system temp directory
ROSU_LIB_PATHPath to the directory containing the Rosu native libraryRecommended

​
Next Steps

Build & Configure

Clone the repo, install libraries, configure application.yaml, and build the JAR.

systemd Service

Run Lazybot as a managed Linux service with automatic restart and journal logging.

Build docs developers (and LLMs) love

Get started for freeTalk to us