SCOPENET-MC/README.md

SCOPENET

A fast, fully customisable Minecraft launcher — and the self-hosted admin panel that controls it.

Brand it, publish vanilla versions or modpacks, manage players, and push changes to every launcher instantly.

What's inside

Launcher (Windows)	Tauri 2 + Rust + Svelte. Uses the system WebView2 instead of bundling Chromium, so the installer stays small and memory use low.
Admin panel (Docker)	Rust (Axum) + SQLite + Svelte. 14 MB image; measured ~2 MB RAM at idle.
Engine	scopenet-core: installs Minecraft, Java, Fabric/Quilt/Forge/NeoForge and launches the game.

Launcher features

• Accounts — private panel accounts (username + password, authenticated online-mode servers), and local offline usernames for local play. Tokens are encrypted with a key stored in Windows Credential Manager.
• Instances — every instance the admin publishes shows up in the sidebar; group-restricted ones only for the right players.
• One-click play — downloads the right Java automatically, the game, the mod loader and the modpack, with live speed/ETA. Files are shared between instances and verified by SHA-1.
• Built-in server — the instance's server is added to the multiplayer list, auto-joined (Quick Play on 1.20+), and its live status (players, MOTD, ping) is shown on the home screen.
• Settings — memory with a recommendation for your PC, resolution, fullscreen, what happens on launch, Java path, GC presets (G1 / ZGC), JVM args, Minecraft keybind editor (applied to every instance), custom accent colour, glass/animation toggles, UI scale, storage manager, per-instance overrides.
• Quality of life — game console, crash dialog with plain-English hints, repair files, offline launch from cache, self-updates from Gitea Releases, single-instance window, Ctrl+Enter to play.
• Branding from the panel — name, logo, colours, font, corner radius, glass, image/video background, news feed, social links, custom CSS. No rebuild needed.

Admin panel features

• Instances — pick a Minecraft version + loader, or import a modpack from Modrinth, CurseForge or a .zip (.mrpack, CurseForge export, or any instance folder). Upload extra mods/configs. CurseForge mods that block third-party downloads are flagged with a download link.
• Access control — public, signed-in players, or specific groups.
• Players — create/approve/disable accounts, roles, groups; sign-ups closed / approval / open.
• Launcher design — every branding option with a live preview and 7 colour presets.
• Dashboard — launches per day, active players, popular instances, recent activity.

Quick start

1. Run the panel

git clone https://gitea.jadonsandbox.com/blade/scopenet-mc.git
cd scopenet-mc
cp .env.example .env
# edit .env → set ADMIN_PASSWORD and PUBLIC_URL for your domain
docker compose config --quiet
docker compose up -d --build

Open http://your-server:8080, sign in as admin, then:

1. Launcher design → name, logo, colours, news.
2. Instances → New instance → a version, or a Modrinth / CurseForge / .zip modpack.
3. Settings → how players sign in.

Put the panel behind HTTPS (Caddy, Traefik, nginx, Cloudflare Tunnel…) before sharing it. See docs/deployment.md.

2. Build your branded launcher

1. In Gitea → Repository Settings → Actions → Variables, add:
   • PANEL_URL = https://panel.example.com (players connect automatically)
   • LOCK_PANEL = 1 (optional: hide the "change server" option)
   • LAUNCHER_NAME = MyServer Launcher (optional)
2. Actions → Release → Run workflow, enter a version like 1.0.0 — or push a tag v1.0.0.

The workflow builds the Windows installer, pushes the panel image to Gitea registry (gitea.jadonsandbox.com/blade/scopenet-mc-panel, amd64 + arm64) and publishes a Gitea release. Installed launchers pick up new releases automatically.

The Gitea registry package may be private at first — make it public under the repository owner’s Packages settings if you want docker pull without logging in.

Gitea runner setup

Register a Linux host runner with the ubuntu-latest label and a Windows host runner with windows-latest. Linux builds the panel Docker image and server JARs; Windows builds the NSIS installer. The workflows use the Linux setup tool and the Windows setup tool to install or check job dependencies. Node 22 and Java 21/25 are downloaded by setup-node and setup-java; the Linux tool installs Rust, Tauri system packages, and release utilities, while the Windows tool installs Rust and downloads PowerShell 7.6.6 if the runner cannot find it. Docker and Buildx are set up by Docker's Actions. The Linux runner must allow a Docker daemon to start or provide one, and system package installation needs root or passwordless sudo. Enable Actions for the repository and allow its job token to write releases and packages. See Gitea's runner labels and token permissions.

The setup tools also run directly on matching hosts: bash scripts/ci/install-linux.sh rust prepares Rust and Tauri builds, bash scripts/ci/install-linux.sh image checks Docker, bash scripts/ci/install-linux.sh java 21 checks a Java integration runner, and powershell -File scripts/ci/install-windows.ps1 prepares the Windows installer runner. Gitea uses them in CI and release jobs; GitHub provides a manual Runner setup workflow for both platforms. Run the Linux rust mode as root or with passwordless sudo; the Windows script may need administrator rights to install Microsoft C++ Build Tools.

Repository layout

crates/shared      Wire types shared by launcher and panel (manifest, branding, auth)
crates/core        Launcher engine: Mojang/Java/loaders, file sync, launch, authlib, ping
integrations/      Paper plugin and Fabric/Forge server mods
panel/server       Admin panel API (Axum + SQLite)
panel/web          Admin panel UI (Svelte 5)
launcher/          Desktop launcher UI (Svelte 5)
launcher/src-tauri Desktop launcher shell (Tauri 2)
Dockerfile         Panel image (static binary on scratch)
docker-compose.yml Panel deployment
.gitea/workflows  CI + release (installer, Gitea release, Gitea registry image)

Documentation

• Admin guide — deploying, HTTPS, modpacks, players, backups
• Official server setup — private authentication, supported versions, activity and UUID protection
• The SCOPENET Map — the built-in world map: terrain, guild land, shops and players
• Discord, live embeds and email — customisable announcements, self-updating status boards and emails to players
• Rewards, limits and permission nodes — what quests can grant, and every setting you can change
• Architecture — how the pieces fit, API reference
• Development — running everything locally, tests
• Deployment — local Compose build, health check, upgrades and backups
• Local 0.4.0 artifacts — Windows installer, server jars and checksums

Configuration reference

Panel (environment variables)

Variable	Default
ADMIN_USERNAME	admin	First admin account (created on first start)
ADMIN_PASSWORD	random, printed in logs	First admin password
JWT_SECRET	auto-generated in /data	Signs login tokens
CURSEFORGE_API_KEY	–	Also settable in the panel
MAX_UPLOAD_MB	2048	Largest modpack upload
SCOPENET_BIND	0.0.0.0:8080	Listen address
SCOPENET_DATA_DIR	/data	Database, hosted files, uploads

Launcher (build-time, via repository variables) — PANEL_URL, LOCK_PANEL, LAUNCHER_NAME.

Notes

• Minecraft is a trademark of Mojang Studios. SCOPENET is not affiliated with Mojang or Microsoft. Offline mode is intended for your own community servers.
• No license has been chosen yet — add a LICENSE file before distributing.