@rpgm-tools/neo-angband-mod-sdk 1.2.1 → 1.8.0

package/docs/tutorials/02-add-an-item.md

@@ -10,7 +10,7 @@ folder is and how to load one.
 
 ---
 
-## The whole mod
+## Mod files
 
 ```
 my-item-mod/
@@ -71,21 +71,21 @@ invented, which means the base game's own data is your reference manual. If you
 want to know what a field does, find an item that already does it and copy how
 it says so.
 
-- **`name`**: the trailing `~` is where the plural goes. "Padded Jerkin~"
+- `name`: the trailing `~` is where the plural goes. "Padded Jerkin~"
   displays as *a Padded Jerkin* and *2 Padded Jerkins*. An item whose name starts
   with `&` (`"& Dagger~"`) takes an article. These marks are the original game's
   convention, and they are why you should copy an existing name's punctuation
   rather than invent it.
-- **`type`**: which kind of item this is. `soft armor` puts it in the body
+- `type`: which kind of item this is. `soft armor` puts it in the body
   armour slot and in the armoury's stock. Use one the game already has;
   [Tutorial 4](04-change-a-spell.md)'s follow-on reading covers inventing a
   wholly new item class.
-- **`level`**: the depth at which it starts appearing.
-- **`alloc`**: how often, and between which depths. `common: 20` is roughly the
+- `level`: the depth at which it starts appearing.
+- `alloc`: how often, and between which depths. `common: 20` is roughly the
   frequency of ordinary early gear; `"1 to 40"` is the depth window.
-- **`armor.ac`**: the armour it gives. Soft Leather Armour has 8 and costs 20,
+- `armor.ac`: the armour it gives. Soft Leather Armour has 8 and costs 20,
   so 5 for 12 gold is a deliberately worse, cheaper option.
-- **`desc`**: an array of lines, shown when the player inspects it.
+- `desc`: an array of lines, shown when the player inspects it.
 
 **Where to get the numbers.** Open `packages/content/pack/object.json` in this
 repository and find an item like the one you want. That file is the base game's
@@ -94,7 +94,7 @@ always a working template. There is also a helper that does this for you:
 `draftRecord` fills in a new record from the game's comparable records, including
 a sensible price. See [AUTHORING.md](../AUTHORING.md).
 
-## What you should see
+## Check the result
 
 Your item exists in the game as soon as the mod is on: it generates in the
 dungeon inside its own depth window, monsters can be carrying one, and wearing it
@@ -112,13 +112,13 @@ made tutorial 1's dagger `core:sword--dagger`. The `my-item-mod:` half is your
 own namespace, so your item can never collide with the base game's or with
 another mod's, even if you both add a Padded Jerkin.
 
-## Try changing this
+## Variations to try
 
-- Make it **cursed-cheap and heavy**: `weight` 200, `cost` 2.
-- Make it **rare and deep**: `level` 30, `alloc` `{ "common": 3, "minmax": "30 to 100" }`.
-- Add a **second item** in the same `records` array. A mod can add as many as it
+- Make it cursed-cheap and heavy: `weight` 200, `cost` 2.
+- Make it rare and deep: `level` 30, `alloc` `{ "common": 3, "minmax": "30 to 100" }`.
+- Add a second item in the same `records` array. A mod can add as many as it
   likes; the array is a list.
-- Give it an **ego** possibility, or a flag. Find an item in the base game's
+- Give it an ego possibility, or a flag. Find an item in the base game's
   `object.json` that has the property you want and copy the field across.
 
 ## What your item joins automatically
@@ -126,15 +126,15 @@ another mod's, even if you both add a Padded Jerkin.
 This is the part worth knowing, because it is the part you do not have to build.
 Your Padded Jerkin is a soft armour, and the game treats it as one everywhere:
 
-- **Egos, runes and brands apply to it.** An ego declares the *kinds* of item it
+- Egos, runes and brands apply to it. An ego declares the *kinds* of item it
   can land on, not a list of named ones: "of Resist Acid" says `soft armor`, so
   it says your jerkin too. A **Padded Jerkin of Resist Fire** is a thing a player
   can find, and nobody had to add it to a list.
-- **Quality enchantment applies.** It can turn up as `[5,+6]`, and its price is
+- Quality enchantment applies. It can turn up as `[5,+6]`, and its price is
   recomputed from what it ended up being rather than from the `cost` you wrote.
-- **It is generated in the dungeon** at the depths your `alloc` names, and it is
+- It is generated in the dungeon at the depths your `alloc` names, and it is
   in the drop tables from the moment the mod is on.
-- **Shops will buy it,** because a shop's buy list is by item kind too.
+- Shops will buy it, because a shop's buy list is by item kind too.
 
 ## One thing that does NOT happen: a picture
 
@@ -191,18 +191,18 @@ offer it at any depth; `alloc` governs where it generates in the dungeon.
 
 Three things worth knowing about that patch:
 
-- **`core:store-armor`** is the store's record id: its code, `STORE_ARMOR`,
+- `core:store-armor` is the store's record id: its code, `STORE_ARMOR`,
   lowercased with `_` turned into `-`. That rule is the STORE file's, not a
   universal one - each data file declares what identifies its records, and the
   table of them is `packages/mod-sdk/src/record-key.ts`. Most files use `name`;
   `object` uses `type` plus `name`; `brand`, `slay` and `projection` use `code`;
   `constants` and `visuals` have one record each and are named by the file.
-- **`normal` is the "may stock" table; `always` is the staples.** Appending to
+- `normal` is the "may stock" table; `always` is the staples. Appending to
   `always` means a shop keeps one on the shelf at all times, which for most
   items is not what you want - and note the Armoury ships no `always` list at
   all, so appending to one there has nothing to append to and is reported rather
   than working quietly.
-- **`sval` is the item's name without the `~`.** If it does not match an item
+- `sval` is the item's name without the `~`. If it does not match an item
   that exists, the game drops that one line from the shop's table and reports it
   against your mod in the mod manager, so a typo costs you a line and tells you
   which one, rather than being silent or taking the game down with it.
@@ -223,7 +223,7 @@ manager says so on your mod's row, and everything else in the Armoury is exactly
 as it was. Declare the other mod in your `dependencies` so the player is told
 before they get there.
 
-## The finished version
+## Sample mod
 
 `samples/tutorials/tutorial-02-add-an-item/`, which is loaded and composed against the
 real game data on every test run.

package/docs/tutorials/03-add-a-monster.md

@@ -9,7 +9,7 @@ soldier ant, living on dungeon level 2.
 
 ---
 
-## The whole mod
+## Mod files
 
 ```
 my-monster-mod/
@@ -49,8 +49,8 @@ file is `monster.json`:
 
 Every monster inherits from a *monster base*, the template that decides its
 symbol on the map, what it is made of, which attacks it can have, and a pile of
-other defaults. `ant` is one the base game ships. So are `canine`, `orc`,
-`dragon`, and fifty-odd others - the file is
+other defaults. `ant` is one that the base game ships. So are `canine`, `orc`,
+`dragon`, and fifty-odd others. The file is
 `packages/content/pack/monster_base.json` and it holds 56 records in total, so it
 is short enough to read.
 
@@ -70,36 +70,36 @@ tutorial's own test asserts the base exists rather than trusting it.
 Same principle as items: find a monster close to what you want in
 `packages/content/pack/monster.json` and copy its shape.
 
-- **`speed`**: 110 is normal walking pace, the same as an unhasted player. 120
+- `speed`: 110 is normal walking pace, the same as an unhasted player. 120
   is fast enough to be genuinely dangerous.
-- **`depth`** and **`rarity`**: where it lives and how often it shows up there.
-- **`experience`**: not a flat award. What the player actually gets is
+- `depth` and `rarity`: where it lives and how often it shows up there.
+- `experience`: not a flat award. What the player actually gets is
   `experience * the monster's level / the player's level`, so the same monster is
   worth steadily less as the character grows.
-- **`sleepiness`**: how likely it is to be asleep when you arrive. 0 means it is
+- `sleepiness`: how likely it is to be asleep when you arrive. 0 means it is
   always awake and coming for you.
-- **`blow`**: a list. Each entry is a `method` (how it attacks), an `effect`
+- `blow`: a list. Each entry is a `method` (how it attacks), an `effect`
   (what that does to you), and `damage` dice. Three blows means three attacks per
   turn. The available methods and effects are in `blow_methods.json` and
   `blow_effects.json` beside the monster file.
-- **`color`**: a single letter, and the case matters. `u` is Umber (brown), `y`
+- `color`: a single letter, and the case matters. `u` is Umber (brown), `y`
   is Yellow, `w` is White - `W` is Light Slate, which is what the soldier ant
   actually is. `packages/core/src/color.ts` is the chart.
 
-## What you should see
+## Check the result
 
 Start a character, descend to level 2, and look for a brown `a`. Look it up with
 `/` or recall it with `l` and the game will describe it using the text you wrote.
 
-## Try changing this
+## Variations to try
 
-- Make it a **unique**: add `"flags": ["UNIQUE"]`, give it a capitalised proper
+- Make it a unique: add `"flags": ["UNIQUE"]`, give it a capitalised proper
   name and a lot more hit points.
-- Give it a **second blow** by adding another entry to the `blow` array.
-- Make it **fast and fragile**: `speed` 130, `hit-points` 4.
-- Add a whole **family**: several records in one array, sharing a base.
+- Give it a second blow by adding another entry to the `blow` array.
+- Make it fast and fragile: `speed` 130, `hit-points` 4.
+- Add a whole family: several records in one array, sharing a base.
 
-## Try breaking it
+## Test a bad base reference
 
 Change `"base": "ant"` to `"base": "aunt"` and reload. Notice what does *and does
 not* happen. That is the failure mode described above, and it is much easier to
@@ -109,9 +109,9 @@ recognise later if you have seen it once on purpose.
 
 Your ant already has an appearance, and you only wrote half of it:
 
-- **`"color": "u"`** is yours: umber, so it draws as a brown `a` and reads as a
+- `"color": "u"` is yours: umber, so it draws as a brown `a` and reads as a
   different creature from the white `a` beside it.
-- **The letter `a` is not yours.** It comes from `"base": "ant"`, along with
+- The letter `a` is not yours. It comes from `"base": "ant"`, along with
   everything else the template carries. Change the base and the letter changes.
 
 **In a tile set, your ant has no picture, and the game will not invent one.** A
@@ -152,13 +152,13 @@ tile mod that fills blanks, the family it borrows from.
 If you want a *specific* picture, a mod can say so. Both routes are past what this
 tutorial covers, and they differ more than they look:
 
-- **Point at a picture that already exists.** Ship a `.prf` as a `prefs`
+- Point at a picture that already exists. Ship a `.prf` as a `prefs`
   resource, and its `monster:carpenter ant:<attr>:<char>` line layers over the
   player's tile set and wins over anything a tile mod would have filled in. One
   line, no art, but the numbers are *atlas coordinates*, so they are correct for
   one pack and wrong for every other. Reach for this when your mod ships or
   requires a particular set.
-- **Ship a whole tile set.** A mod with the `tiles` facet contributes a graphics
+- Ship a whole tile set. A mod with the `tiles` facet contributes a graphics
   mode of its own (`tilePacks`), which is how the Linoleum sets are delivered.
   That is a set the player chooses from the Graphics menu, not one picture added
   to somebody else's set, which nothing supports today.
@@ -185,11 +185,11 @@ mirror of [Tutorial 1](01-tweak-a-value.md) is worth seeing on a monster:
 Giant black ants now have a little more health and hunt in groups. Two things
 that section is teaching beyond the ops themselves:
 
-- **`add` is not `set`.** `{"op": "add", "path": "hit-points", "value": 3}` means
+- `add` is not `set`. `{"op": "add", "path": "hit-points", "value": 3}` means
   "three more than whatever it is", so it still does the right thing if the base
   game retunes the monster, and it still does the right thing if another mod
   changed it first. `set` would silently undo both.
-- **`addFlag` composes.** Two mods adding different flags to the same monster both
+- `addFlag` composes. Two mods adding different flags to the same monster both
   get their flag; neither is a conflict. That is true of `addFlag`, `removeFlag`
   and `append`, and not true of `set`, `merge`, `add` or `mul`. For those, two
   mods on the same field is a reported conflict and the one that loads last wins.
@@ -197,7 +197,7 @@ that section is teaching beyond the ops themselves:
 A patched monster keeps its picture, because the tile set already knows it by
 name. Only the ant you *added* has nothing drawn for it.
 
-## The finished version
+## Sample mod
 
 `samples/tutorials/tutorial-03-add-a-monster/` in this repository is exactly
 this mod. It is not a copy of the tutorial. It is a mod that gets loaded and

package/docs/tutorials/04-change-a-spell.md

@@ -9,7 +9,7 @@ and almost never fails.
 
 ---
 
-## The whole mod
+## Mod files
 
 ```
 my-spell-mod/
@@ -48,7 +48,7 @@ To find the spell you want, open `packages/content/pack/class.json`, find your
 class, and count. Books and spells are in the order they appear in the game's own
 spell menu, so you can count them on screen instead if that is easier.
 
-## The catch worth knowing now
+## Positional paths can target the wrong spell
 
 **A number in that path is a position, not a name.**
 
@@ -101,12 +101,12 @@ The `effect` block is the game's own effect vocabulary: `BOLT_STATUS`,
 game ships, but inventing a new one is a code job rather than a data job; that
 is [Tutorial 5](05-hook-behaviour.md) and the pages beyond it.
 
-## What you should see
+## Check the result
 
 Roll a Priest, learn Minor Healing, and open the spell menu. Its mana cost reads
 1 and its failure rate is far lower than an unmodded Priest's at the same level.
 
-## Try changing this
+## Variations to try
 
 - Retune a **different class**: `core:mage`, `core:ranger`, `core:paladin`.
 - Move a spell **earlier**: set its `level` to 1 and get it at character
@@ -114,7 +114,7 @@ Roll a Priest, learn Minor Healing, and open the spell menu. Its mana cost reads
 - Make a class **worse** at something, which is often what makes a variant
   interesting rather than a cheat.
 
-## The finished version
+## Sample mod
 
 `samples/tutorials/tutorial-04-change-a-spell/`.
 

package/docs/tutorials/05-hook-behaviour.md

@@ -11,7 +11,7 @@ dependencies, just one `.js` file beside the manifest.
 
 ---
 
-## The whole mod
+## Mod files
 
 ```
 my-code-mod/
@@ -109,24 +109,24 @@ Exactly as before: the `mods/` folder on the desktop build, or **Choose a mods
 folder...** in a browser. A code mod is loaded from a folder the same way a data
 mod is.
 
-## What you should see
+## Check the result
 
 Gain a level. The message reads *"Congratulations! Welcome to level 2."*
 
 Turn the mod off, reload, and it reads *"Welcome to level 2."* again.
 
-## Try changing this
+## Variations to try
 
-- Congratulate **loudly**: `` `*** ${raw.toUpperCase()} ***` ``.
+- Congratulate loudly: `` `*** ${raw.toUpperCase()} ***` ``.
 - React to a **different** message. Find one you like in the game and match on
   it.
-- Add a **second** hook. `saveNoiseScent` and `objectListTiebreak` are two of the
-  other seven; see [MOD_SEAMS.md](../MOD_SEAMS.md) for what each one is asked and
-  when.
+- Add a second hook. `saveNoiseScent` and `objectListTiebreak` are two of the
+  other seven; see [MOD_SEAMS.md](../MOD_SEAMS.md) for what each one is asked to do
+  and when.
 - Print something to the console from inside the hook and watch how often it is
   called. It is a good way to get a feel for the game's message volume.
 
-## The finished version
+## Sample mod
 
 `samples/tutorials/tutorial-05-hook-behaviour/`, which really is imported and really is
 folded through the game's own hook composition on every test run. The test would

package/docs/tutorials/06-add-an-option.md

@@ -9,7 +9,7 @@ and off, from the game, without editing anything.
 
 ---
 
-## The whole mod
+## Mod files
 
 Same two files. `manifest.json` gains a `rules` block:
 
@@ -55,7 +55,7 @@ export default {
 That is the entire feature. There is no settings API to learn, no storage to
 manage, and no screen to build.
 
-## How it works
+## The manifest flag controls hook registration
 
 You **declare** the switch in the manifest. The game builds the screen, shows
 your `title` and `description`, remembers what the player chose, and puts the
@@ -79,9 +79,9 @@ hook at all**, not inside `messageText`, returning `raw` unchanged.
 
 Both look identical to the player. They are not the same thing:
 
-- **Checking inside the hook** means the game calls your function for every
+- Checking inside the hook means the game calls your function for every
   message it ever prints, forever, and your function decides to do nothing.
-- **Checking around the hook** means that when the option is off, you supplied no
+- Checking around the hook means that when the option is off, you supplied no
   hook, so the game runs its own untouched path and your mod is not in it at all.
 
 The second is the shape to reach for. A disabled option should cost nothing and
@@ -102,7 +102,7 @@ let them choose.
 The first-party `feature-restoration` mod works exactly this way: enabling it
 changes nothing at all until you pick a feature.
 
-## What you should see
+## Check the result
 
 Enable the mod and reload. Nothing changes yet, and that is correct.
 
@@ -110,7 +110,7 @@ Press `Escape`, choose **Mods**, choose your mod, and you will find *Congratulat
 me on gaining a level* on its own screen, off. Turn it on, choose **Apply changes
 and reload**, and gain a level.
 
-## Try changing this
+## Variations to try
 
 - Add a **second** option, controlling something else, and see both appear.
 - Make one **default on** and notice how differently the mod feels to install.
@@ -119,7 +119,7 @@ and reload**, and gain a level.
   `renamedSectionFlags` in [AUTHORING.md](../AUTHORING.md), since there is a
   supported way to do either without losing everyone's saved choice.
 
-## The finished version
+## Sample mod
 
 `samples/tutorials/tutorial-06-add-an-option/`. Its test asserts the interesting half:
 that with the option off, the mod supplies **no hook at all**.

package/docs/tutorials/07-add-an-artifact.md

@@ -26,10 +26,10 @@ describing the difference, not the thing.
 Two consequences follow from that, and they are what makes artifacts feel
 different from tutorial 2:
 
-- **It is unique.** The game generates each artifact at most once per character.
+- It is unique. The game generates each artifact at most once per character.
   There is no `alloc` fight with a hundred other shields; there is one of these,
   or there is not one yet.
-- **It inherits some things and not others.** The base object supplies the
+- It inherits some things and not others. The base object supplies the
   kind's flags, and its activation when your artifact declares none. It does NOT
   supply the numbers: `weight`, `ac`, `to-a`, `to-h`, `to-d` and the damage dice
   all come from the artifact record, and one you leave out binds to zero rather
@@ -37,7 +37,7 @@ different from tutorial 2:
   leather shield's weight class, its material, how it reacts to acid: all of that
   arrives for free because you named the base.
 
-## The whole mod
+## Mod files
 
 ```
 my-artifact-mod/
@@ -123,11 +123,11 @@ Leather Shield of the Watchful Eye~*.
 
 Both halves of it have to name something real:
 
-- **`tval`** is the item type, and it comes from `object_base.json`. `shield`,
+- `tval` is the item type, and it comes from `object_base.json`. `shield`,
   `sword`, `hard armor`, `light`, `ring`. Note the American spelling on the
   armour ones, which catches people, and note that these are the base game's
   own strings rather than anything you get to choose.
-- **`sval`** is the base object's name inside that type, from `object.json`, with
+- `sval` is the base object's name inside that type, from `object.json`, with
   the `&` and `~` decoration stripped off. The entry reads
   `"& Leather Shield~"`; you write `"Leather Shield"`.
 
@@ -174,21 +174,21 @@ dropped, so `'Angrist'` is `core:angrist`. If a ref does not resolve, the loader
 tells you so by name; that is the friendly failure, and it is what
 `npx neo-angband-mod-check` is for.
 
-## What to fiddle with
+## Artifact fields
 
 Everything below `base-object` is the fun part.
 
-- **`level`** is how deep the game considers the artifact to be, which feeds
+- `level` is how deep the game considers the artifact to be, which feeds
   into how it is priced and how good it is allowed to be.
-- **`alloc`** is `common`, the weighting against everything else eligible, and
+- `alloc` is `common`, the weighting against everything else eligible, and
   `minmax`, the depth band it can appear in. `"12 to 70"` means it will not be
   generated shallower than 12 or deeper than 70.
-- **`armor.ac`** replaces the base object's armour class, and **`armor.to-a`** is
+- `armor.ac` replaces the base object's armour class, and `armor.to-a` is
   the bonus on top. On a weapon you would be reaching for `attack.hd`, `to-h` and
   `to-d` instead.
-- **`flags`** are the yes-or-no properties: `SEE_INVIS`, `PROT_FEAR`,
+- `flags` are the yes-or-no properties: `SEE_INVIS`, `PROT_FEAR`,
   `FREE_ACT`, `REGEN`, and a long list more.
-- **`values`** are the ones that carry a number, written with the number in
+- `values` are the ones that carry a number, written with the number in
   square brackets: `INFRA[2]`, `RES_DARK[1]`, `STR[2]`, `SPEED[5]`.
 
 Both lists are in `packages/content/pack/object_property.json`. One catch when
@@ -204,7 +204,7 @@ If you want an artifact that does something when you activate it, that is `act`
 plus `time`, and the names come from `activation.json`. Copy a base-game artifact
 that already activates and change the numbers before writing one from scratch.
 
-## What you learned
+## Artifact rules to remember
 
 - An artifact is a **layer over an existing item**, not a new item, which is why
   `base-object` exists and why the rest is mostly numbers.
@@ -214,7 +214,7 @@ that already activates and change the numbers before writing one from scratch.
   because the base game needs that behaviour for the Phial. Copy the sval.
 - `add` beats `set` when you are adjusting a number the base game owns.
 
-## The finished version
+## Sample mod
 
 `samples/tutorials/tutorial-07-add-an-artifact/` in this repository is exactly
 this mod. It is not a copy of the tutorial. It is a mod that gets loaded and

package/docs/tutorials/README.md

@@ -1,6 +1,6 @@
 # Make a mod
 
-**Never made a mod before? That is fine.** These seven tutorials assume you can
+**Never made a mod before? That is fine.** These eight tutorials assume you can
 edit a text file and nothing else. The first one takes about five minutes and
 changes the game.
 
@@ -10,7 +10,7 @@ in it.
 
 ---
 
-## The seven tutorials
+## The eight tutorials
 
 Each one teaches exactly one idea and ends with something you can see on screen.
 
@@ -23,19 +23,22 @@ Each one teaches exactly one idea and ends with something you can see on screen.
 | 5 | [Hook behaviour](05-hook-behaviour.md) | Your mod running code, in ten lines | 2 |
 | 6 | [Add an option](06-add-an-option.md) | Letting the player switch your change on and off | 2 |
 | 7 | [Add an artifact](07-add-an-artifact.md) | Building on top of an item the game already has | 2 |
+| 8 | [Add a store](https://github.com/neostryder/neo-angband/blob/master/docs/modding/tutorials/08-add-a-store.md) | Turning a town storefront into your own shop, and adding one shop rule | 4 |
 
 Do them in order if you are new. They build on each other, and each one is short
 enough to read in full before you type anything. Tutorial 7 is the one exception:
 it needs tutorial 2 and nothing else, so you can jump to it if an artifact is
-what brought you here.
+what brought you here. Tutorial 8 needs tutorials 2 and 5, and is the one to
+jump to if a shop is what brought you here.
 
-**These are not snippets.** Every tutorial's finished mod is a real folder in
+**These are not snippets.** Tutorials 1 through 7 each have a finished mod in
 this repository under `samples/tutorials/`, loaded and checked against the actual
 game data on every test run, including a check that each one would be accepted
-by the same folder reader the game itself uses. If a tutorial ever stops working,
-the build fails before you find out the hard way.
+by the same folder reader the game itself uses. Tutorial 8's four complete files
+are on its page. If a sampled tutorial ever stops working, the build fails before
+you find out the hard way.
 
-**You can run them without typing anything.** Copy any of the seven folders out of
+**You can run them without typing anything.** Copy any of the first seven folders out of
 `samples/tutorials/` into the `mods/` folder beside the desktop build (or point a
 browser at `samples/tutorials/` with **Choose a mods folder...**), and they turn
 on from the Mods screen like any other mod. They are named `tutorial-01-...` to
@@ -54,17 +57,17 @@ it.
 Neo Angband is for when you would rather your change be a **portable thing** than
 an edit:
 
-- **The base game stays untouched.** Your change is a layer over it, not a
+- The base game stays untouched. Your change is a layer over it, not a
   modification of it.
-- **It has an off switch**, and turning it off gives back the unmodified game
+- It has an off switch, and turning it off gives back the unmodified game
   exactly.
-- **You share a folder or a repository link**, not a fork and not a patch file.
-- **Several mods combine**, from several people, without any of them having to
+- You share a folder or a repository link, not a fork and not a patch file.
+- Several mods combine, from several people, without any of them having to
   know about each other.
-- **You can expose settings** so the people using it can tune it without editing
+- You can expose settings so the people using it can tune it without editing
   it.
-- **The game can update underneath it** without you re-applying anything.
-- **It scales all the way up.** The same system that changes one number can carry
+- The game can update underneath it without you re-applying anything.
+- It scales all the way up. The same system that changes one number can carry
   an entire variant.
 
 That last point is the real one. The spectrum runs from:
@@ -89,12 +92,12 @@ personal versions of the game and no shared ground.
 
 That is not what this is for, and the design says so:
 
-- **The base game ships as the shared vanilla target**, the latest official
+- The base game ships as the shared vanilla target, the latest official
   Angband release, faithfully, with no mods enabled. That is what an untouched
   install gives you and what the project measures itself against.
-- **This project bundles no mods at all.** Not even the author's. Every one of
+- This project bundles no mods at all. Not even the author's. Every one of
   them installs the same way yours would.
-- **Every mod is a layer you can name, list, and remove.** A game's enabled mods
+- Every mod is a layer you can name, list, and remove. A game's enabled mods
   and versions are recorded in its diagnostics and written into the character
   dump, so any two people can tell whether they were playing the same thing.
 
@@ -103,7 +106,7 @@ having one.
 
 ---
 
-## What would I even mod?
+## Ideas for a first mod
 
 If you want a starting point rather than a blank folder:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpgm-tools/neo-angband-mod-sdk",
-  "version": "1.2.1",
+  "version": "1.8.0",
   "description": "Pack schemas, validation, and tooling for Neo Angband mods (content packs, tile packs, scripted plugins)",
   "license": "GPL-2.0-only",
   "author": "neostryder (RPGM Tools)",

package/src/capabilities.ts

@@ -181,6 +181,10 @@
  *                             the character on disk untouched. Neither is a
  *                             superset of the other and `grantCovers` compares the
  *                             action, so one consent cannot buy both.
+ *  - "display:filter"      - apply a post-processing filter to the game's rendered
+ *                             terminal canvas. It is deliberately separate from
+ *                             display:replace: changing the appearance of the
+ *                             faithful renderer is not taking ownership of it.
  *  - "ui:panel.mount"      - draw with real HTML instead of the character grid: a
  *                             panel of the mod's own, mounted on the page above
  *                             the game. A THIRD "ui:" action, and the reason it is
@@ -226,11 +230,17 @@ export type ParsedCapability =
   | { kind: "state"; domain: string; access: "read" }
   | { kind: "network"; host: string }
   | { kind: "registry"; domain: string }
-  | { kind: "display"; action: "replace" }
+  | { kind: "display"; action: "replace" | "filter" }
   | { kind: "ui"; region: string; action: "replace" | "create" | "mount" }
   | { kind: "backup"; action: "folder" }
   | { kind: "mod"; action: "install" | "session" }
-  | { kind: "debug"; action: "spawn" | "wizard" };
+  | { kind: "debug"; action: "spawn" | "wizard" }
+  | { kind: "keymap"; action: "write" }
+  | { kind: "query"; action: "snapshot" }
+  | { kind: "policy"; action: "install" }
+  | { kind: "hook"; action: "respond" }
+  | { kind: "registry-declaration"; action: "declare" }
+  | { kind: "ui-region"; action: "write" };
 
 const EVENT_RE = /^event:([a-z][a-z0-9-]*)$/;
 /**
@@ -319,8 +329,8 @@ export function parseCapability(cap: string): ParsedCapability {
    * sees of the dungeon is drawn by this mod." It is the display OWNER, so it
    * has no domain to name and no wildcard to sit under - `registry:*` must not
    * carry it, which is exactly what a separate kind buys. */
-  if (cap === "display:replace") {
-    return { kind: "display", action: "replace" };
+  if (cap === "display:replace" || cap === "display:filter") {
+    return { kind: "display", action: cap === "display:replace" ? "replace" : "filter" };
   }
   /* "backup:folder": lets the mod write files into a folder the player picks;
    * the mod never learns the folder's real path (the browser will not say),
@@ -368,6 +378,14 @@ export function parseCapability(cap: string): ParsedCapability {
   if (cap === "debug:wizard") {
     return { kind: "debug", action: "wizard" };
   }
+  if (cap === "keymap:write") {
+    return { kind: "keymap", action: "write" };
+  }
+  if (cap === "query:snapshot") return { kind: "query", action: "snapshot" };
+  if (cap === "policy:install") return { kind: "policy", action: "install" };
+  if (cap === "hook:respond") return { kind: "hook", action: "respond" };
+  if (cap === "registry:declare") return { kind: "registry-declaration", action: "declare" };
+  if (cap === "ui:region") return { kind: "ui-region", action: "write" };
   const ui = UI_RE.exec(cap);
   if (ui) {
     return { kind: "ui", region: ui[1] as string, action: "replace" };
@@ -434,7 +452,7 @@ function grantCovers(grant: ParsedCapability, request: ParsedCapability): boolea
       /* Exact match only. See parseCapability: `registry:*` does not reach
        * here, so a mod holding the override wildcard still cannot take the
        * display without asking for it by name. */
-      return grant.kind === "display";
+      return grant.kind === "display" && grant.action === request.action;
     case "backup":
       /* Exact match only, same reasoning as "display" - there is exactly one
        * backup capability and no wildcard grant could ever cover it. */
@@ -458,6 +476,18 @@ function grantCovers(grant: ParsedCapability, request: ParsedCapability): boolea
        * experience and the acquirement too. Exactly the #261 lesson, caught by
        * adding the second action rather than by shipping it. */
       return grant.kind === "debug" && grant.action === request.action;
+    case "keymap":
+      return grant.kind === "keymap" && grant.action === request.action;
+    case "query":
+      return grant.kind === "query" && grant.action === request.action;
+    case "policy":
+      return grant.kind === "policy" && grant.action === request.action;
+    case "hook":
+      return grant.kind === "hook" && grant.action === request.action;
+    case "registry-declaration":
+      return grant.kind === "registry-declaration" && grant.action === request.action;
+    case "ui-region":
+      return grant.kind === "ui-region" && grant.action === request.action;
     case "ui":
       /* Per region, with one wildcard. A `display` grant is NOT accepted here
        * and a `ui` grant is not accepted above: owning the dungeon and owning