231117 update

README.md

@@ -1,67 +1,64 @@
 # norns-example-mod
 
-this repo demonstrates how to create a "mod" which can augment/patch/hack matron
-(the lua scripting engine for norns).
+This repo demonstrates how to create a "mod" which can augment/patch/hack matron
+(the Lua scripting engine for norns).
 
 ## why
 
-a mod lives in the `dust` folder just like normal norns scripts. unlike norns
+A mod lives in the `dust` folder just like normal norns scripts. Unlike norns
 scripts, the code in a mod is loaded by matron when it starts up. mods can
-modify or extend the lua environment globally such that the changes are visible
+modify or extend the Lua environment globally such that the changes are visible
 to all scripts.
 
 ## how
 
 mods work by registering functions to be called by matron hooks. matron defines
-four hooks:
+five hooks:
 
 * `system_post_startup` - called after matron has fully started and system state
   has been restored but before any script is run
 * `system_pre_shutdown` - called when `SYSTEM > SLEEP` is selected from the menu
 * `script_pre_init` - called after a script has been loaded but before its
   engine has started, pmap settings restored, and `init()` function called
+* `script_post_init` - called after a script's `init()` function has been called
 * `script_post_cleanup` - called after a script's `cleanup()` function has been
   called, this normally occurs when switching between scripts
 
-multiple mods can each register their own callback function for a given hook.
-matron will call each registered function but the order in which the functions
-are called is arbitrary.
+Multiple mods can each register their own callback function for a given hook.
+matron will sort the hooks alphabetically before executing them. This allows mods that add parameters to add them in a consistent order -- eg. mods that need all parameters available before executing should start with `~` to ensure they're at the end.
 
-any errors generated within a registered function will be caught and ignored
-in the maiden REPL, but see
-[the debugging documentation](https://monome.org/docs/norns/help/#deeper-debugging)
+Any errors generated within a registered function will be caught and ignored
+in the maiden REPL, but see [the debugging documentation](https://monome.org/docs/norns/help/#deeper-debugging)
 for how you can access them.
 
 mods may additionally provide their own menu page accessible via the `SYSTEM >
 MODS` menu.
 
 ## layout
 
-a mod is any norns script/project which contains a file called `lib/mod.lua`.
-this layout allows a mod to be either a standalone project or simply
-functionality bundled along side an existing norns script. a mod is free to
+A mod is any norns script/project which contains a file called `lib/mod.lua`.
+This layout allows a mod to be either a standalone project or simply
+functionality bundled along side an existing norns script. A mod is free to
 `require` additional modules as needed.
 
 ## using
 
 mods by their nature can have a negative impact on system stability or make
-system level changes which may not be universally welcome. by default a mod,
-even if installed, will not be loaded by matron. one must explicitly enable a
+system level changes which may not be universally welcome. By default a mod,
+even if installed, will not be loaded by matron. One must explicitly enable a
 mod and restart matron before its functionality will be available.
 
-to enable a mod go to `SYSTEM > MODS` to see the list of installed mods. mods
+To enable a mod go to `SYSTEM > MODS` to see the list of installed mods. mods
 which are loaded will have a small dot to the left of their name.
 use `E2` to selected an item in the list and then use `E3` to enable or disable
-as appropriate. _unloaded_ mods will show a `+` to the right their name to
-indicate that they will be enabled (and thus loaded) on restart. _loaded_ mods will
+as appropriate. _Unloaded_ mods will show a `+` to the right their name to
+indicate that they will be enabled (and thus loaded) on restart. _Loaded_ mods will
 show a `-` to the right of their name indicating they will be disabled on
 restart.
 
-loaded mods which have a menu will have ` >` at the end of their name, pressing
+Loaded mods which have a menu will have ` >` at the end of their name, pressing
 `K3` will enter the mod's menu.
 
 ## developing
 
-see the `lib/mod.lua` file in this repo for more details.
-
-
+See the `lib/mod.lua` file in this repo for more details.