summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-06 02:31:55 -0300
committerGabriel Schneider <[email protected]>2026-11-06 04:04:25 -0300
commit33037ece5af9ae1c7048819bbbae3fc5e6fc4ade (patch)
tree796d4940e4687461d9db2e6a7041a75889368dfb
parent1b87e20543ca4577b855b3abf705561e9b45add8 (diff)
downloadpardes-33037ece5af9ae1c7048819bbbae3fc5e6fc4ade.tar.gz
pardes-33037ece5af9ae1c7048819bbbae3fc5e6fc4ade.zip
kinds #7, the docs: reference.typ's Addons section says ABI 2's contract (the tick rule and PA_FOCUSED, one paint a frame, the tag's prefix, art words and path, jobs across a reload, a client's Shadow), /addons as it is and --addon-test's words, and the changelog one entry
Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
-rw-r--r--docs/typ/reference.typ44
-rw-r--r--src/CHANGELOG.md7
2 files changed, 42 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>
diff --git a/src/CHANGELOG.md b/src/CHANGELOG.md
index 69d9d649..b69fa687 100644
--- a/src/CHANGELOG.md
+++ b/src/CHANGELOG.md
@@ -2,6 +2,13 @@
## Unreleased
+- Addons speak ABI 2 (src/kinds/pardes_addon.h): `tick` is told
+ `PA_FOCUSED` and called again after anything happens to its pane, so a
+ game stands still unfocused asking for nothing; one `paint` a frame;
+ jobs on the host's workers, dropped across a reload; each session its
+ own kinds; a client with no addon shows its panes from the session's
+ frames; `addons/snake` is a game in it.
+
- Half the settings are gone, each one now the value it had by default,
its word refused as any unknown one is (an init file that still says it
gets a notice naming its line), and a dump that kept it loads as before: