# Lore journal (lore.journal)

## What it is for

Lets the player find logs, letters and recordings in the world and keep them in a journal, grouped in series with shown progress, where reading an entry can unlock a recipe, a research or a door.

It needs `input.actions`, `game.engine`; installing it brings them in.

## Turn it on

Install the kit in a project, then change a setting (the values shown are its defaults):

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "lore.journal" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "lore.journal",
                              config: { "readLabel": "Read {name}", "toastSeconds": 4 } }
```

## First example

The kit has no dedicated test yet; this installs it and sets two of its settings to their defaults.

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "lore.journal" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "lore.journal",
                              config: { "readLabel": "Read {name}", "toastSeconds": 4 } }
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `readLabel` | string | `"Read {name}"` |  | Prompt of a lore point; {name} is its label, else the title of its first entry. |
| `toastSeconds` | number | `4` | 0–30 | How long the "New entry" notice stays on the HUD (0: none). |
| `openOnRead` | boolean | `true` |  | Reading a point opens the journal on its first new entry. |

## Services, events, variables

- Service `lore.journal`: entries() (with found), found(id), discover(id) → boolean (new), groups() → [{ group, found, total, complete }], open(entry?), close(), current(), toast(), placePoint(at, entry, opts?).
- Events emitted:
  - `lore.found` (`entry`, `group`, `first`) — An entry joined the journal.
  - `lore.group_completed` (`group`) — Every entry of a group is found.
  - `lore.opened` (`entry`) — The journal opened.
  - `lore.closed` — The journal closed.
- Events listened to: `interaction.requested`, `entity.spawned`, `game.phase`
- Variables:
  - `lore.found` (number) — Entries found
  - `lore.open` (boolean) — Journal open
- Verbs of the scripting layer:
  - `discover_lore` (action) — Add an entry to the journal (a find, a research, a mission).
  - `lore_found` (condition) — The entry is in the journal.
  - `lore_group_complete` (condition) — Every entry of the group is in the journal.
- Input actions: `journal_menu`

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `lore.find` (cancellable) — An entry is about to join the journal (a point read, discover(id), the discover_lore action): it exists and is not found yet.
- Moddable settings: `readLabel`, `toastSeconds`, `openOnRead`
- Moddable collections: `lore`
- Components: `lore_point`

## Engines

Declared targets: `web`, `rust`. `gripforge kit api lore.journal` lists the exact settings and services of your version.

## Versions

Kit version 1.1.1.