LLM Chatter for LonelyIce

Port of Hokken/mod-llm-chatter, pinned to a38c7f8b8c814e31d64fbbf7e15377cd185ca8e2. This repository contains build configuration, compatibility patches, launcher settings and the bridge adapter, rather than an upstream fork. Upstream code remains AGPL-3.0; Hokken and upstream contributors own their work.

Install

Install LLM Chatter (mod-llm-chatter) from the LonelyIce package catalog. The package depends on Playerbots, includes Windows x64 and Linux x64 libraries and a self-contained Python bridge. An existing LonelyIce build with core ABI lonelyice-ac-2 is required. Linux binaries use the same Ubuntu 24.04 baseline as the current LonelyIce Linux packages.

In the GUI or TUI Settings page, open LLM Chatter, select the provider, model, language and API key (or the Ollama address), then enable the module. The TUI configures the profile; start the server normally afterward. There are 544 controls, including every literal upstream configuration key and the port's process/database options. The field names retain upstream keys and documented settings include upstream descriptions. Advanced source-only controls stay unset until edited.

The module is disabled initially. LLM connectivity probes are disabled initially too. The bridge starts with the game server after installation/SQL application, and stops with it. A parent watchdog also ends the bridge if the server process disappears. Its output is written to logs/llm-chatter-bridge.log relative to the server folder. Unexpected exit is reported in the server log without an endless restart loop. LLMChatter.Bridge.AutoStart disables automatic launch when managing the process separately. LLMChatter.Bridge.LogPath changes its log location. No system service installation is involved.

Settings are stored under plugins.mod-llm-chatter.settings in the active YAML profile. The launcher generates a private module .conf; do not edit that generated file. Keep API keys in the sibling local.yaml when sharing server.yaml. Keys already in local.yaml continue to be edited there. The launcher currently uses ordinary text controls for plugin keys.

# server.yaml (merge into your existing profile)
plugins:
  mod-llm-chatter:
    version: "0.1.0"
    enabled: true
    settings:
      LLMChatter.Enable: true
      LLMChatter.Provider: "openai"
      LLMChatter.Model: "your-model-id"
      LLMChatter.Language: "RU"

# local.yaml (keep private)
plugins:
  mod-llm-chatter:
    settings:
      LLMChatter.OpenAI.ApiKey: "your-api-key"

Provider choices are Anthropic, OpenAI, Google, OpenRouter and Ollama. Conversation context goes to the configured provider. Ollama can use a locally hosted model; the model/server is installed separately. Restart the server after changing settings so both C++ and bridge see the same values.

Storage and optional upstream tools

Both built-in SQLite and the LonelyIce MySQL storage plugin are supported. By default the bridge inherits the active server database connection; it does not require duplicate database credentials. The SQLite adapter shares the core's native SQL dialect and function shims, keeps query values bound, supports cross-database reads and uses short explicit transactions for party-chat reservations. Manual MySQL credentials are used only with LLMChatter.Database.UseServerConnection = 0. The MySQL adapter also maps upstream's fixed acore_ qualifiers to the configured database prefix.

Characters schema installation uses upstream's current complete base schema. Historical MySQL upgrade migrations are deliberately omitted for this new package: they target older upstream installations and include redundant/destructive table alterations. World SQL includes upstream's base and fixes. This package is not a migration path for a manually installed old upstream module.

The optional Chatter Companion client addon is a separate upstream download. Conversations work without it. Host screenshot capture is also a separate optional upstream tool; it is not started or bundled as a capture service. Its upstream MySQL/Python requirements still apply, including when running on a different PC. Screenshot settings are exposed in the launcher for operators using that tool; capture is disabled by default.

Build

Add this repository to LONELYICE_PLUGIN_DIRS in a configured LonelyIce build. CMake fetches the pinned upstream source and applies patches/*.patch. Git and Python 3 are needed at build time.

cmake -S /path/to/lonelyice -B /path/to/build \
  -DLONELYICE_CORE_DIR=/path/to/core \
  -DLONELYICE_PLUGIN_DIRS="/path/to/mod-playerbots;/path/to/mod-llm-chatter-plugin"
cmake --build /path/to/build --config RelWithDebInfo --target mod-llm-chatter

The plugin appears in bin/plugins/mod-llm-chatter (bin/RelWithDebInfo/plugins with Visual Studio). The CMake build provides libraries, configuration, SQL and bridge source. To make a distributable package, freeze the bridge on each target OS with Python 3.12 or newer:

python -m venv build/bridge-venv
# Activate the environment, then:
python -m pip install -r bridge/requirements-lock.txt
python cmake/freeze_bridge.py /path/to/fetched/upstream build/frozen build/freeze-work

On Debian/Ubuntu, building the runtime also requires python3-venv and the matching libpython3.x shared library. Copy the contents of build/frozen/chatter-bridge/ into the plugin's bridge/windows-x64/ or bridge/linux-x64/. Preserve the _internal/ directory. The bridge runtime includes Python, provider SDKs, MySQL connector and JSON validation dependencies. The normal LonelyIce/VC runtime prerequisites remain applicable. End users do not need Python or pip.

Use LonelyIce --pkg pack <plugin-folder> <output-folder> to make the package ZIP. Include the source/patches/build instructions in the release. The module's source revision is recorded in plugin.json; the port revision is the release tag. PyInstaller-collected distribution metadata contains dependency licenses. Both platforms use Python 3.12 in the initial release.

When updating upstream, regenerate controls with cmake/generate_settings.py, review the portable defaults, regenerate/review patches with cmake/patch_portable_sql.py, and rerun the checks.

Checks

Set LONELYICE_CHATTER_DATABASE_LIBRARY to the absolute path of chatter_database.dll or libchatter_database.so, and CHATTER_UPSTREAM to the fetched upstream directory, then run:

python -m unittest discover -s tests -v
python tests/check_cpp_queries.py /path/to/patched/upstream characters-schema.sql world-schema.sql
chatter-bridge --check-imports --config /path/to/module.conf --plugin-dir /path/to/plugin

Tests use isolated databases. They cover bound values, cross-database reads, SQL dates/upserts, exclusive queue claims, rollback, the real upstream party reservation and the current characters schema. Query checks prepare 296 complete C++/Python SQL literals against the current core schemas; dynamically assembled queries are outside that static check. Compilation and these checks do not establish in-game conversation quality or validate a particular live LLM provider. The first release is experimental and needs gameplay feedback.

Imported from the previous catalog.