# Dino Land USB / Thumbdrive Install & Run Guide

For non-technical users running Dino Land from a USB drive on unknown computers (Windows, macOS, ChromeOS).

---

## 1) Quick decision tree

```text
Start
 ├─ Can you run a local web server (PHP or portable server) from USB?
 │   ├─ Yes → Use FULL LOCAL MODE (leaderboard + API should work)
 │   └─ No
 │      ├─ Can you at least open files in a browser from USB?
 │      │   ├─ Yes → Use OFFLINE QUICK PLAY (gameplay only, no score save)
 │      │   └─ No → Host machine is locked down; ask for a machine with browser file access
 └─ If security warning appears (SmartScreen/Gatekeeper), use browser-only mode or approved machine
```

---

## 2) Recommendation matrix

| Mode | Needs install/admin? | Works from USB only? | Scoreboard/API | Best when |
|---|---|---|---|---|
| **Works with no install** (open file in browser) | No | Yes | **No** (PHP API unavailable) | Locked-down machines, schools, kiosks |
| **Works with portable binaries** (USB-contained server) | Usually No (if executable allowed) | Yes | **Yes** (if local server starts) | Unknown machine, no admin, but executables allowed |
| **Requires host runtime/install** (host PHP/Python/etc.) | Often Yes (or preinstalled tools) | Not strictly | **Yes** | Managed machine with approved dev/runtime tools |

---

## 3) Packaging options to put on USB

## Option A: **Offline quick play** (no scores)
Use existing project files as-is.

Required on USB:
- `index.php` (or optional static fallback page if you create one)
- `js/`, `assets/`, `styles.css`

What works:
- Core gameplay usually works in browser file mode (`file://...`)

What does **not** work reliably:
- Leaderboard save/load via `api/scores.php`

## Option B: **Full local mode** (with local server)
Put full project folder on USB, including:
- `api/`
- `data/`
- all game assets/files

Then run a local server (portable or host runtime) and open `http://127.0.0.1:PORT`.

---

## 4) Per-OS run steps

## Windows

### A) No install (quick play)
1. Insert USB.
2. Open USB in File Explorer.
3. Right-click `index.php` -> **Open with** -> Chrome/Edge.
   - If this opens raw PHP text or broken page, use Full Local Mode.

### B) Portable binaries (preferred if allowed)
If your USB has `php\php.exe` bundled:

```bat
cd /d "%~dp0"
php\php.exe -S 127.0.0.1:8000
```

Then open:
- `http://127.0.0.1:8000`

If SmartScreen appears:
- Click **More info** -> **Run anyway** only if USB is trusted.
- On locked corporate machines, this option may be blocked.

### C) Host runtime already installed
In Command Prompt (inside Dino Land folder):

```bat
php -S 127.0.0.1:8000
```

---

## macOS

### A) No install (quick play)
1. Insert USB.
2. In Finder, open Dino Land folder.
3. Drag `index.php` into Chrome/Safari (or File -> Open File).

### B) Portable binary from USB
If USB includes a PHP binary (example path `./php/bin/php`):

```bash
cd "/Volumes/<USB_NAME>/Dino Land"
./php/bin/php -S 127.0.0.1:8000
```

Open `http://127.0.0.1:8000`

If Gatekeeper blocks the binary:
- Right-click binary -> **Open** (one-time allow), or
- If policy blocks unknown binaries, use quick play mode.

If quarantine flag blocks execution, advanced users can remove it:

```bash
xattr -dr com.apple.quarantine "/Volumes/<USB_NAME>/Dino Land/php"
```

(Only do this for trusted files.)

### C) Host runtime (if preinstalled)

```bash
cd "/Volumes/<USB_NAME>/Dino Land"
php -S 127.0.0.1:8000
```

---

## ChromeOS

### A) No install (quick play)
- Open Files app -> USB -> game files.
- Open with browser.
- If browser blocks local JS/file access behavior, use another machine or Linux mode.

### B) Portable/server mode on ChromeOS
- Usually restricted unless Linux (Crostini) is enabled.
- If Linux terminal is available:

```bash
cd "/mnt/chromeos/removable/<USB_NAME>/Dino Land"
php -S 127.0.0.1:8000
```

Then open `http://127.0.0.1:8000` in Chrome.

### C) Host runtime/install required
- On managed school/work Chromebooks, installing/enabling Linux may be disabled by policy.
- In that case, only quick play (if allowed) is feasible.

---

## 5) Limitations, risks, and behavior to expect

- **`file://` origin restrictions:** browsers may block some fetch/XHR/module behaviors from local files.
- **Scoreboard/API dependency:** leaderboard save/load needs `api/scores.php` via server-side PHP. No running PHP server = no persistent scores.
- **Windows SmartScreen:** may warn/block unsigned portable executables from USB.
- **macOS Gatekeeper/quarantine:** may block downloaded/unsigned binaries on USB until manually allowed.
- **ChromeOS constraints:** managed devices often block runtime installs, local servers, or executable permissions.
- **USB write permissions:** if USB is read-only or restricted, `data/scores.json` cannot update even with server running.

---

## 6) Practical fallback order (recommended)

1. Try **Full local mode** (portable PHP on USB).
2. If blocked, try **host-installed PHP** (if already present).
3. If still blocked, use **Offline quick play** (no scores).

---

## 7) Minimal launcher scripts (optional, put on USB)

### `start-windows.bat`
```bat
@echo off
cd /d "%~dp0"
if exist php\php.exe (
  php\php.exe -S 127.0.0.1:8000
) else (
  php -S 127.0.0.1:8000
)
```

### `start-macos.sh`
```bash
#!/usr/bin/env bash
cd "$(dirname "$0")"
if [ -x "./php/bin/php" ]; then
  ./php/bin/php -S 127.0.0.1:8000
else
  php -S 127.0.0.1:8000
fi
```

Make executable (once):

```bash
chmod +x start-macos.sh
```