0019 – Characters tell what they know: knowledge cards

Status:

Accepted by the project owner and implemented in the working trees (not yet released)

Date:

2026-10-20

Context

The game should teach a little. Every character a player talks to is a person from some trade or time, so it can tell something true about itself: a short summary, one picture and the way to the article that says more.

Decision

  • “Tell me about yourself” is a button of the dialogue panel, offered by the client for every character that has a knowledge card. It is not an authored dialogue choice, so no dialogue has to be edited and it is offered at every node. A character without a card does not offer it.

  • A card (knowledge.yaml at the root of a datadisk, etc/knowledge.yaml for the generated characters) has an id, title_key, text_key (two to four sentences), image (a png or jpg below media/knowledge/, at most 1 MiB), credit_key (author, work and licence of the picture) and wikipedia: the title of the article by language, English required. A character names its card with about. Cards are shared by id, so several characters may tell the same one.

  • GET /story/npcs/{id}/about answers (token, the player within talking reach) with the keys, the media path of the picture and the article titles. The server never stores a language and chooses none: texts are keys of /story/strings and the client picks the language of the text and of the article. The dialogue reply says whether a card exists (about). No migration.

  • The client shows the picture in place of the portrait, the text, the credit and two buttons: back to the conversation and “Read more on Wikipedia”. The address is https://<language>.wikipedia.org/wiki/<title> with the language of the interface (English when the card has no article in it), and the browser is opened only after the player confirms a dialog that shows the address. Titles must hold no URL syntax (schema, server and client all check), so the host is always Wikipedia.

  • Pictures are shipped in the package (the server’s assets/knowledge/ for generated characters, the datadisk’s media/knowledge/), never loaded from Wikipedia at play time: no outside traffic, no tracking of the player, and the licence is known. Only public-domain or freely licensed pictures; author, work and licence go into credit_key and into debian/copyright.

  • The generated characters (trader, gate guard, shepherd, shipwright) tell cards of the server. A card whose picture is not installed is left out and its character has no such option.

Consequences

  • Writing a card is data: a text in each language, a picture with its credit and two article titles.

  • The text is the author’s to keep true; the article is the reader’s way to the rest.

  • Planned: cards for the characters of the Gilgamesh and Endland disks and for places and animals.