From 6d4db9f12b7577a77797b4169a2e2b5659f3d515 Mon Sep 17 00:00:00 2001 From: Arne Keller Date: Fri, 13 Mar 2020 09:30:26 +0100 Subject: [PATCH] Javadoc + allow various command during game end phase --- .../kit/informatik/cardgame/model/Card.java | 7 ++ .../cardgame/model/CardCategory.java | 16 ++++ .../informatik/cardgame/model/CardGame.java | 90 +++++++++++++++++-- .../kit/informatik/cardgame/model/Item.java | 7 ++ .../cardgame/model/ItemCategory.java | 13 +++ 5 files changed, 124 insertions(+), 9 deletions(-) diff --git a/src/edu/kit/informatik/cardgame/model/Card.java b/src/edu/kit/informatik/cardgame/model/Card.java index 4aac4f1..b54e26b 100644 --- a/src/edu/kit/informatik/cardgame/model/Card.java +++ b/src/edu/kit/informatik/cardgame/model/Card.java @@ -1,5 +1,12 @@ package edu.kit.informatik.cardgame.model; +/** + * Game card. + * + * @see CardCategory + * @author Arne Keller + * @version 1.0 + */ public enum Card { /** * Wood. Basic resource. diff --git a/src/edu/kit/informatik/cardgame/model/CardCategory.java b/src/edu/kit/informatik/cardgame/model/CardCategory.java index 9605652..4f896d4 100644 --- a/src/edu/kit/informatik/cardgame/model/CardCategory.java +++ b/src/edu/kit/informatik/cardgame/model/CardCategory.java @@ -1,7 +1,23 @@ package edu.kit.informatik.cardgame.model; +/** + * Card category. Game cards are categorized into three categories depending on their properties. + * + * @see Card + * @author Arne Keller + * @version 1.0 + */ public enum CardCategory { + /** + * Basic resource card, harmless. + */ RESOURCE, + /** + * Animal card, can attack player. + */ ANIMAL, + /** + * Catastrophic card, can not harm player. + */ CATASTROPHE } diff --git a/src/edu/kit/informatik/cardgame/model/CardGame.java b/src/edu/kit/informatik/cardgame/model/CardGame.java index 13cbb37..4923731 100644 --- a/src/edu/kit/informatik/cardgame/model/CardGame.java +++ b/src/edu/kit/informatik/cardgame/model/CardGame.java @@ -21,6 +21,7 @@ public class CardGame { /** * Start a new game with the specified stack of cards. + * * @param cardStack stack of cards to use, where the first element is the first to take * @throws LogicException if card stack has wrong distribution of cards * @return whether the game could be successfully started @@ -38,6 +39,13 @@ public class CardGame { return true; } + /** + * Draw a new card. Will automatically add the card to the players resources, start an encounter or let the + * thunderstorm do its work. + * + * @return the card + * @throws LogicException if no card to draw exists or phase is not scavenge + */ public Card draw() throws LogicException { if (currentCardStack == null || currentCardStack.isEmpty()) { throw new LogicException("no card to draw exists"); @@ -65,6 +73,14 @@ public class CardGame { return card; } + /** + * Roll a dice with the specified size and result. + * + * @param size dice size + * @param roll dice result + * @return result of the throw (survived, lose or win) + * @throws LogicException if not expecting dice roll or dice roll is invalid + */ public String rollDice(int size, int roll) throws LogicException { if (phase != Phase.ENDEAVOR && phase != Phase.ENCOUNTER) { throw new LogicException("not expecting dice roll"); @@ -100,13 +116,20 @@ public class CardGame { } } - public void clearResources() { + private void clearResources() { final int keepLastResources = items.stream().mapToInt(Item::itemsSecured).sum(); while (resources.size() > keepLastResources) { resources.removeFirst(); } } + /** + * Attempt to build the specified item. + * + * @param item item to build + * @return building result (OK or win), or null if item can not be built + * @throws LogicException if in wrong phase or item already built + */ public String build(Item item) throws LogicException { if (item == null) { throw new LogicException("can not build item"); @@ -134,7 +157,7 @@ public class CardGame { return "win"; } break; - case DEFAULT: + default: checkLost(); break; @@ -174,39 +197,65 @@ public class CardGame { private void checkLost() { if (phase != Phase.LOST + // can not draw new cards && currentCardStack != null && currentCardStack.isEmpty() + // can not roll dice && phase != Phase.ENCOUNTER && phase != Phase.ENDEAVOR - && !Arrays.stream(Item.values()).anyMatch(this::canBuild)) { + // can not build item + && Arrays.stream(Item.values()).noneMatch(this::canBuild)) { endGame(); phase = Phase.LOST; } } + /** + * Check whether the active game is lost. The game is lost if no cards to draw exist and no further actions are + * possible. + * + * @return whether the active game is lost + */ public boolean gameLost() { return phase == Phase.LOST; } + /** + * Get the resources available for building. + * + * @return resources available + * @throws LogicException if no game is active + */ public Deque getResources() throws LogicException { - if (!gameActive()) { + if (!gameStarted()) { throw new LogicException("can not get resources: game not started"); } // do not allow caller to modify internal queue return new ArrayDeque<>(resources); } + /** + * Get the items already built. + * + * @return items owned by the player + * @throws LogicException if no game is active + */ public List getItems() throws LogicException { - if (!gameActive()) { + if (!gameStarted()) { throw new LogicException("can not get buildings: game not started"); } - // do not allow caller to modify internal list + // have to copy here: caller does not expect an auto-updating list return new ArrayList<>(items); } + /** + * Get the currently buildable items. + * + * @return set of items currently buildable + * @throws LogicException if game not in scavenge phase + */ public Set getBuildableItems() throws LogicException { - if (!gameActive()) { + if (!gameStarted()) { throw new LogicException("can not get buildable items: game not started"); - } - if (phase != Phase.SCAVENGE) { + } else if (phase != Phase.SCAVENGE) { throw new LogicException("can not get buildable items: awaiting dice roll"); } return Arrays.stream(Item.values()).filter(this::canBuild).collect(Collectors.toSet()); @@ -216,6 +265,11 @@ public class CardGame { currentCardStack = null; } + /** + * Reset the game, restoring the original card stack. + * + * @throws LogicException if game was never started + */ public void reset() throws LogicException { if (cardStack == null) { throw new LogicException("can not reset a game that is not started!"); @@ -229,11 +283,29 @@ public class CardGame { this.phase = Phase.SCAVENGE; } + /** + * Game phase. + */ enum Phase { + /** + * Player can draw cards and build. + */ SCAVENGE, + /** + * Player has to fight an animal. + */ ENCOUNTER, + /** + * Player is attempting to escape. + */ ENDEAVOR, + /** + * Player won. + */ WON, + /** + * Player lost. + */ LOST } } diff --git a/src/edu/kit/informatik/cardgame/model/Item.java b/src/edu/kit/informatik/cardgame/model/Item.java index 879302c..8b85bec 100644 --- a/src/edu/kit/informatik/cardgame/model/Item.java +++ b/src/edu/kit/informatik/cardgame/model/Item.java @@ -8,6 +8,13 @@ import static edu.kit.informatik.cardgame.model.Card.METAL; import static edu.kit.informatik.cardgame.model.Card.PLASTIC; import static edu.kit.informatik.cardgame.model.Card.WOOD; +/** + * Game item. + * + * @see ItemCategory + * @author Arne Keller + * @version 1.0 + */ public enum Item { /** * Axe. Provides an attack bonus of two. diff --git a/src/edu/kit/informatik/cardgame/model/ItemCategory.java b/src/edu/kit/informatik/cardgame/model/ItemCategory.java index d921a53..c6a5526 100644 --- a/src/edu/kit/informatik/cardgame/model/ItemCategory.java +++ b/src/edu/kit/informatik/cardgame/model/ItemCategory.java @@ -1,6 +1,19 @@ package edu.kit.informatik.cardgame.model; +/** + * Item category. Game items are categorized into two categories: normal items and items used to escape. + * + * @see Item + * @author Arne Keller + * @version 1.0 + */ public enum ItemCategory { + /** + * Normal item, can not be used to escape. + */ DEFAULT, + /** + * Item that can be used to escape. + */ ESCAPE; }