@pompidup/kingdomino-engine 2.0.3 → 2.1.2

package/README.md

@@ -1,5 +1,12 @@
 # Kingdomino Engine
 
+[![Node.js CI](https://github.com/Pompidup/KDomino/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/Pompidup/KDomino/actions/workflows/node.js.yml)
+![Branches](./badges/coverage-branches.svg)
+![Functions](./badges/coverage-functions.svg)
+![Lines](./badges/coverage-lines.svg)
+![Statements](./badges/coverage-statements.svg)
+![Coverage total](./badges/coverage-total.svg)
+
 ## Overview
 
 This is a simple and lightweight TypeScript engine designed to facilitate the gameplay of Kingdomino. It provides the core logic for managing game states, rules, and player interactions, making it easy to integrate into any application that requires a Kingdomino game engine.
@@ -39,11 +46,34 @@ Each method returns an updated game state object, which contains the current sta
 To start using the Kingdomino Engine, import it and initialize a new game instance:
 
 ```typescript
-import gameEngine from "@pompidup/kingdomino-engine";
+import createGameEngine from "@pompidup/kingdomino-engine";
 
-const engine = gameEngine();
+const engine = createGameEngine({});
 let gameState = engine.createGame({ mode: "Classic" });
+```
+
+### Options for GameEngine
+
+You can pass options to the `createGameEngine` function to customize the engine's behavior. The available options are:
+
+- `logging`: Enable or disable logging for debugging purposes. Default is `false`.
+- `shuffleMethod`: Specify the method used to shuffle dominoes. If not specified, a default shuffle method will be used.
+- `uuidMethod`: Specify the method used to generate UUIDs. If not specified, a default UUID method will be used.
+
+Here's an example of how to pass options to the engine:
+
+```typescript
+// Full custom options
+const options: EngineConfig = {
+  logging: true,
+  shuffleMethod: myCustomShuffleMethod,
+  uuidMethod: myCustomUuidMethod,
+};
+
+const engine = createGameEngine(options);
 
+// If you want default options
+const engine = createGameEngine({});
 ```
 
 ### Adding Players
@@ -51,30 +81,45 @@ let gameState = engine.createGame({ mode: "Classic" });
 Add players to the game by passing an array of player names:
 
 ```typescript
-gameState = engine.addPlayers(gameState, ["Player 1", "Player 2", "Player 3"]);
+gameState = engine.addPlayers({gameState, ["Player 1", "Player 2", "Player 3"]});
 ```
 
-### Setting Up Extra Rules
+### Getting Available Game Modes
 
-You can get available extra rules and add them to the game:
+You can get available game modes and select one for the game:
+
+```typescript
+const modes = engine.getModes({});
+gameState = engine.createGame({ mode: modes[0].name });
+```
+
+### Getting Available Extra Rules
+
+You can get available extra rules for a specific game mode and number of players:
 
 ```typescript
 const extraRules = engine.getExtraRules({ mode: "Classic", players: 2 });
+```
+
+### Setting Up Extra Rules
+
+You can add extra rules to the game to modify gameplay. For example, you can add the "The Middle Kingdom" rule:
+
+```typescript
 gameState = engine.addExtraRules({
-game: gameState,
-extraRules: ["The middle Kingdom"],
+  game: gameState,
+  extraRules: ["The middle Kingdom"],
 });
 ```
 
 ### Starting the Game
 
-After setting up players and rules, start the game:
+After setting up players and rules, start the game, the engine will automatically set up the initial game state and determine the first player (lord) to play in nextAction.
 
 ```typescript
 gameState = engine.startGame({ game: gameState });
 ```
 
-
 ### Player Actions
 
 Players can perform actions like picking a domino, placing a domino, and discarding a domino.
@@ -85,7 +130,7 @@ Players can perform actions like picking a domino, placing a domino, and discard
 gameState = engine.chooseDomino({
   game: gameState,
   lordId: "lordId",
-  dominoPick: 12
+  dominoPick: 12,
 });
 ```
 
@@ -97,7 +142,7 @@ gameState = engine.placeDomino({
   lordId: "lordId",
   position: { x: 0, y: 0 },
   orientation: "horizontal",
-  rotation: 0
+  rotation: 0,
 });
 ```
 
@@ -110,14 +155,30 @@ gameState = engine.discardDomino({
 });
 ```
 
-
 ### Game Flow
 
 The game progresses through various steps and actions. The `nextAction` property in the game state indicates what action should be taken next. This could be a step (like "addPlayers", "options", "start", or "result") or an action (like "pickDomino" or "placeDomino").
+Once the game is started you will receive the nextAction and nextLord, when you receive a nextStep the game isOver.
+You can use utility functions to check the game state and determine the next action to take.
+
+```typescript
+while (isGameWithNextAction(gameState)) {
+  // Manage player actions
+}
+
+if (isGameWithNextStep(gameState)) {
+  // Manage game steps, like adding players or showing results
+}
+```
 
 ### Scoring
 
-When the last turn is played, the game will automatically calculate and provide the final score for each player and their position.
+When the last turn is played, the game will automatically calculate the final score for each player and their position.
+You can get the results by calling the `getResults` method:
+
+```typescript
+gameState = engine.getResults({ game: gameState });
+```
 
 ## Extra Rules
 
@@ -143,13 +204,12 @@ type GameEngine = {
   addExtraRules: (command: AddExtraRulesCommand) => GameWithNextStep;
   startGame: (command: StartGameCommand) => GameWithNextAction;
   chooseDomino: (command: ChooseDominoCommand) => GameWithNextAction;
-  placeDomino: (command: PlaceDominoCommand) => GameWithNextAction | GameWithNextStep;
-  discardDomino: (command: DiscardDominoCommand) => GameWithNextAction | GameWithNextStep;
+  placeDomino: (command: PlaceDominoCommand) => GameState;
+  discardDomino: (command: DiscardDominoCommand) => GameState;
   getResults: (command: GetResultCommand) => GameWithResults;
 };
 ```
 
-
 #### Game
 
 Represents the current state of a Kingdomino game.
@@ -162,12 +222,12 @@ type Game = {
   players: Player[];
   lords: Lord[];
   turn: number;
+  nextAction: NextAction | NextStep;
   rules: SelectedRules;
   mode: GameMode;
 };
 ```
 
-
 #### NextStep and NextAction
 
 Represent the next step or action in the game flow.
@@ -177,14 +237,14 @@ type NextStep = {
   type: "step";
   step: "addPlayers" | "options" | "start" | "result";
 };
+
 type NextAction = {
   type: "action";
   nextLord: string;
-  nextAction: "pickDomino" | "placeDomino";
+  nextAction: "pickDomino" | "placeDomino" | "pass";
 };
 ```
 
-
 #### ExtraRule
 
 Represents an additional rule that can be applied to the game.
@@ -198,7 +258,6 @@ type ExtraRule = {
 };
 ```
 
-
 ### Methods
 
 #### createGame(command: CreateGameCommand): GameWithNextStep
@@ -221,11 +280,11 @@ Starts the game, setting up the initial game state.
 
 Allows a player to choose a domino.
 
-#### placeDomino(command: PlaceDominoCommand): GameWithNextAction | GameWithNextStep
+#### placeDomino(command: PlaceDominoCommand): GameState
 
 Allows a player to place a domino on their kingdom.
 
-#### discardDomino(command: DiscardDominoCommand): GameWithNextAction | GameWithNextStep
+#### discardDomino(command: DiscardDominoCommand): GameState
 
 Allows a player to discard a domino if they cannot place it.
 
@@ -236,4 +295,3 @@ Calculates and returns the final game results.
 ## Advanced Usage
 
 For more advanced usage and detailed API documentation, please refer to the source code and inline comments.
-

package/dist/index.d.ts

@@ -70,10 +70,6 @@ type ExtraRule = {
     mode: GameMode[];
     playersLimit?: number;
 };
-type Rules = {
-    basic: Record<number, BasicRules>;
-    extraRules: ExtraRule[];
-};
 type SelectedRules = {
     basic: BasicRules;
     extra: ExtraRule[];
@@ -112,6 +108,7 @@ type GameWithNextAction = Game & {
 type GameWithNextStep = Game & {
     nextAction: NextStep;
 };
+type GameState = GameWithNextAction | GameWithNextStep;
 type Score = {
     points: number;
     maxPropertiesSize: number;
@@ -141,33 +138,27 @@ type CreateGameCommand = {
 };
 
 type AddPlayersCommand = {
-    game: Game & {
-        nextAction: NextStep;
-    };
+    game: GameState;
     players: string[];
 };
 
 type AddExtraRulesCommand = {
-    game: Game & {
-        nextAction: NextStep;
-    };
+    game: GameState;
     extraRules: string[];
 };
 
 type StartGameCommand = {
-    game: Game & {
-        nextAction: NextStep;
-    };
+    game: GameState;
 };
 
 type ChooseDominoCommand = {
-    game: GameWithNextAction;
+    game: GameState;
     dominoPick: number;
     lordId: string;
 };
 
 type PlaceDominoCommand = {
-    game: GameWithNextAction;
+    game: GameState;
     lordId: string;
     position: Position;
     orientation: Orientation;
@@ -175,12 +166,12 @@ type PlaceDominoCommand = {
 };
 
 type DiscardDominoCommand = {
-    game: GameWithNextAction;
+    game: GameState;
     lordId: string;
 };
 
 type GetResultCommand = {
-    game: GameWithNextStep;
+    game: GameState;
 };
 
 type GameEngine = {
@@ -191,34 +182,19 @@ type GameEngine = {
     addExtraRules: (command: AddExtraRulesCommand) => GameWithNextStep;
     startGame: (command: StartGameCommand) => GameWithNextAction;
     chooseDomino: (command: ChooseDominoCommand) => GameWithNextAction;
-    placeDomino: (command: PlaceDominoCommand) => GameWithNextAction | GameWithNextStep;
-    discardDomino: (command: DiscardDominoCommand) => GameWithNextAction | GameWithNextStep;
+    placeDomino: (command: PlaceDominoCommand) => GameState;
+    discardDomino: (command: DiscardDominoCommand) => GameState;
     getResults: (command: GetResultCommand) => GameWithResults;
 };
 
-type DominoesRepository = {
-    getForMode: (mode: GameMode) => Domino[] | [];
-};
-
-type ModeRepository = {
-    getAvailables: () => GameMode[];
-};
-
-type RuleRepository = {
-    getAll: () => Rules;
-    getAllExtra: () => ExtraRule[];
-};
-
 type ShuffleMethod = <T>(array: T[]) => T[];
 
 type UuidMethod = () => string;
 
 type EngineConfig = {
-    modeRepository?: ModeRepository;
-    dominoesRepository?: DominoesRepository;
-    ruleRepository?: RuleRepository;
     uuidMethod?: UuidMethod;
     shuffleMethod?: ShuffleMethod;
+    logging?: boolean;
 };
 
 declare const createGameEngine: (config: Partial<EngineConfig>) => GameEngine;