SCOPENET-MC/README.md

<div align="center">

<img src="launcher/src-tauri/icons/128x128.png" width="96" alt="" />

# 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.

</div>

<p align="center">
  <img src="docs/screenshots/launcher-home.webp" width="49%" alt="Launcher home" />
  <img src="docs/screenshots/panel-design.webp" width="49%" alt="Panel launcher designer" />
</p>

## 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.

<p align="center">
  <img src="docs/screenshots/launcher-install.webp" width="32%" alt="" />
  <img src="docs/screenshots/launcher-controls.webp" width="32%" alt="" />
  <img src="docs/screenshots/panel-dashboard.webp" width="32%" alt="" />
</p>

## Quick start

### 1. Run the panel

```bash
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](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`. 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](https://docs.gitea.com/runner/labels/) and [token permissions](https://docs.gitea.com/usage/actions/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](docs/admin-guide.md) — deploying, HTTPS, modpacks, players, backups
- [Official server setup](docs/server-integration.md) — private authentication, supported versions, activity and UUID protection
- [The SCOPENET Map](docs/map.md) — the built-in world map: terrain, guild land, shops and players
- [Discord, live embeds and email](docs/discord-and-email.md) — customisable announcements, self-updating status boards and emails to players
- [Rewards, limits and permission nodes](docs/rewards-and-limits.md) — what quests can grant, and every setting you can change
- [Architecture](docs/architecture.md) — how the pieces fit, API reference
- [Development](docs/development.md) — running everything locally, tests
- [Deployment](docs/deployment.md) — local Compose build, health check, upgrades and backups
- [Local 0.4.0 artifacts](release-artifacts/0.4.0/README.md) — 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.