# shot

> **Tool `tools/live/shot.py`** (program, The running game). Keep a capture of the screen, a window or a file under a name of its own.

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

## Its own help

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

```text
Keep a capture of the screen, a window or a file under a name of its own. Never overwrite one.

Usage: shot.py NAME [--from FILE | --window ID | --display :N] [--text TEXT | --text-file FILE]
               [--dir DIR]

  NAME          what the capture shows: s3-setstate-error, menu-first-light (a-z, 0-9, - and _)
  --from FILE   keep a capture another tool made (a VM's screenshot copied out, a /tmp file)
  --window ID   capture one window (macOS: `screencapture -l ID`)
  --display :N  capture an X display (`import -window root` from ImageMagick, or `xwd`), as
                inside a Linux VM with Xvfb
  (none)        the whole screen (macOS: screencapture; Linux: the X display in $DISPLAY)
  --text TEXT   the dialog's message, the address, the log lines: kept beside it in NAME.txt
  --text-file   the same, from a file
  --dir DIR     where captures go (default derived/captures, which git ignores)

The capture goes to DIR/YYYY-MM-DD/NAME.EXT. When that name is taken, it becomes NAME-2.EXT,
NAME-3.EXT and so on. No capture is ever overwritten. It prints the path it wrote.

Why: the dialogs a game shows on the way to running are evidence. They are easy to lose. The
next run overwrites a scratch capture. Once the cause is fixed, the dialog never comes back
(docs/knowhow/context-keep-every-dialog.md). Captures of the game are game material. Keep them
out of git. A few go into documents, each with a caption.

It does not click the dialog away, read its text or crop. Standard library only. The screen
capture itself needs screencapture (macOS) or ImageMagick's import or xwd (X11).
```