@quantumplayed/quantum-game-engine 1.0.2 → 1.0.3

package/README.md

@@ -312,3 +312,182 @@ EntanglementEngine.conditionalInteract({
 // Because everything is sparse, branches where mathematically invalid things happen
 // (like trying to capture an empty square) don't consume memory.
 ```
+
+---
+
+## 6. Higher-Level Board Game Abstractions (The BoardGameHelpers Pattern)
+
+For board games (like Checkers or Chess), you can wrap low-level transitions and complex amplitudes into an intuitive, custom helper class within your project. This keeps your game rules code clean and accessible to non-quantum experts.
+
+Here is the recommended pattern:
+
+```typescript
+import { QuantumEntity, EntanglementEngine, Operations } from '@quantumplayed/quantum-game-engine';
+
+export class BoardGameHelpers {
+    /**
+     * Move a piece classically from source to target.
+     * Transitions state |1, 0> (source occupied, target empty) to |0, 1>.
+     */
+    static move(source: QuantumEntity, target: QuantumEntity): void {
+        const trans = [{ from: 2, to: 1, amplitude: { re: 1, im: 0 } }];
+        EntanglementEngine.interactMany([source, target], Operations.SparseTransition(trans));
+    }
+
+    /**
+     * Splits a piece equally into a superposition across two target entities.
+     * Ensure targets are cleared to state 0 (empty) first before calling.
+     */
+    static split(source: QuantumEntity, target1: QuantumEntity, target2: QuantumEntity): void {
+        target1.amplitudes = { 0: { re: 1, im: 0 } };
+        target1.entangledSystem = undefined;
+        target2.amplitudes = { 0: { re: 1, im: 0 } };
+        target2.entangledSystem = undefined;
+
+        const trans = [
+            { from: 4, to: 2, amplitude: { re: 0.70710678, im: 0 } }, // |1,0,0> -> |0,1,0>
+            { from: 4, to: 1, amplitude: { re: 0.70710678, im: 0 } }  // |1,0,0> -> |0,0,1>
+        ];
+        EntanglementEngine.interactMany([source, target1, target2], Operations.SparseTransition(trans));
+    }
+
+    /**
+     * Merges a split piece from two source entities back into a single target entity.
+     * Handles positive/negative phases for constructive/destructive interference.
+     */
+    static merge(source1: QuantumEntity, source2: QuantumEntity, target: QuantumEntity): void {
+        const trans = [
+            { from: 4, to: 1, amplitude: { re: 0.70710678, im: 0 } }, // |1,0,0> -> |0,0,1>
+            { from: 4, to: 6, amplitude: { re: 0.70710678, im: 0 } }, // |1,0,0> -> |1,1,0>
+            { from: 2, to: 1, amplitude: { re: 0.70710678, im: 0 } }, // |0,1,0> -> |0,0,1>
+            { from: 2, to: 6, amplitude: { re: -0.70710678, im: 0 } } // |0,1,0> -> -|1,1,0>
+        ];
+        EntanglementEngine.interactMany([source1, source2, target], Operations.SparseTransition(trans));
+    }
+
+    /**
+     * Performs a conditional capture (Toffoli gate logic): if both attacker and victim are occupied,
+     * the attacker moves to target and victim is captured (cleared to empty).
+     */
+    static capture(attacker: QuantumEntity, victim: QuantumEntity, target: QuantumEntity): void {
+        EntanglementEngine.conditionalInteract({
+            controls: [
+                { entity: attacker, state: 1 },
+                { entity: victim, state: 1 }
+            ],
+            targets: [
+                { entity: attacker, operation: Operations.Shift(1) },
+                { entity: target, operation: Operations.Shift(1) },
+                { entity: victim, operation: Operations.Shift(1) }
+            ]
+        });
+    }
+
+    /**
+     * Performs conditional captures for multiple victims sequentially.
+     */
+    static captureMany(attacker: QuantumEntity, victims: QuantumEntity[], target: QuantumEntity): void {
+        for (const victim of victims) {
+            this.capture(attacker, victim, target);
+        }
+    }
+}
+```
+
+---
+
+## 7. Quantum Card Abstractions (The CardGameHelpers Pattern)
+
+For quantum card games (like Quantum Poker or Blackjack), cards can exist in a superposition of multiple ranks/suits until they are observed. 
+
+Here is the helper pattern:
+
+```typescript
+import { QuantumEntity, Operations, EntanglementEngine } from '@quantumplayed/quantum-game-engine';
+
+export class CardGameHelpers {
+    /**
+     * Shuffles a card qudit (dimension = number of ranks in deck) 
+     * into a uniform superposition of possible ranks.
+     */
+    static shuffleSuperposition(card: QuantumEntity, fromRank: number, possibleRanks: number[]): void {
+        const factor = 1 / Math.sqrt(possibleRanks.length);
+        const transitions = possibleRanks.map(rank => ({
+            from: fromRank,
+            to: rank,
+            amplitude: { re: factor, im: 0 }
+        }));
+        card.apply(Operations.SparseTransition(transitions));
+    }
+
+    /**
+     * Deals a card from the deck to a player hand slot, entangling them.
+     * Transitions card from |deck_occupied, hand_empty> to |deck_empty, hand_occupied>.
+     */
+    static dealCard(deckSlot: QuantumEntity, handSlot: QuantumEntity): void {
+        // Assume 2-dimensional qudits (0=Empty/Card Gone, 1=Card Present)
+        const trans = [{ from: 2, to: 1, amplitude: { re: 1, im: 0 } }]; // |1,0> -> |0,1>
+        EntanglementEngine.interactMany([deckSlot, handSlot], Operations.SparseTransition(trans));
+    }
+}
+```
+
+---
+
+## 8. Quantum Inventory & Item Systems (The InventoryHelpers Pattern)
+
+In adventure games or RPGs, you can entangle chest contents or puzzles with player inventory state. If a player obtains a key in a superposition branch, the chest status becomes entangled with that reality branch.
+
+Here is the helper pattern:
+
+```typescript
+import { QuantumEntity, Operations, EntanglementEngine } from '@quantumplayed/quantum-game-engine';
+
+export class InventoryHelpers {
+    /**
+     * Entangles a chest and its reward with a key in the player's inventory.
+     * IF the key is gathered (state 1) and chest is closed (state 0):
+     *   1. Chest transitions to Open (state 1)
+     *   2. Reward item transitions to Obtained (state 1)
+     */
+    static entangleReward(key: QuantumEntity, chest: QuantumEntity, rewardItem: QuantumEntity): void {
+        EntanglementEngine.conditionalInteract({
+            controls: [
+                { entity: key, state: 1 },
+                { entity: chest, state: 0 }
+            ],
+            targets: [
+                { entity: chest, operation: Operations.Shift(1) },     // 0 (Closed) -> 1 (Open)
+                { entity: rewardItem, operation: Operations.Shift(1) } // 0 (None) -> 1 (Obtained)
+            ]
+        });
+    }
+}
+```
+
+---
+
+## 9. Branching Quantum Narrative Trees (The NarrativeHelpers Pattern)
+
+In branching dialogue systems or RPG narrative questlines, the story can branch down multiple paths simultaneously. The state of the world remains in a superposition until a player observes a dialogue consequence.
+
+Here is the helper pattern:
+
+```typescript
+import { QuantumEntity, Operations } from '@quantumplayed/quantum-game-engine';
+
+export class NarrativeHelpers {
+    /**
+     * Splits the narrative state (dimension = number of quest state nodes)
+     * from a root dialog node into an equal superposition of two branching outcomes.
+     */
+    static splitDecision(narrativeState: QuantumEntity, fromNode: number, branchANode: number, branchBNode: number): void {
+        const trans = [
+            { from: fromNode, to: branchANode, amplitude: { re: 0.70710678, im: 0 } },
+            { from: fromNode, to: branchBNode, amplitude: { re: 0.70710678, im: 0 } }
+        ];
+        narrativeState.apply(Operations.SparseTransition(trans));
+    }
+}
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quantumplayed/quantum-game-engine",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,4 +19,4 @@
     "typescript": "^6.0.3",
     "vitest": "^3.2.4"
   }
-}
+}