Developing

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

Is This A Mimic(s)? 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 is-this-a-mimic 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

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

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

It's written to dist/ITAMSapp.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 MIMIC_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
python tools/publish.py --release --version 1.2.0 …             # (the next minor version unless given)

The published copy says which version it is: publish.py writes it into APP_VERSION in js/app.js (the project's own copy says "dev"); a site-only publish carries the latest release's number. Check for updates compares it with GitHub's latest release, and the Windows app's Install and restart is server.update_app (/api/update, the app's own window only): it downloads ITAMSapp.exe, checks its SHA-256 against the release's, swaps it in (the running exe is renamed .exe.old) and starts it with --after-update, which waits for the old one to stop.

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