mudmouth/docs/development.md

Development and build notes

Local development

Mudmouth requires Rust stable. On NixOS, the included shell also provides the ALSA development metadata used by the Linux audio backend:

nix-shell

Run the normal validation suite before submitting a change:

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release

Refreshing the PEQ NPC gender index

The checked-in generated/peq-npc-gender-index.json is generated data, not a runtime database dependency. Regenerate it from an explicit ProjectEQ dump with the tool below; it reads either create_tables_content.sql directly or the peq-dump/create_tables_content.sql member of the supplied zip archive. unzip is available in shell.nix for the latter.

cargo run --bin generate_peq_npc_index -- \
  --dump "$HOME/Downloads/peq-1759046415.zip" \
  --output generated/peq-npc-gender-index.json

The tool prints its input identity, complete conflict/neuter statistics, and output size. Run it twice and compare the output hashes before updating the checked-in artifact. The source archive and any temporary database files must not be committed or included in release archives.

The parser tests cover the observed log formats, including NPC dialogue, channel-chat exclusion, zone events, normalization, persistent/random speaker voice policies, log truncation, and first-run log discovery.

Running locally

Start the local Kokoro FastAPI service when necessary, then pass an EverQuest log directly:

doas systemctl start podman-kokoro-fastapi.service
cargo run --release -- --log "$HOME/Games/EverQuestLegends/Logs/eqlog_Pleb_oggok.txt"

Starting without a log path opens first-time setup. Mudmouth scans common Steam and Daybreak install folders for eqlog_*.txt files and lets you choose a character; if it finds none, enter the EverQuest game directory. Use [r] to rescan after enabling /log on in EverQuest. You can also change the log path and Kokoro endpoint from Settings:

cargo run --release
cargo run --release -- --kokoro-url http://127.0.0.1:8880

Release builds

Build Linux and Windows binaries locally with release.nix, then package them with:

nix-build release.nix -A linux -o result-linux
nix-build release.nix -A windows -o result-windows
./scripts/package-release.sh \
  --linux result-linux/bin/mudmouth \
  --windows result-windows/bin/mudmouth.exe

The packager writes platform-qualified archives and SHA256SUMS.txt to dist/. It also writes SIZE-REPORT.txt, recording the generated PEQ index, the two executables, and both final archives in bytes. Before writing the checksums, the packager verifies that each archive contains exactly its binary, README.md, LICENSE, and config.toml. This excludes PEQ dumps, SQL/fixture inputs, MariaDB data, the generator, and all source files from releases.

Keep the size report with the release/change description. When changing the embedded index encoding, compare its archive sizes against the previous report and record the Linux .tar.gz and Windows .zip deltas. Do not add an archive size threshold until a stable release baseline has been established.

PEQ index size audit — 2026-07-29

The following release builds compare pre-PEQ commit 561ace9 with the current core mapping implementation (tasks 1–4). The after size includes the embedded index and its resolver code.

Artifact	Before	After	Delta
Generated index	0 B	719,199 B	+719,199 B
Linux executable	6,772,856 B	7,535,632 B	+762,776 B
Linux .tar.gz	2,871,605 B	3,010,723 B	+139,118 B
Windows executable	6,577,369 B	7,332,144 B	+754,775 B
Windows .zip	2,805,692 B	2,944,841 B	+139,149 B

Both archives were inspected after packaging and contained only the platform binary, README.md, LICENSE, and config.toml. The compressed distribution cost is about 139 KB per platform; retain the JSON encoding until a future measurement establishes a material reason to optimize it.

scripts/publish-release.sh uploads the archive assets and checksums as a Gitea pre-release after the worktree is committed and clean.