Rewrite README as Wammer - Android

README.md

@@ -1,56 +1,108 @@
-# Contributors Notice
+# Wammer - Android
 
-I am accepting pull requests, feature requests and issues using the github project tracking tools. If you need more help setting up the code base for compilation, assistance in finding out how something works, or where to go to look for "x", please feel free to ask me. This is the first time I've ever managed an open source project so I could use feedback on how I could do things better. Or let me know if I've got something out of bad practice checked into source code, BlowTorch is a work in progress; It can always be better.
+[![Build](https://github.com/ncmud/Wamdroid/actions/workflows/ci.yml/badge.svg)](https://github.com/ncmud/Wamdroid/actions/workflows/ci.yml)
+[![Kotlin](https://img.shields.io/badge/Kotlin-2.3-blue)](https://kotlinlang.org)
+[![API](https://img.shields.io/badge/API-31%2B-brightgreen)](https://developer.android.com/about/versions/12)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+![It's dangerous!](https://img.shields.io/badge/You_are_likely_to_be_eaten_by_a-grue-red.svg)
+[![Take this.](https://img.shields.io/badge/get-lamp-yellow.svg)](http://getlamp.com)
 
-# BlowTorch Source Code Repository
+A MUD client for Android with Lua scripting, plugin support, and multi-connection capability. This is a fork of [BlowTorch](https://github.com/petter-syn/bloern) by Dan Block, modernized to build with current tools and target Android 16.
 
-## To Build BlowTorch you will need the following things downloaded:
+See also [Wammer - iOS](https://github.com/ncmud/Wammer), the sister project for iPhone, iPad, and macOS.
 
-* Android SDK (latest version is fine)
-* Android NDK, specifically any version that isn't the latest. r15c is what I use.
-* Unpack these, note the paths, they will be needed later
-* For now the LuaJit, SQLite3, LuaJava, and Lua extension modules have their source code checked in for ease of use. I am pretty sure this is bad practice so it will probably be replaced by a downloader script or instructions here on what version to download and where to extract it.
+## About MUDs
 
+[MUDs (Multi-User Dungeons)](https://en.wikipedia.org/wiki/MUD) are online multiplayer text-based games. Thousands of players today are on hundreds of MUDs in all manner of worlds: fantasy, absurdist, sci-fi, horror, and more. Many MUDs have been continuously online for decades.
 
-## Now set the following Environment Variables:
+## Features
 
-* export ANDROID_SDK_ROOT=path to sdk root
-* export NDK_HOME=path to ndk root
-* export NDK_HOST_CC_TARGET=darwin-x86_64 for mac, linux-x86_64 for unix, i dont know for windows
-* NDKABI=14 is defined in build_ndk_libraries.sh this should be moved.
-* The current build script hard codes the compiler as GCC v.7. This should be pulled out into an environment variable.
+- **Multi-connection** — connect to multiple MUDs simultaneously and switch between them
+- **Lua scripting** — LuaJIT-powered plugin system with access to triggers, aliases, timers, and the UI
+- **Triggers and responders** — pattern-matched triggers with actions: colorize, gag, replace, script execution, notifications, and more
+- **Configurable button bars** — customizable button layouts per connection
+- **MCCP** — Mud Client Compression Protocol v2 (zlib) for compressed data transfer
+- **ANSI color** — full color rendering
+- **Per-connection settings** — independent configuration for each MUD connection
 
-## Now execute the NDK build script:
+## Getting Started
 
-* ./build_ndk_libraries.sh
+### Prerequisites
 
-## With the native libraries built, the android project can be built with gradle:
+- Android SDK (set `ANDROID_SDK_ROOT`)
+- Android NDK (set `NDK_HOME`)
+- Java 17+
 
+### Build native libraries
 
-* ./gradlew :BT_Free:assembleDebug
-* ./gradlew :BT_Free:assembleDebug
+The app uses LuaJIT and native extensions (luajava, lsqlite3, marshal, luabins) that must be compiled for each target ABI.
 
-or
+```bash
+./build_ndk_libraries_modern.sh
+```
+
+This builds for `arm64-v8a` and `x86_64` and copies `.so` files to `BTLib/src/main/jniLibs/`.
+
+### Build the app
+
+```bash
+./gradlew :BT_Free:assembleDebug
+```
+
+Output: `BT_Free/build/outputs/apk/debug/`
+
+### Install on a connected device
+
+```bash
+./gradlew :BT_Free:installDebug
+```
+
+### Release builds
+
+Release builds require a signing keystore at `BTLib/key/bt_privatekey.keystore` and the `BT_RELEASE_PASS` environment variable:
 
-* ./gradlew :BT_Free:assembleRelease
-* ./gradlew :BT_Aard:aasembleRelease
+```bash
+export BT_RELEASE_PASS=your_keystore_password
+./gradlew :BT_Free:assembleRelease
+```
+
+## Architecture
+
+The app is split into two modules:
 
-note: the gradle project will attempt to sign the apk with a non existant certificate, drop your certificate into the appropriate location and the gradle project will pull the password from an environment variable, BT_RELEASE_PASS for the stock BlowTorch and BT_AARD_PASS for the Aardwolf client. If you do not know about apk signing, please see the android developer documentation.
+| Module | Purpose |
+|--------|---------|
+| **BTLib** | Shared library containing all core logic (`com.offsetnull.bt`) |
+| **BT_Free** | Thin app wrapper with the launcher activity |
 
-double note: the location that the build scripts look for certificates is in the build.gradle for the respective project. For the stock BlowTorch client it looks for BTLib/key/bt_privatekey.keystore and for the aardwolf client it looks for BT_Aard/key/signiture_cert the passwords are passed via system environment variable.
+### Key components
+
+- **StellarService** — background service managing all connections, runs in a separate process (`:stellar`)
+- **Connection** — per-connection handler orchestrating data flow, triggers, and plugins
+- **DataPumper** — network I/O thread with socket read/write management
+- **Processor** — telnet protocol parser with option negotiation and MCCP decompression
+- **Plugin** — Lua plugin system exposing Java API to Lua scripts
+- **MainWindow** — main activity with terminal UI, input handling, and button bars
+
+### Data flow
 
-If you want to set the password from the command line without seeing it use the following:
-```shell
-#!/bin/bash
-
-read -s -p "Enter Password: " BT_RELEASE_PASS
-export BT_RELEASE_PASS
 ```
-Taking special care to source the script into your current environment, or the script will execute inside of its own session, set the variable and then the environment terminates with the program.
-```shell
-source ~/bt_enter.sh
+MUD Server -> Socket -> DataPumper -> Processor (telnet/MCCP) -> Connection (triggers/plugins) -> MainWindow (render)
+User Input -> MainWindow -> Service -> Connection -> DataPumper -> Socket -> MUD Server
 ```
 
-The output from the gradle build is in BT_[Free|Aard]/build/outputs/apk.
-
+### IPC
+
+AIDL-based communication between `MainWindow` (foreground) and `StellarService` (background process).
+
+## Contributing
+
+Pull requests, feature requests, and issues are welcome.
+
+## Credits
+
+This project is a fork of [BlowTorch](https://github.com/petter-syn/bloern) by Dan Block. BlowTorch was an impressive piece of work — a full-featured Android MUD client with Lua scripting and plugin support that served the MUD community for years. We are grateful for Dan's contribution to the community and for open-sourcing the project.
+
+## License
 
+Available under the MIT License. See [LICENSE](LICENSE) for details.