@pompidup/kingdomino-engine 2.0.1 → 2.0.5

package/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-This is under development. The goal is to create 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.
+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.
 
 ## Requirements
 
@@ -13,94 +13,227 @@ This is under development. The goal is to create a simple and lightweight TypeSc
 - **Game State Management**: Efficiently manage game states, including player turns, game rules, and game progression.
 - **Rule Enforcement**: Automatically enforce game rules, ensuring a fair and consistent gameplay experience.
 - **Player Interaction**: Simplify player interactions, including drawing tiles, placing dominoes, and scoring.
+- **Extra Rules Support**: Implement and manage additional game rules for enhanced gameplay.
+- **Multiple Game Modes**: Support for different game modes, including Classic and potentially others.
 
 ## Installation
 
-To install the Kingdomino Engine, you can use npm, yarn or pnpm. Run the following command in your terminal:
+To install the Kingdomino Engine, you can use npm, yarn or pnpm. Run one of the following commands in your terminal:
 
 ```bash
 npm install @pompidup/kingdomino-engine
-```
-
-or
-
-```bash
 yarn add @pompidup/kingdomino-engine
-```
-
-or
-
-```bash
 pnpm add @pompidup/kingdomino-engine
 ```
 
 ## Usage
 
-The Kingdomino Engine is designed to be easy to use and integrate into any application. Below are some examples of how you can use the engine to create a new game, add players, and start playing.
+The Kingdomino Engine is designed to be easy to use and integrate into any application. Below are examples of how you can use the engine to create a new game, add players, set rules, and manage gameplay.
 
-Each method returns an updated game state object, which contains the current state of the game, including the board, players, and dominoes. In return you will receive too the nextLord (the next player to play) and the nextAction (the next action to be performed by the next player).
+Each method returns an updated game state object, which contains the current state of the game, including the board, players, and dominoes. You will also receive the nextLord (the next player to play) and the nextAction (the next action to be performed by the next player).
 
 **It's your responsibility to save and pass the updated game state to the next method call.**
 
 ### Basic Setup
 
-To start using the Kingdomino Engine, you need to import it and initialize a new game instance.
+To start using the Kingdomino Engine, import it and initialize a new game instance:
 
 ```typescript
 import gameEngine from "@pompidup/kingdomino-engine";
 
 const engine = gameEngine();
-let gameState = engine.init();
+let gameState = engine.createGame({ mode: "Classic" });
+
 ```
 
-### Start game and setting up players
+### Adding Players
 
-You can add players to the game by passing an array of player.
+Add players to the game by passing an array of player names:
 
 ```typescript
-const players = [{ name: "Player  1" }, { name: "Player  2" }];
-gameState = engine.start(gameState, players);
+gameState = engine.addPlayers(gameState, ["Player 1", "Player 2", "Player 3"]);
 ```
 
-### Choosing game mode (Classic, Queendomino...)
+### Setting Up Extra Rules
 
-Incoming...
+You can get available extra rules and add them to the game:
 
-### Setting Up Rules
+```typescript
+const extraRules = engine.getExtraRules({ mode: "Classic", players: 2 });
+gameState = engine.addExtraRules({
+game: gameState,
+extraRules: ["The middle Kingdom"],
+});
+```
+
+### Starting the Game
+
+After setting up players and rules, start the game:
+
+```typescript
+gameState = engine.startGame({ game: gameState });
+```
 
-Incoming...
 
 ### Player Actions
 
-Players can perform actions like pick domino, placing domino, and passing turns.
+Players can perform actions like picking a domino, placing a domino, and discarding a domino.
 
 - Pick Domino:
-  You can pick a domino by passing the lordId and the number of the domino you want to pick.
 
 ```typescript
-gameState = engine.pickDomino(gameState, "lordId", 12);
+gameState = engine.chooseDomino({
+  game: gameState,
+  lordId: "lordId",
+  dominoPick: 12
+});
 ```
 
 - Place Domino:
-  You can place a domino by passing the lordId, the position where you want to place the domino, the orientation (horizontal or vertical), and the rotation (if you want to switch left and right tile you can pass 180 else 0).
 
 ```typescript
-gameState = engine.placeDomino(
-  gameState,
-  "lordId",
-  { x: 0, y: 0 },
-  "horizontal",
-  0
-);
+gameState = engine.placeDomino({
+  game: gameState,
+  lordId: "lordId",
+  position: { x: 0, y: 0 },
+  orientation: "horizontal",
+  rotation: 0
+});
 ```
 
-- Pass Turn:
-  If you can not place a domino you can pass your turn.
+- Discard Domino:
 
 ```typescript
-gameState = engine.passTurn(gameState, "lordId");
+gameState = engine.discardDomino({
+  game: gameState,
+  lordId: "lordId",
+});
 ```
 
+
+### 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").
+
 ### Scoring
 
-When last turn is played, you will received the final score of each player and their position.
+When the last turn is played, the game will automatically calculate and provide the final score for each player and their position.
+
+## Extra Rules
+
+The engine supports extra rules that can modify gameplay. Some examples include:
+
+- **The Middle Kingdom**: Gain 10 additional points if your castle is in the middle of the kingdom.
+- **Harmony**: Gain 5 additional points if your kingdom is complete (no discarded dominoes).
+
+## API Documentation
+
+### Key Types and Interfaces
+
+#### GameEngine
+
+The main interface for interacting with the Kingdomino engine.
+
+```typescript
+type GameEngine = {
+  getModes: (command: GetModesCommand) => GameMode[];
+  getExtraRules: (command: GetExtraRulesCommand) => ExtraRule[];
+  createGame: (command: CreateGameCommand) => GameWithNextStep;
+  addPlayers: (command: AddPlayersCommand) => GameWithNextStep;
+  addExtraRules: (command: AddExtraRulesCommand) => GameWithNextStep;
+  startGame: (command: StartGameCommand) => GameWithNextAction;
+  chooseDomino: (command: ChooseDominoCommand) => GameWithNextAction;
+  placeDomino: (command: PlaceDominoCommand) => GameWithNextAction | GameWithNextStep;
+  discardDomino: (command: DiscardDominoCommand) => GameWithNextAction | GameWithNextStep;
+  getResults: (command: GetResultCommand) => GameWithResults;
+};
+```
+
+
+#### Game
+
+Represents the current state of a Kingdomino game.
+
+```typescript
+type Game = {
+  id: string;
+  dominoes: Domino[];
+  currentDominoes: RevealedDomino[];
+  players: Player[];
+  lords: Lord[];
+  turn: number;
+  rules: SelectedRules;
+  mode: GameMode;
+};
+```
+
+
+#### NextStep and NextAction
+
+Represent the next step or action in the game flow.
+
+```typescript
+type NextStep = {
+  type: "step";
+  step: "addPlayers" | "options" | "start" | "result";
+};
+type NextAction = {
+  type: "action";
+  nextLord: string;
+  nextAction: "pickDomino" | "placeDomino";
+};
+```
+
+
+#### ExtraRule
+
+Represents an additional rule that can be applied to the game.
+
+```typescript
+type ExtraRule = {
+  name: string;
+  description: string;
+  mode: GameMode[];
+  playersLimit?: number;
+};
+```
+
+
+### Methods
+
+#### createGame(command: CreateGameCommand): GameWithNextStep
+
+Creates a new game with the specified game mode.
+
+#### addPlayers(command: AddPlayersCommand): GameWithNextStep
+
+Adds players to the game.
+
+#### addExtraRules(command: AddExtraRulesCommand): GameWithNextStep
+
+Adds extra rules to the game.
+
+#### startGame(command: StartGameCommand): GameWithNextAction
+
+Starts the game, setting up the initial game state.
+
+#### chooseDomino(command: ChooseDominoCommand): GameWithNextAction
+
+Allows a player to choose a domino.
+
+#### placeDomino(command: PlaceDominoCommand): GameWithNextAction | GameWithNextStep
+
+Allows a player to place a domino on their kingdom.
+
+#### discardDomino(command: DiscardDominoCommand): GameWithNextAction | GameWithNextStep
+
+Allows a player to discard a domino if they cannot place it.
+
+#### getResults(command: GetResultCommand): GameWithResults
+
+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

@@ -1,8 +1,3 @@
-type GameMode = {
-    name: string;
-    description: string;
-};
-
 declare const GROUND: readonly ["castle", "wheat", "forest", "sea", "plain", "swamp", "mine"];
 type Ground = (typeof GROUND)[number];
 type EmptyGround = "empty";
@@ -27,6 +22,14 @@ type RevealsDomino = {
     position: number;
 };
 
+type Position = {
+    x: number;
+    y: number;
+};
+type Orientation = "vertical" | "horizontal";
+type Rotation = 0 | 180;
+type Kingdom = (Tile | EmptyTile)[][];
+
 type Lord = {
     id: string;
     playerId: string;
@@ -36,13 +39,10 @@ type Lord = {
     dominoPicked?: Domino;
 };
 
-type Position = {
-    x: number;
-    y: number;
+type GameMode = {
+    name: string;
+    description: string;
 };
-type Orientation = "vertical" | "horizontal";
-type Rotation = 0 | 180;
-type Kingdom = (Tile | EmptyTile)[][];
 
 type ObjectValues<T> = T[keyof T];
 
@@ -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,32 +182,16 @@ 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;
 };