# sentences

> **Tool `tools/triage/sentences.py`** (program, Triage). List the sentences in a program: the long strings a person wrote for players, such as messages, mission text, item descriptions and notes left by the developers.

Run it with `./gameframe run sentences ARGS` or `python3 tools/triage/sentences.py`. [Source on GitHub](https://github.com/tanepiper/game-frame/blob/main/tools/triage/sentences.py).

## Its own help

This is the help text in the tool itself, as `./gameframe tool sentences` prints it.

```text
List the sentences in a program: the long strings a person wrote for players, such as
messages, mission text, item descriptions and notes left by the developers.

Usage: sentences.py FILE [--min-words N] [--grep WORD] [--sort address|words] [--json]

  FILE           a binary (any kind: PE, DOS, a data file, a memory dump), or the strings.txt
                 of a Ghidra export (lines of ADDRESS<TAB>TEXT), read as is
  --min-words N  the fewest words a sentence has (default 5)
  --grep WORD    only sentences that contain WORD (case-blind; repeat for any of several)
  --sort         address (default: the order the program keeps them, which is often the order
                 of the story) or words (longest first)
  --json         one record per sentence: offset, virtual address, encoding, words, text

A game's story and its rules are often written in its own text before they are visible in its
code (docs/working/lore.md). This tool finds that text. From a binary it reads runs of
printable bytes (ASCII and Latin-1) and UTF-16LE text, splits them at line breaks, and keeps
the pieces that read like sentences: at least N words, mostly letters, with spaces between
the words. Format codes such as %s and %d count as words and are kept, so templates like
"%s is low on power" appear too. For a Windows PE file each hit also gets its virtual address,
which finds the code that uses it (refs, decomp_query).

It does not decode compressed or encrypted text (xorscan.py, filetypes.py), text built on the
stack (stackstrings.py), or text in a custom encoding. The output is the game's own text: write
it into analysis/ or another ignored folder, never into a tracked file. Standard library only.
```