koishipro-core.js 1.2.2 → 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,21 +37,29 @@ __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,
-  consumeResponseFromOcgcoreProcess: () => consumeResponseFromOcgcoreProcess,
   createDuelFromYrp: () => createDuelFromYrp,
   createOcgcoreWrapper: () => createOcgcoreWrapper,
   createSqljsCardReader: () => createSqljsCardReader,
@@ -62,7 +71,6 @@ __export(index_exports, {
   parseRegistryKeys: () => parseRegistryKeys,
   playYrp: () => playYrp,
   playYrpStep: () => playYrpStep,
-  processYrpDuelStep: () => processYrpDuelStep,
   testCard: () => testCard
 });
 module.exports = __toCommonJS(index_exports);
@@ -261,6 +269,22 @@ var OcgcoreDuel = class {
       message: parsedMessage
     };
   }
+  *advance(advancor) {
+    while (true) {
+      const res = this.process();
+      yield res;
+      if (res.status === 2 || res.message instanceof import_ygopro_msg_encode3.YGOProMsgRetry) {
+        break;
+      }
+      if (res.status === 1 && res.raw.length > 0) {
+        const response = advancor?.(res.message);
+        if (!response) {
+          break;
+        }
+        this.setResponse(response);
+      }
+    }
+  }
   newCard(card) {
     this.ocgcoreWrapper.ocgcoreModule._new_card(
       this.duelPtr,
@@ -1191,6 +1215,7 @@ async function DirCardReader(sqljs, ...baseDirs) {
 
 // src/play-yrp.ts
 var import_ygopro_yrp_encode = require("ygopro-yrp-encode");
+var import_ygopro_msg_encode5 = require("ygopro-msg-encode");
 var { LOCATION_DECK, LOCATION_EXTRA, POS_FACEDOWN_DEFENSE } = import_ygopro_msg_encode.OcgcoreScriptConstants;
 function normalizeYrp(input) {
   if (input instanceof import_ygopro_yrp_encode.YGOProYrp) {
@@ -1290,45 +1315,19 @@ function createDuelFromYrp(wrapper, yrpInput) {
   duel.startDuel(yrp.opt >>> 0);
   return { yrp, duel };
 }
-function consumeResponseFromOcgcoreProcess(duel, result, responses) {
-  if (result.raw.length > 0 && result.raw[0] === import_ygopro_msg_encode.OcgcoreCommonConstants.MSG_RETRY) {
-    throw new Error("Got MSG_RETRY");
-  }
-  if (result.status === 0) {
-    return false;
-  }
-  if (result.status === 1) {
-    if (result.raw.length === 0) {
-      return false;
-    }
-    const response = responses.shift();
-    if (!response) {
-      return true;
-    }
-    duel.setResponse(response);
-    return false;
-  }
-  return true;
-}
-function* processYrpDuelStep(duel, yrp) {
-  const responses = yrp.responses.slice();
-  while (true) {
-    const result = duel.process();
-    yield {
-      duel,
-      result,
-      responses
-    };
-    if (consumeResponseFromOcgcoreProcess(duel, result, responses)) {
-      break;
-    }
-  }
-}
 function* playYrpStep(ocgcoreWrapper, yrpInput) {
   const { yrp, duel } = createDuelFromYrp(ocgcoreWrapper, yrpInput);
+  const responses = yrp.responses.slice();
   try {
-    for (const stepResult of processYrpDuelStep(duel, yrp)) {
-      yield stepResult;
+    for (const result of duel.advance(() => responses.shift())) {
+      yield {
+        duel,
+        result,
+        responses
+      };
+      if (result.message instanceof import_ygopro_msg_encode5.YGOProMsgRetry) {
+        throw new Error("Got MSG_RETRY");
+      }
     }
   } finally {
     duel.endDuel();
@@ -1385,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,
@@ -1398,21 +1510,29 @@ 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,
-  consumeResponseFromOcgcoreProcess,
   createDuelFromYrp,
   createOcgcoreWrapper,
   createSqljsCardReader,
@@ -1424,7 +1544,6 @@ if (typeof globalThis !== "undefined" && !globalThis.Buffer) {
   parseRegistryKeys,
   playYrp,
   playYrpStep,
-  processYrpDuelStep,
   testCard
 });
 //# sourceMappingURL=index.cjs.map