diff --git a/src/edu/kit/informatik/cardgame/model/Card.java b/src/edu/kit/informatik/cardgame/model/Card.java index 76dd84f..d19ccdf 100644 --- a/src/edu/kit/informatik/cardgame/model/Card.java +++ b/src/edu/kit/informatik/cardgame/model/Card.java @@ -90,7 +90,7 @@ public enum Card implements RequireDice { } /** - * Get the number of cards of this type needed in a stack. + * Get the number of cards of this type needed to {@link CardGame#start start} a game. * * @return amount of cards needed in a card deck */ diff --git a/src/edu/kit/informatik/cardgame/model/CardCategory.java b/src/edu/kit/informatik/cardgame/model/CardCategory.java index 4f896d4..e03a912 100644 --- a/src/edu/kit/informatik/cardgame/model/CardCategory.java +++ b/src/edu/kit/informatik/cardgame/model/CardCategory.java @@ -1,23 +1,32 @@ package edu.kit.informatik.cardgame.model; /** - * Card category. Game cards are categorized into three categories depending on their properties. + * Card category. {@link Card 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. + * + * @see Card#WOOD + * @see Card#METAL + * @see Card#PLASTIC */ RESOURCE, /** * Animal card, can attack player. + * + * @see Card#SNAKE + * @see Card#SPIDER + * @see Card#TIGER */ ANIMAL, /** * Catastrophic card, can not harm player. + * + * @see Card#THUNDERSTORM */ CATASTROPHE } diff --git a/src/edu/kit/informatik/cardgame/model/CardGame.java b/src/edu/kit/informatik/cardgame/model/CardGame.java index 9c991ff..47c0ac4 100644 --- a/src/edu/kit/informatik/cardgame/model/CardGame.java +++ b/src/edu/kit/informatik/cardgame/model/CardGame.java @@ -1,6 +1,7 @@ package edu.kit.informatik.cardgame.model; import java.util.Arrays; +import java.util.Collection; import java.util.Collections; import java.util.Deque; import java.util.List; @@ -8,7 +9,15 @@ import java.util.Set; import java.util.stream.Collectors; /** - * Card game. + * Card game. Features: + * * * @author Arne Keller * @version 1.0 @@ -27,7 +36,7 @@ public class CardGame { */ private Phase phase; /** - * Object currently requiring dice roll. + * Object currently requiring dice roll, null if not awaiting dice roll. */ private RequireDice requireDice; @@ -61,16 +70,16 @@ public class CardGame { */ public Card draw() throws LogicException { if (cardStack == null) { - throw new LogicException("no card to draw exists"); + throw new LogicException("no card stack to draw from exists"); } else if (phase != Phase.SCAVENGE) { throw new LogicException("can only draw cards in scavenge phase"); } final Card card = cardStack.draw().orElseThrow(() -> new LogicException("no card to draw exists")); switch (card.category()) { - case RESOURCE: + case RESOURCE: // simply add resource cards to the player's inventory inventory.addResource(card); break; - case ANIMAL: + case ANIMAL: // animal cards trigger an encounter requireDice = card; phase = Phase.ENCOUNTER; break; @@ -97,8 +106,8 @@ public class CardGame { if (requireDice == null) { throw new LogicException("not expecting dice roll"); } - int sizeNeeded = requireDice.diceSizeNeeded().get(); - int minimumNeeded = requireDice.minimumDiceRollNeeded().get(); + final int sizeNeeded = requireDice.diceSizeNeeded().get(); + final int minimumNeeded = requireDice.minimumDiceRollNeeded().get(); if (sizeNeeded != size) { throw new LogicException("unexpected dice size"); } else if (roll > sizeNeeded || roll < 1) { @@ -106,6 +115,7 @@ public class CardGame { } requireDice = null; if (phase == Phase.ENCOUNTER) { + // calculate fighting bonus, selecting the most powerful item the player owns final int bonus = inventory.itemStream().mapToInt(Item::fightingBonus).max().orElse(0); phase = Phase.SCAVENGE; checkLost(); @@ -138,31 +148,26 @@ public class CardGame { */ public String build(Item item) throws LogicException { if (item == null) { - throw new LogicException("can not build item"); + throw new LogicException("can not build null item"); } else if (phase != Phase.SCAVENGE) { throw new LogicException("can only build in scavenge phase"); } else if (inventory.contains(item)) { throw new LogicException("already built"); } else if (inventory.canBuild(item)) { inventory.build(item); - switch (item.category()) { - case ESCAPE: - if (item.diceSizeNeeded().isPresent()) { - // player needs to roll dice to escape - requireDice = item; - phase = Phase.ENDEAVOR; - } else { - // player won - endGame(); - phase = Phase.WON; - return "win"; - } - break; - default: - checkLost(); - break; - + if (item.category() == ItemCategory.ESCAPE) { + if (item.diceSizeNeeded().isPresent()) { + // player needs to roll dice to escape + requireDice = item; + phase = Phase.ENDEAVOR; + } else { + // player won + endGame(); + phase = Phase.WON; + return "win"; + } } + checkLost(); return "OK"; } else { return null; @@ -216,7 +221,7 @@ public class CardGame { * @return resources available * @throws LogicException if no game is active */ - public Deque getResources() throws LogicException { + public Collection getResources() throws LogicException { if (!gameStarted()) { throw new LogicException("can not get resources: game not started"); } diff --git a/src/edu/kit/informatik/cardgame/model/CardStack.java b/src/edu/kit/informatik/cardgame/model/CardStack.java index 90fa38b..1351971 100644 --- a/src/edu/kit/informatik/cardgame/model/CardStack.java +++ b/src/edu/kit/informatik/cardgame/model/CardStack.java @@ -4,6 +4,12 @@ import java.util.ArrayDeque; import java.util.Deque; import java.util.Optional; +/** + * Simple card stack that remembers its initial state and can be {@link #reset} on demand. + * + * @author Arne Keller + * @version 1.0 + */ public class CardStack { /** * Copy of the card stack used to initialize the stack. @@ -14,24 +20,44 @@ public class CardStack { */ private Deque activeStack; + /** + * Construct a new card stack with the specified card collection. + * The first element will be {@link #draw drawn} first. + * + * @param cards card stack + */ public CardStack(Deque cards) { // copy stack to avoid modifications this.stack = new ArrayDeque<>(cards); reset(); } + /** + * Draw the next card. + * + * @return the card (empty if stack is empty) + */ public Optional draw() { return Optional.ofNullable(activeStack.pollFirst()); } + /** + * Clear the currently active stack. + */ public void clearActiveStack() { activeStack.clear(); } + /** + * Reset the currently active stack. + */ public void reset() { activeStack = new ArrayDeque<>(stack); } + /** + * @return whether the active card stack is empty + */ public boolean isEmpty() { return activeStack.isEmpty(); } diff --git a/src/edu/kit/informatik/cardgame/model/Inventory.java b/src/edu/kit/informatik/cardgame/model/Inventory.java index d457848..05bc6b2 100644 --- a/src/edu/kit/informatik/cardgame/model/Inventory.java +++ b/src/edu/kit/informatik/cardgame/model/Inventory.java @@ -17,6 +17,9 @@ public class Inventory { resources.add(resourceCard); } + /** + * @return resources owned by the player + */ public Deque getResources() { // have to copy here: caller does not expect an auto-updating collection return new ArrayDeque<>(resources); diff --git a/src/edu/kit/informatik/cardgame/model/Item.java b/src/edu/kit/informatik/cardgame/model/Item.java index 56b603d..61179a8 100644 --- a/src/edu/kit/informatik/cardgame/model/Item.java +++ b/src/edu/kit/informatik/cardgame/model/Item.java @@ -9,27 +9,26 @@ import static edu.kit.informatik.cardgame.model.Card.PLASTIC; import static edu.kit.informatik.cardgame.model.Card.WOOD; /** - * Game item. + * Game item that can be built by the player. Categorized into several {@link ItemCategory categories}. * - * @see ItemCategory * @author Arne Keller * @version 1.0 */ public enum Item implements RequireDice { /** - * Axe. Provides an attack bonus of two. + * Axe. Provides an {@link #fightingBonus attack bonus} of two. */ AXE, /** - * Club. Provides an attack bonus of one. + * Club. Provides an {@link #fightingBonus attack bonus} of one. */ CLUB, /** - * Shack. Can save the last five items in case of animal attacks or catastrophic events. + * Shack. Can {@link #itemsSecured save} the last five items in case of animal attacks or catastrophic events. */ SHACK, /** - * Fireplace. Required for some advanced items. + * Fireplace. {@link #itemsNeededToBuild Required} for some advanced items. */ FIREPLACE, /** @@ -51,7 +50,7 @@ public enum Item implements RequireDice { BALLON; /** - * Resources needed to build this item, in no particular order. + * Get the resources needed to build this item, in no particular order. * * @return resources needed to build this item */ diff --git a/src/edu/kit/informatik/cardgame/model/ItemCategory.java b/src/edu/kit/informatik/cardgame/model/ItemCategory.java index c6a5526..d244a39 100644 --- a/src/edu/kit/informatik/cardgame/model/ItemCategory.java +++ b/src/edu/kit/informatik/cardgame/model/ItemCategory.java @@ -1,19 +1,28 @@ package edu.kit.informatik.cardgame.model; /** - * Item category. Game items are categorized into two categories: normal items and items used to escape. + * Item category. {@link Item 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. + * + * @see Item#AXE + * @see Item#CLUB + * @see Item#SHACK + * @see Item#FIREPLACE */ DEFAULT, /** * Item that can be used to escape. + * + * @see Item#SAILING_RAFT + * @see Item#HANG_GLIDER + * @see Item#STEAMBOAT + * @see Item#BALLON */ ESCAPE; } diff --git a/src/edu/kit/informatik/cardgame/model/LogicException.java b/src/edu/kit/informatik/cardgame/model/LogicException.java index d6d1736..cead230 100644 --- a/src/edu/kit/informatik/cardgame/model/LogicException.java +++ b/src/edu/kit/informatik/cardgame/model/LogicException.java @@ -1,7 +1,7 @@ package edu.kit.informatik.cardgame.model; /** - * Thrown on semantically invalid user input. + * Thrown on semantically invalid user input, usually in the {@link CardGame game}. * * @author Arne Keller * @version 1.0 diff --git a/src/edu/kit/informatik/cardgame/model/RequireDice.java b/src/edu/kit/informatik/cardgame/model/RequireDice.java index 80d7c5f..256cb89 100644 --- a/src/edu/kit/informatik/cardgame/model/RequireDice.java +++ b/src/edu/kit/informatik/cardgame/model/RequireDice.java @@ -16,7 +16,6 @@ public interface RequireDice { */ Optional diceSizeNeeded(); - /** * Get the minimum dice roll needed to activate this object. * diff --git a/src/edu/kit/informatik/cardgame/ui/InvalidInputException.java b/src/edu/kit/informatik/cardgame/ui/InvalidInputException.java index 18458d6..4739408 100644 --- a/src/edu/kit/informatik/cardgame/ui/InvalidInputException.java +++ b/src/edu/kit/informatik/cardgame/ui/InvalidInputException.java @@ -1,7 +1,9 @@ package edu.kit.informatik.cardgame.ui; +import edu.kit.informatik.cardgame.ui.command.Command; + /** - * Thrown on syntactically invalid user input. + * Thrown on syntactically invalid user input, usually in the {@link Command#parse command parsers}. * * @author Arne Keller * @version 1.0 diff --git a/src/edu/kit/informatik/cardgame/ui/command/ListBuildings.java b/src/edu/kit/informatik/cardgame/ui/command/ListBuildings.java index 72bcaa5..55cfdc9 100644 --- a/src/edu/kit/informatik/cardgame/ui/command/ListBuildings.java +++ b/src/edu/kit/informatik/cardgame/ui/command/ListBuildings.java @@ -22,7 +22,7 @@ public final class ListBuildings extends Command { @Override public void apply(CardGame game) throws LogicException { - List items = game.getItems(); + final List items = game.getItems(); if (items.isEmpty()) { Terminal.printLine("EMPTY"); } else { diff --git a/src/edu/kit/informatik/cardgame/ui/command/ListResources.java b/src/edu/kit/informatik/cardgame/ui/command/ListResources.java index 2c653aa..77dd16f 100644 --- a/src/edu/kit/informatik/cardgame/ui/command/ListResources.java +++ b/src/edu/kit/informatik/cardgame/ui/command/ListResources.java @@ -6,7 +6,7 @@ import edu.kit.informatik.cardgame.model.CardGame; import edu.kit.informatik.cardgame.model.LogicException; import edu.kit.informatik.cardgame.ui.InvalidInputException; -import java.util.Deque; +import java.util.Collection; /** * list-resources command. Prints all of the {@link Card resources} collected by the player, @@ -23,7 +23,7 @@ public final class ListResources extends Command { @Override public void apply(CardGame game) throws LogicException { - final Deque resources = game.getResources(); + final Collection resources = game.getResources(); if (resources.isEmpty()) { Terminal.printLine("EMPTY"); } else {