summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/typ/reference.typ44
1 files changed, 35 insertions, 9 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 205b0400..972d5794 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -978,9 +978,29 @@ game, a plot. It is written against one header, `src/kinds/pardes_addon.h`,
in C or anything that speaks C, and links nothing of pardes: the records
are the header's, and what pardes does for it (an allocation from the
pane's arena, a job off the loop, a Look, a message, a new text pane) it is
-handed at load. `addons/fake/fake.c` uses every function; a kind with only
-a head and `paint` is a valid one. Image is a kind compiled in, through the
-same records.
+handed at load. `addons/fake/fake.c` uses every function and
+`addons/snake/snake.c` is a game in it; a kind with only a head and `paint`
+is a valid one. Image is a kind compiled in, through the same records. The
+header is ABI 2: an addon built against another major is refused.
+
+- `tick(state, now, flags)` returns the absolute time of its next step
+ (0: none) on a monotonic clock. It is called when that time comes and
+ once after `open`, a key or click it took, a word, a job's answer, a
+ `load`, and whenever `PA_FOCUSED` (its pane has the keyboard in some
+ view, its window focused) changes: a kind that returned 0 is woken by
+ the next thing that happens to it, and one that steps only while focused
+ asks for nothing otherwise. `paint` is called once a frame and changes
+ nothing (a Debug build checks the kind's memory across it).
+- The tag of its pane is the prefix its last frame gave (else its kind's
+ name), then, when that frame placed a picture, the core's own
+ `petscii:on palette:commodore ascii:off` (#word("Petscii"),
+ #word("Palette") and #word("Ascii") are the core's words), then its
+ path.
+- Its jobs run on the host's workers; one asked before an
+ #word("Addon") `reload` answers into nothing, and the old library stays
+ until its last such job has answered.
+- A client of the session runs no addon's code: a pane of a kind it lacks
+ shows the session's frames of it, and its keys go to the session.
- #word("Addon") `load <path>` (relative to the pane's directory) loads
one; `unload <name>` lets one go, refused while a pane of its kind is
@@ -989,10 +1009,12 @@ same records.
a library that fails any check leaves the old one running; bare, it says
the kinds here. At start, every `*.so` of `$XDG_DATA_HOME/pardes/addons`,
then of `<prefix>/lib/pardes/addons`, is loaded.
-- #file("/addons"): a line a kind, `<kind> <version> <abi> static|loaded
- <path>`, and a line an addon refused, with why: another ABI's major, no
- `pardes_addon`, a word, leader path or extension already someone's (the
- core's or another addon's: refused whole), words with no `ctl`.
+- #file("/addons"): a line a kind, `<kind> <version> <abi> <panes open>
+ <path> <blake3> static|loaded`, and a line an addon refused, with why:
+ another ABI's major, no `pardes_addon`, a word, leader path or extension
+ already someone's (the core's or another addon's: refused whole), words
+ for its panes with no `ctl`. Each session has its own: a library is
+ shared by the sessions of a process that loaded the same bytes.
- Its words join #file("/commands") and Help, `(addon <name>)` after each.
Written to a pane of its kind they go to that kind; a word that opens its
kind opens a pane of it from anywhere, its argument the path; any other
@@ -1011,8 +1033,12 @@ same records.
library, listed so, until #word("Addon") `load` asks for it again. A
crash inside one says `in addon <file>, <call>` in the crash record.
- `pardes --addon-test <lib> <script>` runs a script of keys, clicks,
- words and ticks against a pane of its kind and prints the pane after
- each: an addon's test, compared with `diff`.
+ words and ticks (its clock starts at 1 s), `focus` and `blur`, `size C
+ R` (the session's terminal), `dump` (the pane's record, loaded into a
+ fresh pane), `body` and `ctl` against a pane of its kind and prints the
+ pane after each, with `window CxR` (the cells it paints) at the start
+ and after `size`: an addon's test, compared with `diff`. `settle` ticks
+ until the kind asks for no step, and fails for one that asks while idle.
= The pardes command <command-line>