From 1bab945dcdeff18c709bac6710397a239c459e8b Mon Sep 17 00:00:00 2001 From: OpenClaw Engineer Date: Sat, 14 Mar 2026 21:12:14 -0500 Subject: [PATCH] docs: add USB thumbdrive install/run guide for Dino Land --- README.md | 5 ++ thumbdrive-install.md | 200 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+) create mode 100644 thumbdrive-install.md diff --git a/README.md b/README.md index e32573d..476a2f0 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,11 @@ LAN test URL (from another device on your network): `python3 -c "import socket;s=socket.socket(socket.AF_INET,socket.SOCK_DGRAM);s.connect(('8.8.8.8',80));print(s.getsockname()[0]);s.close()"` 2. Open: `http://:8000` (example: `http://192.168.1.25:8000`) +## USB / thumbdrive distribution + +Need to run Dino Land from a USB drive on unknown machines (Windows/macOS/ChromeOS)? +See: **[thumbdrive-install.md](./thumbdrive-install.md)** + ## Controls - **Up Arrow**: jump diff --git a/thumbdrive-install.md b/thumbdrive-install.md new file mode 100644 index 0000000..db79702 --- /dev/null +++ b/thumbdrive-install.md @@ -0,0 +1,200 @@ +# 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//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//Dino Land/php" +``` + +(Only do this for trusted files.) + +### C) Host runtime (if preinstalled) + +```bash +cd "/Volumes//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//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 +```