# Juniper-RS — macOS Client

Two ways to run Juniper on Mac. Pick whichever you prefer.

## Quick start (Option 1 — .command script)

1. Install Java 8 or newer (Temurin/Adoptium recommended):
   https://adoptium.net/ — pick **JDK 8** or **JDK 11**, "macOS" tab, your
   chip (Apple Silicon = aarch64, Intel = x64).
2. Put **`Juniper.command`** in a folder along with **`Juniper.jar`** and
   (optionally) **`JuniperUpdater.jar`**.
3. Double-click `Juniper.command`.

**First-launch warning** ("cannot verify developer"): macOS Gatekeeper
blocks unsigned scripts by default. Three options:

- Right-click `Juniper.command` → **Open** → click **Open** in the dialog.
  Only needed once.
- Or in Terminal:
  ```
  chmod +x Juniper.command
  xattr -d com.apple.quarantine Juniper.command 2>/dev/null
  ```
- Or System Settings → Privacy & Security → **Allow Anyway** next to the
  warning about Juniper.command (after the first failed launch attempt).

For local-server testing instead of the live VPS, double-click
**`local-client.command`** — same logic, but sets `juniper.localhost=true`
so the client connects to `127.0.0.1:43595`.

## Native-feel (Option 2 — .app bundle)

For players who'd rather drag a real Mac app into their Applications
folder, this directory ships a `Juniper.app` bundle skeleton. To make
it usable:

1. Place `Juniper.jar` (and optionally `JuniperUpdater.jar`) inside
   `Juniper.app/Contents/Resources/`.
2. (Optional) Drop a `.icns` icon file at
   `Juniper.app/Contents/Resources/Juniper.icns`.
3. From Terminal, make the launcher script executable:
   ```
   chmod +x "Juniper.app/Contents/MacOS/launch.sh"
   xattr -dr com.apple.quarantine Juniper.app 2>/dev/null
   ```
4. Drag `Juniper.app` to `/Applications/`.

The app shows up in Spotlight, the Dock, and Launchpad like any normal
Mac application. Double-click to play.

## Folder layout you should ship to players

```
JuniperMac/
├── Juniper.command         <- main launcher
├── local-client.command    <- only if they're running a local server
├── Juniper.jar             <- the client (from 718 Client/build/libs/)
├── JuniperUpdater.jar      <- optional, auto-pulls cache from VPS
└── README.md               <- this file
```

If you want to give players the .app bundle instead, ship:

```
JuniperMac/
├── Juniper.app/
│   ├── Contents/
│   │   ├── Info.plist
│   │   ├── MacOS/launch.sh
│   │   └── Resources/
│   │       ├── Juniper.jar
│   │       ├── JuniperUpdater.jar  (optional)
│   │       └── Juniper.icns        (optional)
└── README.md
```

## Cache location on Mac

The client uses `$HOME` (your Mac user folder) for cache storage. On
first launch the JuniperUpdater (if shipped) downloads the latest cache
files into:

```
~/Juniper/CACHE/LIVE/
```

(same relative path as Windows; just rooted under your home folder
instead of `C:\Users\<name>\`.) To clear the cache and force a fresh
download, delete that directory and relaunch.

## Environment variable knobs

| Variable | Purpose | Default |
|---|---|---|
| `JUNIPER_NO_UPDATE` | Set to anything to skip the cache updater. Useful when offline or when the VPS update endpoint is down. | unset |
| `JUNIPER_UPDATE_URL` | Override the cache-update server URL. | `http://play.juniper-rs.com:8081` |

Example: `JUNIPER_NO_UPDATE=1 ./Juniper.command`

## Troubleshooting

- **"java: command not found"** — Java isn't installed or isn't on your
  PATH. Install via https://adoptium.net then close+reopen Terminal.
- **App icon greyed out / "damaged and can't be opened"** — Gatekeeper
  quarantine; run `xattr -dr com.apple.quarantine Juniper.app` from
  Terminal once.
- **Black screen on launch** — Could be a Java 17+ Java2D issue.
  Install Java 8 or 11 alongside (Adoptium lets you install multiple
  versions) and try again.
- **Connection refused** — The Mac client launcher defaults to the live
  VPS. If you only have the LOCAL server running, use
  `local-client.command` instead.
