DinoLand/thumbdrive-install.md

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

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:

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):

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):

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:

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

(Only do this for trusted files.)

C) Host runtime (if preinstalled)

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:

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

@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

#!/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):

chmod +x start-macos.sh