koishipro-core.js 1.2.3 → 1.2.5

package/README.md

@@ -162,6 +162,26 @@ Represents a single duel instance with full lifecycle management.
 - `endDuel(): void`  
   End the duel and clean up resources.
 
+**Advance Helpers (Advancors):**
+- `advance(advancor?: Advancor): Generator<OcgcoreProcessResult>`  
+  Advances the duel processing loop. It repeatedly calls `process()`, and when a response is required, it invokes your advancor. It stops when the duel ends, a retry is requested, or your advancor returns `undefined`.
+
+**Example (Advance + Advancor)**
+```ts
+import { createOcgcoreWrapper, SlientAdvancor } from 'koishipro-core.js';
+
+const wrapper = await createOcgcoreWrapper();
+// ...setScriptReader / setCardReader / create duel / start duel...
+
+const duel = wrapper.createDuel(1234);
+
+for (const result of duel.advance(SlientAdvancor())) {
+  if (result.message) {
+    console.log(result.message);
+  }
+}
+```
+
 **Card Management:**
 - `newCard(card: OcgcoreNewCardParams): void`  
   Add a card to the duel.
@@ -267,6 +287,61 @@ for (const { duel, result } of playYrpStep(wrapper, yrpBytes)) {
 }
 ```
 
+
+### Advancors
+Advancors are small response producers. You pass them into `duel.advance(...)` and they auto-generate response bytes for the current message. If multiple advancors are combined, the first one that returns a response wins.
+
+**Type**
+```ts
+import { YGOProMsgResponseBase } from 'ygopro-msg-encode';
+
+export type Advancor<T extends YGOProMsgResponseBase = YGOProMsgResponseBase> =
+  (message: T) => Uint8Array | null | undefined;
+```
+
+#### `SlientAdvancor()`
+Calls `defaultResponse()` for any message. In practice, this auto-answers optional effect prompts with “do not activate” and is ideal for fast-forwarding.
+
+#### `NoEffectAdvancor()`
+Only responds to `SelectChain` when there are **no** chains available, allowing the duel to continue. It does not auto-decline effect prompts. Use this when you want to handle effect prompts yourself.
+
+#### `SummonPlaceAdvancor(placeAndPosition?)`
+Auto-selects summon placement (`SelectPlace`) and position (`SelectPosition`). You can pass a partial filter to constrain player/location/sequence/position.
+
+#### `SelectCardAdvancor(...filters)`
+Selects cards by matching filters (e.g., code, location, controller). Supports several message types like `SelectCard`, `SelectUnselectCard`, `SelectSum`, `SelectTribute`.
+
+#### `StaticAdvancor(items)`
+Returns a fixed sequence of responses you provide. Each call consumes one item.
+
+#### `CombinedAdvancor(...advancors)`
+Runs advancors in order and returns the first non-`undefined` response. This is the same combiner used by `advance(...)` internally.
+
+#### `MapAdvancor(...handlers)`
+Dispatches by message class. Each handler maps a message type to an advancor function.
+
+#### `MapAdvancorHandler(msgClass, cb)`
+Helper for building `MapAdvancor` handler objects.
+
+#### `LimitAdvancor(advancor, limit)`
+Wraps an advancor and only allows it to return a response `limit` times.
+
+#### `OnceAdvancor(advancor)`
+Shorthand for `LimitAdvancor(advancor, 1)`.
+
+#### `PlayerViewAdvancor(player, advancor)`
+Runs the inner advancor only when `responsePlayer()` matches the specified player.
+
+#### Composition
+You can combine advancors to form a pipeline:
+```ts
+duel.advance(
+  SlientAdvancor(),
+  SummonPlaceAdvancor(),
+  SelectCardAdvancor({ code: 28985331 }),
+);
+```
+
 ### Card Reader
 
 #### `SqljsCardReader(...dbs: Database[]): CardReader`

package/dist/index.cjs

@@ -29,6 +29,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // index.ts
 var index_exports = {};
 __export(index_exports, {
+  CombinedAdvancor: () => CombinedAdvancor,
   DirCardReader: () => DirCardReader,
   DirReader: () => DirReader,
   DirScriptReader: () => DirScriptReader,
@@ -36,17 +37,27 @@ __export(index_exports, {
   LEN_EMPTY: () => LEN_EMPTY,
   LEN_FAIL: () => LEN_FAIL,
   LEN_HEADER: () => LEN_HEADER,
+  LimitAdvancor: () => LimitAdvancor,
   MESSAGE_BUFFER_SIZE: () => MESSAGE_BUFFER_SIZE,
+  MapAdvancor: () => MapAdvancor,
+  MapAdvancorHandler: () => MapAdvancorHandler,
   MapReader: () => MapReader,
   MapScriptReader: () => MapScriptReader,
+  NoEffectAdvancor: () => NoEffectAdvancor,
   OcgcoreDuel: () => OcgcoreDuel,
   OcgcoreDuelOptionFlag: () => OcgcoreDuelOptionFlag,
   OcgcoreDuelRule: () => OcgcoreDuelRule,
   OcgcoreMessageType: () => OcgcoreMessageType,
   OcgcoreWrapper: () => OcgcoreWrapper,
+  OnceAdvancor: () => OnceAdvancor,
+  PlayerViewAdvancor: () => PlayerViewAdvancor,
   QUERY_BUFFER_SIZE: () => QUERY_BUFFER_SIZE,
   REGISTRY_BUFFER_SIZE: () => REGISTRY_BUFFER_SIZE,
+  SelectCardAdvancor: () => SelectCardAdvancor,
+  SlientAdvancor: () => SlientAdvancor,
   SqljsCardReader: () => SqljsCardReader,
+  StaticAdvancor: () => StaticAdvancor,
+  SummonPlaceAdvancor: () => SummonPlaceAdvancor,
   ZipReader: () => ZipReader,
   ZipScriptReader: () => ZipScriptReader,
   _OcgcoreConstants: () => vendor_exports,
@@ -267,7 +278,7 @@ var OcgcoreDuel = class {
         break;
       }
       if (res.status === 1 && res.raw.length > 0) {
-        const response = advancor?.();
+        const response = advancor?.(res.message);
         if (!response) {
           break;
         }
@@ -1374,12 +1385,324 @@ function testCard(ocgcoreWrapper, ...ids) {
   return logs;
 }
 
+// src/advancors/slient-advancor.ts
+var SlientAdvancor = () => {
+  return (msg) => {
+    return msg.defaultResponse();
+  };
+};
+
+// src/advancors/static-advancor.ts
+var import_nfkit = require("nfkit");
+var StaticAdvancor = (items) => {
+  const _items = (0, import_nfkit.makeArray)(items).slice();
+  return () => _items.shift();
+};
+
+// src/advancors/no-effect-advancor.ts
+var import_ygopro_msg_encode6 = require("ygopro-msg-encode");
+
+// src/advancors/map-advancor.ts
+var MapAdvancorHandler = (msgClass, cb) => ({
+  msgClass,
+  cb
+});
+var MapAdvancor = (...handlers) => {
+  const handlerMap = /* @__PURE__ */ new Map();
+  for (const handleObj of handlers) {
+    handlerMap.set(handleObj.msgClass, handleObj.cb);
+  }
+  return (msg) => {
+    const cb = handlerMap.get(
+      msg.constructor
+    );
+    if (cb != null) {
+      const res = cb(msg);
+      if (res != null) {
+        return res;
+      }
+    }
+    return void 0;
+  };
+};
+
+// src/advancors/no-effect-advancor.ts
+var NoEffectAdvancor = () => MapAdvancor(
+  MapAdvancorHandler(import_ygopro_msg_encode6.YGOProMsgSelectChain, (msg) => {
+    if (msg.chains.length) {
+      return;
+    }
+    return msg.prepareResponse(void 0);
+  })
+);
+
+// src/advancors/combined-advancor.ts
+var CombinedAdvancor = (...advancors) => {
+  return (msg) => {
+    for (const advancor of advancors) {
+      const res = advancor(msg);
+      if (res != null) {
+        return res;
+      }
+    }
+    return void 0;
+  };
+};
+
+// src/advancors/limit-advancor.ts
+var LimitAdvancor = (a, limit = 1) => {
+  let called = 0;
+  return (msg) => {
+    if (called >= limit) {
+      return void 0;
+    }
+    const res = a(msg);
+    if (res !== void 0) {
+      called++;
+    }
+    return res;
+  };
+};
+var OnceAdvancor = (a) => LimitAdvancor(a, 1);
+
+// src/advancors/player-view-advancor.ts
+var PlayerViewAdvancor = (player, a) => (msg) => {
+  if (msg.responsePlayer() === player) {
+    return a(msg);
+  }
+  return void 0;
+};
+
+// src/advancors/summon-place-advancor.ts
+var import_ygopro_msg_encode7 = require("ygopro-msg-encode");
+var SummonPlaceAdvancor = (placeAndPosition = {}) => MapAdvancor(
+  MapAdvancorHandler(import_ygopro_msg_encode7.YGOProMsgSelectPlace, (msg) => {
+    const places = msg.getSelectablePlaces().filter(
+      (p) => (placeAndPosition.player == null || p.player === placeAndPosition.player) && (placeAndPosition.location == null || p.location === placeAndPosition.location) && (placeAndPosition.sequence == null || p.sequence === placeAndPosition.sequence)
+    ).slice(0, msg.count);
+    return msg.prepareResponse(places);
+  }),
+  MapAdvancorHandler(import_ygopro_msg_encode7.YGOProMsgSelectPosition, (msg) => {
+    if (placeAndPosition.position) {
+      return msg.prepareResponse(placeAndPosition.position);
+    }
+    const possiblePositions = msg.positions;
+    for (let i = 0; i < 8; i++) {
+      const value = 1 << i;
+      if ((possiblePositions & value) !== 0) {
+        return msg.prepareResponse(value);
+      }
+    }
+    return void 0;
+  })
+);
+
+// src/advancors/select-card-advancor.ts
+var import_ygopro_msg_encode8 = require("ygopro-msg-encode");
+var SelectCardAdvancor = (...cards) => {
+  const remainingCards = cards.slice();
+  const applyFilter = (items, filter) => {
+    return items.filter(
+      (item) => Object.entries(filter).every(
+        ([key, value]) => value == null || item[key] === value
+      )
+    );
+  };
+  const pickCard = (items, min, max) => {
+    const picked = [];
+    const usedIndices = /* @__PURE__ */ new Set();
+    const usedFilters = /* @__PURE__ */ new Set();
+    for (const filter of remainingCards) {
+      if (picked.length >= max) break;
+      let matchIndex = -1;
+      for (let i = 0; i < items.length; i++) {
+        if (usedIndices.has(i)) continue;
+        if (applyFilter([items[i]], filter).length === 1) {
+          matchIndex = i;
+          break;
+        }
+      }
+      if (matchIndex < 0) continue;
+      picked.push((0, import_ygopro_msg_encode8.IndexResponse)(matchIndex));
+      usedIndices.add(matchIndex);
+      usedFilters.add(filter);
+    }
+    if (picked.length < min) {
+      return void 0;
+    }
+    for (let i = remainingCards.length - 1; i >= 0; i--) {
+      if (usedFilters.has(remainingCards[i])) {
+        remainingCards.splice(i, 1);
+      }
+    }
+    return picked;
+  };
+  return MapAdvancor(
+    MapAdvancorHandler(import_ygopro_msg_encode8.YGOProMsgSelectCard, (msg) => {
+      const picked = pickCard(msg.cards, msg.min, msg.max);
+      if (picked) {
+        return msg.prepareResponse(picked);
+      }
+    }),
+    MapAdvancorHandler(import_ygopro_msg_encode8.YGOProMsgSelectUnselectCard, (msg) => {
+      const picked = pickCard(msg.selectableCards, 1, 1);
+      if (picked) {
+        return msg.prepareResponse(picked[0]);
+      }
+    }),
+    MapAdvancorHandler(import_ygopro_msg_encode8.YGOProMsgSelectSum, (msg) => {
+      const decodeOpParam = (opParam) => {
+        const u = opParam >>> 0;
+        if ((u & 2147483648) !== 0) {
+          return { amount: u & 2147483647, extra: 0 };
+        }
+        return { amount: u & 65535, extra: u >>> 16 & 65535 };
+      };
+      const amountOf = (c) => decodeOpParam(c.opParam).amount;
+      const mustSum = (msg.mustSelectCards ?? []).reduce(
+        (acc, c) => acc + amountOf(c),
+        0
+      );
+      const mustCount = (msg.mustSelectCards ?? []).length;
+      const pickedIdx = [];
+      const pickedIdxSet = /* @__PURE__ */ new Set();
+      const totalSum = () => mustSum + pickedIdx.reduce((acc, i) => acc + amountOf(msg.cards[i]), 0);
+      const totalCount = () => mustCount + pickedIdx.length;
+      const filterMatch = /* @__PURE__ */ new Map();
+      for (let fi = 0; fi < remainingCards.length; fi++) {
+        const f = remainingCards[fi];
+        const idx = msg.cards.findIndex(
+          (c, i) => !pickedIdxSet.has(i) && applyFilter([c], f).length === 1
+        );
+        if (idx < 0) continue;
+        pickedIdx.push(idx);
+        pickedIdxSet.add(idx);
+        filterMatch.set(fi, idx);
+      }
+      const consumeRemainingByFinalPick = () => {
+        const usedFilterIdx = /* @__PURE__ */ new Set();
+        for (const [fi, idx] of filterMatch.entries()) {
+          if (pickedIdxSet.has(idx)) usedFilterIdx.add(fi);
+        }
+        for (let i = remainingCards.length - 1; i >= 0; i--) {
+          if (usedFilterIdx.has(i)) remainingCards.splice(i, 1);
+        }
+      };
+      const target = msg.sumVal;
+      if (msg.mode === 1) {
+        let s = totalSum();
+        if (s < target) {
+          for (let i = 0; i < msg.cards.length; i++) {
+            if (s >= target) break;
+            if (pickedIdxSet.has(i)) continue;
+            pickedIdx.push(i);
+            pickedIdxSet.add(i);
+            s += amountOf(msg.cards[i]);
+          }
+        }
+        if (s < target) return;
+        const removable = (pos) => {
+          const idx = pickedIdx[pos];
+          const v = amountOf(msg.cards[idx]);
+          return s - v >= target;
+        };
+        for (let pos = pickedIdx.length - 1; pos >= 0; pos--) {
+          if (!removable(pos)) continue;
+          const idx = pickedIdx[pos];
+          const v = amountOf(msg.cards[idx]);
+          pickedIdx.splice(pos, 1);
+          pickedIdxSet.delete(idx);
+          s -= v;
+        }
+        for (const idx of pickedIdx) {
+          if (s - amountOf(msg.cards[idx]) >= target) return;
+        }
+        consumeRemainingByFinalPick();
+        return msg.prepareResponse(pickedIdx.map((i) => (0, import_ygopro_msg_encode8.IndexResponse)(i)));
+      }
+      const baseSum = mustSum;
+      const baseCount = mustCount;
+      const sumLeft = target - baseSum;
+      const minLeft = Math.max(0, msg.min - baseCount);
+      const maxLeft = Math.max(0, msg.max - baseCount);
+      if (sumLeft < 0) return;
+      if (maxLeft < 0) return;
+      const preSum = pickedIdx.reduce(
+        (acc, i) => acc + amountOf(msg.cards[i]),
+        0
+      );
+      const preCount = pickedIdx.length;
+      const sumNeed = sumLeft - preSum;
+      const minNeed = Math.max(0, minLeft - preCount);
+      const maxNeed = Math.max(0, maxLeft - preCount);
+      if (sumNeed < 0) return;
+      if (maxNeed < 0) return;
+      const candidates = [];
+      for (let i = 0; i < msg.cards.length; i++) {
+        if (pickedIdxSet.has(i)) continue;
+        const v = amountOf(msg.cards[i]);
+        if (v <= sumNeed) candidates.push({ idx: i, v });
+      }
+      const keyOf = (sum, cnt) => `${sum}|${cnt}`;
+      const dp = /* @__PURE__ */ new Map();
+      dp.set(keyOf(0, 0), {});
+      for (const c of candidates) {
+        const snapshot = Array.from(dp.keys());
+        for (const k of snapshot) {
+          const [sStr, cStr] = k.split("|");
+          const s = Number(sStr);
+          const cnt = Number(cStr);
+          const ns = s + c.v;
+          const ncnt = cnt + 1;
+          if (ns > sumNeed) continue;
+          if (ncnt > maxNeed) continue;
+          const nk = keyOf(ns, ncnt);
+          if (dp.has(nk)) continue;
+          dp.set(nk, { prevKey: k, takeIdx: c.idx });
+        }
+      }
+      let bestKey;
+      for (let cnt = minNeed; cnt <= maxNeed; cnt++) {
+        const k = keyOf(sumNeed, cnt);
+        if (dp.has(k)) {
+          bestKey = k;
+          break;
+        }
+      }
+      if (!bestKey) return;
+      const extraIdx = [];
+      let curKey = bestKey;
+      while (curKey !== keyOf(0, 0)) {
+        const node = dp.get(curKey);
+        if (typeof node.takeIdx === "number") extraIdx.push(node.takeIdx);
+        curKey = node.prevKey;
+      }
+      extraIdx.reverse();
+      for (const i of extraIdx) {
+        pickedIdx.push(i);
+        pickedIdxSet.add(i);
+      }
+      if (totalCount() < msg.min || totalCount() > msg.max) return;
+      if (totalSum() !== target) return;
+      consumeRemainingByFinalPick();
+      return msg.prepareResponse(pickedIdx.map((i) => (0, import_ygopro_msg_encode8.IndexResponse)(i)));
+    }),
+    MapAdvancorHandler(import_ygopro_msg_encode8.YGOProMsgSelectTribute, (msg) => {
+      const picked = pickCard(msg.cards, msg.min, msg.max);
+      if (picked) {
+        return msg.prepareResponse(picked);
+      }
+    })
+  );
+};
+
 // index.ts
 if (typeof globalThis !== "undefined" && !globalThis.Buffer) {
   globalThis.Buffer = import_buffer.Buffer;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CombinedAdvancor,
   DirCardReader,
   DirReader,
   DirScriptReader,
@@ -1387,17 +1710,27 @@ if (typeof globalThis !== "undefined" && !globalThis.Buffer) {
   LEN_EMPTY,
   LEN_FAIL,
   LEN_HEADER,
+  LimitAdvancor,
   MESSAGE_BUFFER_SIZE,
+  MapAdvancor,
+  MapAdvancorHandler,
   MapReader,
   MapScriptReader,
+  NoEffectAdvancor,
   OcgcoreDuel,
   OcgcoreDuelOptionFlag,
   OcgcoreDuelRule,
   OcgcoreMessageType,
   OcgcoreWrapper,
+  OnceAdvancor,
+  PlayerViewAdvancor,
   QUERY_BUFFER_SIZE,
   REGISTRY_BUFFER_SIZE,
+  SelectCardAdvancor,
+  SlientAdvancor,
   SqljsCardReader,
+  StaticAdvancor,
+  SummonPlaceAdvancor,
   ZipReader,
   ZipScriptReader,
   _OcgcoreConstants,