koishipro-core.js 1.2.3 → 1.2.4

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,26 @@ __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,
+  SlientAdvancor: () => SlientAdvancor,
   SqljsCardReader: () => SqljsCardReader,
+  StaticAdvancor: () => StaticAdvancor,
+  SummonPlaceAdvancor: () => SummonPlaceAdvancor,
   ZipReader: () => ZipReader,
   ZipScriptReader: () => ZipScriptReader,
   _OcgcoreConstants: () => vendor_exports,
@@ -267,7 +277,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 +1384,125 @@ 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;
+  })
+);
+
 // 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 +1510,26 @@ 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,
+  SlientAdvancor,
   SqljsCardReader,
+  StaticAdvancor,
+  SummonPlaceAdvancor,
   ZipReader,
   ZipScriptReader,
   _OcgcoreConstants,