Developing Pack Rat

For people who want to run Pack Rat from its source, change it, or build the apps. (To use it, see Getting Started.)

Pack Rat is plain HTML, CSS and JavaScript (classic scripts, no build step). The party server is Python's standard library only; the Android app has a Java port of it. The source is the pack-rat repository.

Running it from source

On a PC, open index.html directly, or serve the folder (needed for offline use and installing):

python -m http.server 8765

Then browse to http://localhost:8765. To try it on a phone on the same Wi-Fi, run python -m http.server 8765 --bind 0.0.0.0 and open http://<your-PC-IP>:8765 on the phone. Installing to a phone's home screen needs HTTPS: GitHub Pages, Netlify Drop or Cloudflare Pages all work.

Each address keeps its own data; use Settings → Files → Export everything and Import a file to move it.

To host a party without the Windows app, run python server.py (or double-click start-party.bat): see Party Play. python server.py 9000 uses another port. The party is saved in party-data/ next to it (delete that folder for a fresh party). There are no passwords, so only run it on a network you trust.

After changing the app's files, bump VERSION in sw.js so installed copies refresh their offline cache.

Building the Windows app

PackRat.exe is the party server and a launcher (desktop.py) in one file, built with PyInstaller. It opens Pack Rat in an Edge (or Chrome) app window, and keeps its data in %APPDATA%\PackRat\my-data, shared by every Pack Rat window on the PC.

python -m pip install pyinstaller pillow
python tools/build_exe.py

It's written to dist/PackRat.exe.

Building the Android app

No Android Studio or Gradle: tools/build_apk.py compiles, packages and signs it with the SDK's command-line tools.

python tools/build_apk.py

It needs a JDK 17 and the Android SDK command-line tools (platforms;android-34, build-tools;34.0.0) in ../android-toolchain, or set PACKRAT_ANDROID_TOOLCHAIN. The APK is signed with the key in android/keystore/. Back that folder up and keep it private: Android only installs updates signed with the same key, so losing it means uninstalling (and losing the phone's data) to update.

Updating the item data

python tools/build_srd.py            # uses cached pages in tools/.cache
python tools/build_srd.py --refresh  # downloads them again from dnd5e.wikidot.com

This regenerates js/srd-data.js with everything the pages list, for your own use. Published builds use System Reference Document 5.1 content only: python tools/build_srd.py --srd-only OUT writes that version (no trinkets, gemstones, setting-specific games or tool activities).

Item icons are generated too: tools/build_icons.py builds js/icons-data.js from a curated list of game-icons.net icons.

Publishing (the maintainer)

python tools/publish.py                                       # stage, commit and push; the site redeploys
python tools/publish.py --release --title "…" --notes notes.md   # also build the exe and APK and publish a release

tools/publish.py copies the project into a clone of the repository without private or local files (the signing keystore, dist/, caches), swaps in the SRD-only item data, commits and pushes. GitHub Actions then deploys the download page (site/index.html) and the web app (at /app/) to GitHub Pages. With --release it builds the exe and APK from that copy and uploads them to a new release, so the download links always point at the latest one.

Where things are

Path	What it is
index.html, css/app.css	The app's page and styles (light and dark; phone layout under 720 px)
js/store.js	Saved data, campaigns and rule packages, and the rules maths (weight, coins)
js/app.js	Screens and windows: inventory, catalog, item details, the item editor, settings
js/radial.js	The item menu (press and hold an item)
js/templates.js, js/system.js	The fields every item has, features and templates; game systems (groups, states, money, words)
js/systems/	The D&D 5e system and its panels, and the Slot Delve example
js/panels.js	Running a system's panels in sandboxed frames, and their API
js/clockwork.js, js/clockwork-ui.js	Global and Local values, what changes them and what they drive; the Values and Connections tabs
js/triggers.js	Item rules
js/gm-controls.js, js/control-panels.js	The GM tab, boards and control panels
js/treasure.js, js/shops.js	Treasure hoards and tables; shops
js/files.js	Settings → Campaigns and Files: campaigns, rule packages, exports and imports
js/documents.js	Documents: Markdown, the reader and editor, the picture store
js/party.js, js/party-ui.js	Party play: syncing with the host, joining, trading
js/icons.js, js/icons-data.js	Item icons (generated) and the picker
js/srd-data.js	The item catalog (generated)
js/vendor/	The icon editor (svg-lay-tool), Markdown and sanitising, QR codes
server.py, start-party.bat, desktop.py	The party server, and the Windows app's launcher
android/	The Android app: a WebView activity, the Java party server and the hosting service
tools/	Builders: the exe, the APK, the item data, the icons; publishing
sw.js, manifest.webmanifest, icons/	Offline use and installing
site/, .github/workflows/pages.yml	The download page and its deployment to GitHub Pages