motely-wasm 17.7.0 → 18.1.1

package/README.md

@@ -2,6 +2,8 @@
 
 WebAssembly package for [Motely](https://github.com/OptimusPi/MotelyJAML) — the Balatro seed search engine, with filters written in JAML.
 
+The package ships `jaml.schema.json` (JSON Schema for the JAML filter format) at the package root, so editors can wire it up for autocomplete / validation without an extra fetch.
+
 ## Install
 
 ```sh
@@ -124,6 +126,60 @@ const result = Motely.analyzeJamlSeeds(jaml, ["ABCD1234", "XYZ99"]);
 console.log(Motely.version());
 ```
 
+## JAML schema
+
+`motely-wasm` ships `jaml.schema.json` at the package root — point your editor at it for
+autocomplete and inline validation while writing filters:
+
+```json
+{
+  "$schema": "node_modules/motely-wasm/jaml.schema.json"
+}
+```
+
+Or with a `# yaml-language-server` comment at the top of any `.jaml` / `.yml` filter file:
+
+```yaml
+# yaml-language-server: $schema=node_modules/motely-wasm/jaml.schema.json
+name: WeeMonday
+deck: Erratic
+stake: Black
+must:
+  - joker: WeeJoker
+    antes: [1]
+```
+
+JAML is a YAML dialect (JSON-compatible). A filter is a flat document:
+
+| Key | Purpose | Example |
+|---|---|---|
+| `name` | Human label | `WeeMonday` |
+| `deck` | Starting deck | `Erratic`, `Red`, `Ghost`, … |
+| `stake` | Difficulty floor | `White`, `Black`, `Gold`, … |
+| `must` | All clauses must match | list of clause objects |
+| `mustNot` | All clauses must NOT match | list of clause objects |
+| `should` | Scored clauses (use with `score:`) | list of clause objects |
+
+Each clause object names a target type (`joker`, `tarot`, `planet`, `voucher`, `tag`, `boss`) plus
+optional filters (`antes`, `sources`, `min`, `score`):
+
+```yaml
+must:
+  - joker: WeeJoker          # specific item name, or "Any"
+    antes: [1, 2]            # which antes to check (omit = all)
+    sources:
+      shopItems: [0, 1]      # shop slot indices
+      boosterPacks: [0]      # pack slot indices
+  - tag: NegativeTag
+    antes: [1]
+  - voucher: Telescope
+    antes: [1, 2]
+    min: 2                   # appear at least N times across all listed antes
+```
+
+Use `Motely.validateJaml(jaml)` to check a filter string at runtime; `Motely.explainJaml(jaml)`
+returns a human-readable plan; `Motely.createPlan(jaml)` returns the scoring structure.
+
 ## Running a search
 
 `Motely.createSearch(jaml)` returns a settings builder. Chain a search-mode method,
@@ -155,6 +211,69 @@ console.log(search.isCompleted, search.totalSeedsSearched, search.matchingSeeds)
 search.cancel(); // stop early
 ```
 
+## Stream pagers
+
+Pagers expose Balatro's raw PRNG streams — one packed int per item, no JAML filter needed.
+**Always prefer `getNextChunk(n)` over repeated `getNext()` calls** — each call is a WASM
+interop crossing, so batching is the right default:
+
+```js
+import { Motely, MotelyDeck, MotelyStake } from "motely-wasm";
+
+const pager = Motely.createShopPager("AAAAAAAA", MotelyDeck.Red, MotelyStake.White, 1);
+const items = pager.getNextChunk(6); // 6 packed ints, one crossing
+```
+
+Each factory targets a distinct PRNG stream — these are not the same stream filtered, so there
+is one factory per stream type:
+
+| Factory | Stream |
+|---|---|
+| `createShopPager(seed, deck, stake, ante)` | Mixed shop (jokers, tarots, planets, spectrals on Ghost, standard cards with MagicTrick) |
+| `createJokerPager(seed, deck, stake, ante)` | Shop jokers — includes edition + sticker bits |
+| `createTarotPager(seed, deck, stake, ante)` | Shop tarots |
+| `createPlanetPager(seed, deck, stake, ante)` | Shop planets |
+| `createSpectralPager(seed, deck, stake, ante)` | Shop spectrals (non-Ghost returns `SpectralExcludedByStream`) |
+| `createLegendaryJokerPager(seed, deck, stake, ante)` | Legendary fixed-rarity joker stream |
+| `createRareTagJokerPager(seed, deck, stake, ante)` | Rare Tag hand-out joker stream |
+| `createTagPager(seed, deck, stake, ante)` | Tags — value is `MotelyTag` cast to int |
+| `createVoucherPager(seed, deck, stake, ante)` | Vouchers — value is `MotelyVoucher` cast to int |
+
+## Packed-int decoders
+
+All pager streams return packed integers. Bit fields are extracted with the decode helpers
+exported from the entry point:
+
+```js
+import {
+    Motely,
+    MotelyItemType, MotelyItemTypeCategory, MotelyJokerRarity,
+    MotelyItemEdition, MotelyItemSeal, MotelyItemEnhancement,
+} from "motely-wasm";
+
+const pager = Motely.createJokerPager("AAAAAAAA", 0, 0, 1);
+const v = pager.getNext();
+
+const type      = Motely.decodeItemType(v);        // → MotelyItemType value
+const category  = Motely.decodeItemCategory(v);    // → MotelyItemTypeCategory value
+const rarity    = Motely.decodeJokerRarity(v);     // → MotelyJokerRarity (Common/Uncommon/Rare/Legendary)
+const edition   = Motely.decodeItemEdition(v);     // → MotelyItemEdition (None/Foil/Holo/Poly/Negative)
+const seal      = Motely.decodeItemSeal(v);        // → MotelyItemSeal
+const enh       = Motely.decodeItemEnhancement(v); // → MotelyItemEnhancement
+
+const perishable = Motely.isPerishable(v);  // → boolean
+const eternal    = Motely.isEternal(v);     // → boolean
+const rental     = Motely.isRental(v);      // → boolean
+
+console.log(MotelyItemType[type]);      // e.g. "WeeJoker"
+console.log(MotelyJokerRarity[rarity]); // e.g. "Common"
+```
+
+All enum tables (`MotelyItemType`, `MotelyItemTypeCategory`, `MotelyJokerRarity`,
+`MotelyItemEdition`, `MotelyItemSeal`, `MotelyItemEnhancement`, `MotelyTag`,
+`MotelyVoucher`, `MotelyBoosterPack`, `MotelyDeck`, `MotelyStake`) are exported from
+`motely-wasm` and can be used for reverse-lookup by numeric value or forward-lookup by name.
+
 ## Events
 
 | Event | Payload |