View source for Mneme World Generator/PWA (Dec 2025)

= 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 [https://github.com/StevenTiu22/mneme-world-generator-pwa.git](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

[[Category:Mneme World Generator]]
[[Category:Gaming Projects]]