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 linux-build label and a Windows host runner with windows-build. The CI workflows check the host OS and required tools before building. The Linux host needs Rust with rustfmt and clippy, Node 22+, Java 21 and 25 for the integration matrix, Docker with Buildx, pkg-config, the Tauri WebKit/GTK development libraries, curl, and jq. The Windows host needs Rust, Node 22+, PowerShell and Git Bash. Enable Actions for the repository and allow its job token to write releases and packages. See Gitea's runner labels and token permissions.

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.