Mneme World Generator PWA

Procedural Star System Generation for Tabletop Worldbuilders

The Mneme World Generator is a React-based Progressive Web App (PWA) designed to procedurally generate astronomically plausible star systems. Built for offline-first reliability, it allows GMs and worldbuilders to generate, edit, and store complex stellar data without needing a constant internet connection.

1. Requirements

Node.js: v20 or v22 (LTS recommended)

Package Manager: PNPM (recommended) or NPM

Environment: Linux (Debian/Ubuntu tested), Windows, or macOS

Browser: Chrome, Brave, or Samsung Internet (for best PWA support)

🛠 Troubleshooting: Requirements

Node Version Mismatch: If you see "Unsupported engine," update Node using nvm install 22.

Missing PNPM: Install it globally via npm install -g pnpm.

2. Quick Start (Local Development)

Clone the repository

git clone [1](https://github.com/StevenTiu22/mneme-world-generator-pwa.git) cd mneme-world-generator-pwa

Install dependencies

pnpm install

IMPORTANT: If you see an "Ignored build scripts" warning, run:

pnpm approve-builds

Build & Preview

pnpm build pnpm preview

🛠 Troubleshooting: Quick Start

Large Chunk Warning: If you see (!) Some chunks are larger than 500 kB, this is a standard Vite warning for large applications. It does not mean the build failed. You can safely ignore this for local testing or deployment.

ELIFECYCLE / Command Failed: This often occurs if you manually stop the process (Ctrl+C) or if a previous instance of the app is still running. Try running killall node or fuser -k 4173/tcp to clear the port.

Ignored Build Scripts: If the UI looks unstyled, run pnpm approve-builds to authorize Tailwind and esbuild.

Build Errors: If TypeScript errors block the build, try npx vite build to bypass strict checks.

3. Launching for Local Testing (Desktop & Mobile)

To test the app on your phone while it is running on your desktop, you need to expose your local build to your home network.

A. Find your Desktop IP Address

Windows: Open Command Prompt, type ipconfig. Look for "IPv4 Address" (e.g., 192.168.1.5).

Linux/Mac: Open Terminal, type hostname -I or ifconfig.

B. Launching via Preview (Network Mode)

Run the preview command with the --host flag to make it visible to other devices:

pnpm preview --host

The terminal will provide a "Network" URL (e.g., http://192.168.1.5:4173).

C. Testing on your Mobile Phone

Connect your phone to the same Wi-Fi as your desktop.

Open your mobile browser (Chrome/Brave) and enter the Network URL.

PWA Installation Note: For local testing without HTTPS, use Chrome Port Forwarding:

Connect phone via USB.

On Desktop Chrome, go to chrome://inspect/#devices.

Click Port Forwarding and map port 4173 to localhost:4173.

🛠 Troubleshooting: Local Launch

Connection Timed Out: Ensure your desktop firewall allows traffic on port 4173.

Site Loads but No Icons: Ensure you ran pnpm build after your last code update.

4. Updates & Version Control

As an open-source living project, Mneme is frequently updated with new features and bug fixes.

A. Checking and Pulling Updates

git fetch origin git pull origin master pnpm install pnpm approve-builds pnpm build

B. Verification after Update

After building the update, follow the steps in Section 3 (Launching for Local Testing) to verify the changes on your devices. Always remember to use the --host flag if you are accessing the app from a phone or tablet.

🛠 Troubleshooting: Updates

Fast-forward Updates: If you see "Fast-forward" in the output, the update was successful. Always run pnpm install immediately after to sync new dependencies.

Merge Conflicts: If you modified the code locally, git pull may fail. Use git stash to hide your changes.

5. QA & Pre-Launch Verification

A. Simulating Mobile & Offline Mode

Use Chrome DevTools (F12) -> Application -> Service Workers -> Check Offline.

🛠 Troubleshooting: QA

Changes Not Appearing: PWAs cache aggressively. In DevTools, go to Application -> Storage -> Clear site data.

6. Self-Hosting Guide (Home Servers)

A. Nginx Static Hosting

Move dist/ contents to /var/www/mneme.

Configure Nginx with try_files $uri $uri/ /index.html;.

B. Cloudflare Tunnel

pm2 start serve --name "mwg" --cwd /path/to/dist -- -s . -l 4174

Map tunnel to http://localhost:4174.

🛠 Troubleshooting: Hosting

404 on Refresh: If refreshing a sub-page gives a 404, check that your Nginx try_files directive is correctly pointing to index.html.

7. Offline Android & Mobile Installation

Navigate to your URL.

Tap Install App or Add to Home Screen.

🛠 Troubleshooting: Installation

No Install Prompt: Ensure your site is served over HTTPS (or via the Chrome Port Forwarding method in Section 3).

8. Future: Customizing Rules & Tables

Logic: src/logic/generators/starGenerator.ts

Zones: src/logic/calculators/zoneCalculator.ts

Tables: src/data/tables/

9. Distribution & Sharing (DriveThruRPG)

🛠 Troubleshooting: Distribution

Blank Screen on Local Open: Browsers block features when opening index.html via file://. Advise users to use a local static server.

10. Final Observations & Persistence

Persistence: Data is in IndexedDB (Dexie).

Troubleshooting Note: Clearing browser cache will delete user data unless they have used the Export to JSON feature.

Maintained by: Steven Tiu & Justin Aquino

Version: 1.0.0-Milestone6