236 lines
7.4 KiB
Markdown
236 lines
7.4 KiB
Markdown
# lib-core.notify
|
|
|
|
Headless player-facing message routing. Tag-based messages with a channel
|
|
registry, tag-filter routing, subscriber callbacks, and an engine.print mirror.
|
|
No render code; no UI.
|
|
|
|
**Version:** 0.1.0
|
|
**Lib-ID:** lib-core.notify
|
|
**Requires:** engine.time.now (optional, for auto-timestamp), engine.print (optional, for log mirror)
|
|
**Tags:** notify, message, channel, routing, hud
|
|
|
|
## Topology
|
|
|
|
<!-- topology:start (auto-generated; do not edit) -->
|
|
```mermaid
|
|
graph LR
|
|
this["lib-core.notify"]
|
|
engine_time["engine.time.now (optional)"]
|
|
engine_print["engine.print (optional)"]
|
|
this -.->|optional| engine_time
|
|
this -.->|optional| engine_print
|
|
```
|
|
<!-- topology:end -->
|
|
|
|
## Scope (v0.1.0)
|
|
|
|
v0.1 ships the data layer only:
|
|
|
|
- Channel registry (create, destroy, list)
|
|
- Tag-filter routing: OR-match on shared tags; empty filter = catch-all
|
|
- Per-channel history ring-buffer (max_history capped, oldest dropped)
|
|
- Subscribe / unsubscribe callbacks (returns opaque handle)
|
|
- Severity sugar wrappers: `info`, `warn`, `error`
|
|
- Engine-log mirror (calls `engine.print` on every posted message; toggle via `set_engine_log_mirror`)
|
|
|
|
**Intentional non-goals (deferred):**
|
|
- Glob/wildcard tag filters
|
|
- AND-combination or exclude-tag filters
|
|
- Persistent history (disk/savegame serialization)
|
|
- Display rendering (belongs in a future lib-core.notify-display)
|
|
|
|
## Message Schema
|
|
|
|
| Field | Type | Set by | Notes |
|
|
|-------------|--------------|-------------------|--------------------------------|
|
|
| `tags` | string[] | caller (required) | Non-empty; drives routing |
|
|
| `text` | string | caller (required) | Human-readable message body |
|
|
| `severity` | string | caller / auto | `"info"` / `"warn"` / `"error"`; defaults to `"info"` |
|
|
| `ttl` | number / nil | caller (optional) | Display timeout in seconds; toast mode falls back to channel/display default if unset |
|
|
| `source` | any / nil | caller (optional) | Optional source reference (e.g. originating entity) |
|
|
| `data` | table / nil | caller (optional) | Structured key/value payload; detail mode renders `msg.data.*` |
|
|
| `id` | number | auto | Monotonically increasing |
|
|
| `timestamp` | number / nil | auto | `engine.time.now()` if available |
|
|
|
|
## Channel Schema
|
|
|
|
| Field | Type | Required | Notes |
|
|
|----------------|----------|----------|----------------------------------------------------|
|
|
| `id` | string | yes | Unique channel identifier |
|
|
| `filter` | string[] | yes | Tag OR-list; `{}` = catch-all |
|
|
| `display_mode` | string | yes | `"log"` / `"toast"` / `"detail"` |
|
|
| `max_history` | number | no | Default: log=200, toast=20, detail=1 |
|
|
| `title` | string | no | Human-readable channel name |
|
|
|
|
## Filter Semantics
|
|
|
|
Routing uses an OR-list: a message is delivered to a channel if at least one
|
|
of the message's tags appears in the channel's filter array.
|
|
|
|
An empty filter array (`{}`) is a catch-all — every message is delivered
|
|
regardless of its tags.
|
|
|
|
```
|
|
channel filter = {"combat", "loot"} message tags = {"loot", "vendor"}
|
|
→ match: "loot" in both lists
|
|
```
|
|
|
|
## API
|
|
|
|
### `notify.create_channel(def)`
|
|
|
|
**Syntax:** `notify.create_channel(def: table) -> void`
|
|
|
|
**Example:**
|
|
```lua
|
|
notify.create_channel{
|
|
id = "combat-log",
|
|
filter = {"combat", "damage"},
|
|
display_mode = "log",
|
|
max_history = 100,
|
|
title = "Combat Log",
|
|
}
|
|
```
|
|
|
|
Registers a new channel. Loud-error on: non-table `def`, missing or empty
|
|
`def.id`, duplicate id, non-table `def.filter`, unknown `def.display_mode`.
|
|
`max_history` defaults to display-mode default (log=200, toast=20, detail=1).
|
|
|
|
---
|
|
|
|
### `notify.destroy_channel(channel_id)`
|
|
|
|
**Syntax:** `notify.destroy_channel(channel_id: string) -> void`
|
|
|
|
Removes the channel and all its subscribers. Idempotent (no-op if channel
|
|
does not exist).
|
|
|
|
---
|
|
|
|
### `notify.list_channels()`
|
|
|
|
**Syntax:** `notify.list_channels() -> table[]`
|
|
|
|
Returns a shallow-copy array of all registered channel definitions (without
|
|
internal history). Order is unspecified.
|
|
|
|
---
|
|
|
|
### `notify.post(msg)`
|
|
|
|
**Syntax:** `notify.post(msg: table) -> void`
|
|
|
|
**Example:**
|
|
```lua
|
|
notify.post{ tags = {"combat", "damage"}, text = "You hit goblin for 12 damage.", severity = "info" }
|
|
```
|
|
|
|
Posts a message. Auto-fills `id`, `timestamp`, and `severity` (default
|
|
`"info"`). Routes to all channels whose filter matches at least one tag.
|
|
Appends to channel history (ring-buffered at `max_history`), invokes all
|
|
registered subscriber callbacks in insertion order, and mirrors to
|
|
`engine.print` if `engine_log_mirror` is enabled.
|
|
|
|
Loud-error on: non-table `msg`, missing or non-array `msg.tags`, empty
|
|
`msg.tags`, non-string tag elements, non-string `msg.text`.
|
|
|
|
---
|
|
|
|
### `notify.info(tags, text)`
|
|
|
|
**Syntax:** `notify.info(tags: string[], text: string) -> void`
|
|
|
|
Sugar for `M.post{ tags=tags, text=text, severity="info" }`.
|
|
|
|
---
|
|
|
|
### `notify.warn(tags, text)`
|
|
|
|
**Syntax:** `notify.warn(tags: string[], text: string) -> void`
|
|
|
|
Sugar for `M.post{ tags=tags, text=text, severity="warn" }`.
|
|
|
|
---
|
|
|
|
### `notify.error(tags, text)`
|
|
|
|
**Syntax:** `notify.error(tags: string[], text: string) -> void`
|
|
|
|
Sugar for `M.post{ tags=tags, text=text, severity="error" }`.
|
|
|
|
---
|
|
|
|
### `notify.get_history(channel_id, n)`
|
|
|
|
**Syntax:** `notify.get_history(channel_id: string, n?: number) -> table[]`
|
|
|
|
**Example:**
|
|
```lua
|
|
local last5 = notify.get_history("combat-log", 5)
|
|
```
|
|
|
|
Returns a shallow-copy array of the last `n` messages delivered to the
|
|
channel, oldest-first within the returned slice. If `n` is nil or greater
|
|
than the number of stored messages, returns all stored messages. Returns
|
|
`{}` for unknown channels.
|
|
|
|
---
|
|
|
|
### `notify.subscribe(channel_id, callback)`
|
|
|
|
**Syntax:** `notify.subscribe(channel_id: string, callback: function) -> handle`
|
|
|
|
**Example:**
|
|
```lua
|
|
local handle = notify.subscribe("combat-log", function(msg)
|
|
hud.append(msg.text)
|
|
end)
|
|
```
|
|
|
|
Registers `callback` to be invoked whenever a message is routed to
|
|
`channel_id`. Returns an opaque handle table required by `unsubscribe`.
|
|
Loud-error on unknown channel or non-function callback.
|
|
|
|
---
|
|
|
|
### `notify.unsubscribe(handle)`
|
|
|
|
**Syntax:** `notify.unsubscribe(handle: table) -> void`
|
|
|
|
Removes the subscription identified by `handle`. Silent if the subscription
|
|
or channel no longer exists (idempotent).
|
|
|
|
---
|
|
|
|
### `notify.set_engine_log_mirror(enable)`
|
|
|
|
**Syntax:** `notify.set_engine_log_mirror(enable: bool) -> void`
|
|
|
|
Enables or disables mirroring every posted message to `engine.print`.
|
|
Only `true` (boolean) enables the mirror; any other value disables it.
|
|
Enabled by default at module load.
|
|
|
|
---
|
|
|
|
## Engine-Log Mirror
|
|
|
|
When `engine_log_mirror` is enabled (default), every call to `notify.post`
|
|
also calls `engine.print(msg.text)` if `engine.print` is available. This
|
|
provides zero-config visibility in the engine console during development.
|
|
|
|
Disable in production or when a channel subscriber handles its own output:
|
|
|
|
```lua
|
|
notify.set_engine_log_mirror(false)
|
|
```
|
|
|
|
---
|
|
|
|
## Test Backdoors
|
|
|
|
The following functions are for test-only use. Do not call them from game code.
|
|
|
|
- `notify._test_clear_all()` — resets all state to initial values
|
|
- `notify._test_get_subscribers(channel_id)` — returns raw subscriber list
|
|
- `notify._test_get_log_mirror()` — returns current `engine_log_mirror` bool
|