@quantumplayed/quantum-game-engine 1.0.2 → 1.2.0

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/dist/EntanglementEngine.d.ts

@@ -1,50 +1,14 @@
-import { QuantumEntity, type Predicate } from './QuantumEntity.js';
-import { type QuantumOperation, type SparseAmplitudes } from './Operations.js';
-import { type Complex } from './Complex.js';
-export declare class JointQuantumSystem {
-    static maxDimensionLimit: number;
-    static setMaxDimensionLimit(limit: number): void;
-    entities: QuantumEntity[];
-    dimensions: number[];
-    totalDimension: number;
-    jointAmplitudes: SparseAmplitudes;
-    private constructor();
-    static create(entities: QuantumEntity[]): JointQuantumSystem;
-    static merge(involvedEntities: QuantumEntity[]): JointQuantumSystem;
-    private _calculateTensorProduct;
-    decomposeState(jointState: number): number[];
-    composeState(states: number[]): number;
-    applyLocal(entityIndex: number, operation: QuantumOperation): void;
-    applyToSubspace(targetEntities: QuantumEntity[], operation: QuantumOperation): void;
-    getTargetProbabilities(targetEntity: QuantumEntity): Record<number, number>;
-    getTargetAmplitudes(targetEntity: QuantumEntity): Record<number, Complex>;
-    measureTarget(targetEntity: QuantumEntity, forcedOutcome?: number): number;
-    getProjectedAmplitudes(conditions: {
-        entity: QuantumEntity;
-        state: number;
-    }[]): SparseAmplitudes;
-    getJointProbability(conditions: {
-        entity: QuantumEntity;
-        state: number;
-    }[]): number;
-    areMutuallyExclusive(conditions: {
-        entity: QuantumEntity;
-        state: number;
-    }[]): boolean;
-    getReducedDensityMatrix(targetEntity: QuantumEntity): Record<number, Record<number, Complex>>;
-    /**
-     * Create a joint system from existing amplitudes and entities (Bit-Perfect Restoration/Cloning).
-     */
-    static inject(entities: QuantumEntity[], jointAmplitudes: SparseAmplitudes): JointQuantumSystem;
-}
-export interface TargetOperation {
-    entity: QuantumEntity;
-    operation: QuantumOperation;
-}
+import { QuantumEntity } from './QuantumEntity.js';
+import { QuantumSystem, type Predicate, type TargetOperation } from './QuantumSystem.js';
+import { type QuantumOperation } from './Operations.js';
+export { QuantumSystem as JointQuantumSystem, type TargetOperation, type Predicate };
+/**
+ * @deprecated Use QuantumSystem.interact or QuantumSystem.conditionalInteract directly.
+ */
 export declare const EntanglementEngine: {
     interactMany(entities: QuantumEntity[], operation: QuantumOperation): void;
     conditionalInteract(args: {
         controls: Predicate[];
         targets: TargetOperation[];
-    }): void;
+    }): QuantumSystem;
 };