Package: Game

Game

Coverage

1: /*
2: * Copyright © 2020-2023 Fachhochschule für die Wirtschaft (FHDW) Hannover
3: *
4: * This file is part of gaming-core.
5: *
6: * Gaming-core is free software: you can redistribute it and/or modify it under
7: * the terms of the GNU General Public License as published by the Free Software
8: * Foundation, either version 3 of the License, or (at your option) any later
9: * version.
10: *
11: * Gaming-core is distributed in the hope that it will be useful, but WITHOUT
12: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
13: * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
14: * details.
15: *
16: * You should have received a copy of the GNU General Public License along with
17: * gaming-core. If not, see <http://www.gnu.org/licenses/>.
18: */
19: package de.fhdw.gaming.core.domain;
20:
21: import java.util.Map;
22: import java.util.Optional;
23:
24: /**
25: * Represents a game.
26: *
27: * @param <P> The type of game players.
28: * @param <S> The type of game states.
29: * @param <M> The type of game moves.
30: * @param <ST> The type of game strategies.
31: */
32: public interface Game<P extends Player<P>, S extends State<P, S>, M extends Move<P, S>, ST extends Strategy<P, S, M>>
33: extends AutoCloseable {
34:
35: /**
36: * Returns an integer value that uniquely identifies this game.
37: */
38: int getId();
39:
40: /**
41: * Returns all the players of the game.
42: */
43: Map<String, P> getPlayers();
44:
45: /**
46: * Returns all the players' strategies.
47: */
48: Map<String, ST> getStrategies();
49:
50: /**
51: * Returns a copy of the game state.
52: */
53: S getState();
54:
55: /**
56: * Adds an observer.
57: *
58: * @param observer The observer to add.
59: */
60: void addObserver(Observer observer);
61:
62: /**
63: * Removes an observer.
64: *
65: * @param observer The observer to remove.
66: */
67: void removeObserver(Observer observer);
68:
69: /**
70: * Starts the game.
71: *
72: * @throws InterruptedException if starting the game has been interrupted.
73: */
74: void start() throws InterruptedException;
75:
76: /**
77: * Makes a single move. This means:
78: * <ul>
79: * <li>The set of all players being able to make a move is determined. If this set is empty, the game is over.</li>
80: * <li>The strategies of all these players are requested to choose a move.</li>
81: * <li>The first such move is applied to the game state (if possible, as the move may be illegal).</li>
82: * <li>The game state is checked whether the game is over. This is typically the case if:
83: * <ul>
84: * <li>One or more players have won the game; or</li>
85: * <li>All players have lost the game; or</li>
86: * <li>All but one player have lost the game. In that case the remaining player has won the game.</li>
87: * </ul>
88: * </li>
89: * </ul>
90: * <p>
91: * If some player's strategy returns {@code null} or an illegal move, this player loses the game immediately.
92: * <p>
93: * The following events are possibly emitted:
94: * <ul>
95: * <li>{@link Observer#nextPlayersComputed(Game, State, java.util.Set)}</li>
96: * <li>{@link Observer#illegalPlayerRejected(Game, State, Player)}</li>
97: * <li>{@link Observer#legalMoveApplied(Game, State, Player, Move)}</li>
98: * <li>{@link Observer#illegalMoveRejected(Game, State, Player, Optional, String)}</li>
99: * <li>{@link Observer#playerOvertaken(Game, State, Player, Player)}</li>
100: * <li>{@link Observer#finished(Game, State)}</li>
101: * </ul>
102: *
103: * @throws IllegalStateException if the game is already over.
104: * @throws InterruptedException if choosing and applying a move has been interrupted.
105: */
106: void makeMove() throws InterruptedException;
107:
108: /**
109: * Tries to abort the game by invoking {@link Strategy#abortRequested(int)} on all players' strategies.
110: */
111: void abortRequested();
112:
113: /**
114: * Chooses a random but valid move. Used when a strategy does not return a move in the given time window.
115: *
116: * @param player The player to choose the move for.
117: * @param stateCopy The game state. This is a copy of the game state.
118: * @return A valid move. Can be empty if no valid move is available (e.g. because some player has already won the
119: * game).
120: */
121: Optional<M> chooseRandomMove(P player, S stateCopy);
122:
123: /**
124: * Determines whether the game has been started.
125: *
126: * @return {@code true} if the game has been started, {@code false} otherwise.
127: */
128: boolean isStarted();
129:
130: /**
131: * Determines whether the game is over.
132: *
133: * @return {@code true} if the game is over, {@code false} otherwise.
134: */
135: boolean isFinished();
136:
137: @Override
138: void close();
139:
140: }