Kulatro

A round-based card game written in Java with a Swing GUI. The game logic is fully independent of the GUI; all randomness uses java.security.SecureRandom no external libraries are used.

---

Requirements

• A JDK, Java 17 or later (developed and tested on JDK 21). java and javac must be on your PATH.
• Windows is assumed for the helper scripts (PowerShell). Plain javac/java commands are given below for any platform.

---

Compile & Run

Recommended (Windows / PowerShell)

From the project root:

powershell -NoProfile -File .\run.ps1

This compiles every source file under src/ into bin/ and launches the game (com.kulatro.Main).

Manual (any platform)

PowerShell:

$files = Get-ChildItem -Recurse src -Filter *.java | ForEach-Object { $_.FullName }
New-Item -ItemType Directory -Force bin | Out-Null
javac -d bin $files
java -cp bin com.kulatro.Main

Windows cmd:

dir /s /b src\*.java > sources.txt
javac -d bin @sources.txt
java -cp bin com.kulatro.Main

Linux/macOS:

mkdir -p bin
find src -name '*.java' > sources.txt
javac -d bin @sources.txt
java -cp bin com.kulatro.Main

The game reads decks/ and assets/ and writes log.txt, saves/, and data/users.txt relative to the current working directory, so always run it from the project root.

Run the test suite

A hand-rolled test harness (no external test framework) covers the engine, scoring, special effects, persistence, and the GUI controller:

powershell -NoProfile -File .\selftest.ps1

It prints TOTAL passed=<N> failed=0 and exits 0 when everything passes.

Generate Javadoc

powershell -NoProfile -File .\gen-docs.ps1

Open the generated docs/api/index.html in a browser.

---

How to Play

1. Login

• On first launch, type a username and password and click Create Account.
• Returning players click Log In.
• Usernames/session names must be 1–40 characters with no spaces or the characters | ; : / \.

2. Main Menu

• The leaderboard lists every registered user, their most-recent game's accumulated score, status (Ongoing/Finished) and result (WON/LOST). The top 3 players by score show a gold / silver / bronze medal.
• New Game — choose a deck style (Alchemy / Element / Quantum), a difficulty (Easy / Medium / Hard) and a session name, then pick one starting special card to keep in a persistent slot.
• Continue — pick a saved session from the dropdown and resume it.

3. The Game (4 rounds)

Each round you hold up to 4 cards and must reach the round's target score.

• Click a number card to select / deselect it (selected cards get a gold border).
• Click a special card in your hand, or the Play Special button (for the persistent slot special), to use its effect. Interactive specials (e.g. Photon Burst) prompt you for the required choice.
• Right-click a special card to read its description.
• Discard — discard the selected cards and draw replacements. Limited to 4 per round and 6 in total across the game (the button disables when a limit is reached).
• Submit — score the current hand and advance to the next round.
• Save — save the game to saves/<session>.txt.
• Main Menu — return to the menu (unsaved progress is lost).

The side panel always shows the round (x / 4), round target, total score, deck name, cards remaining (x / 40), discard counters, and a face-down deck.

Scoring

For the number cards in a submitted hand:

Hand pattern	Multiplier
Four of a kind (4 cards, all same type)	sum × 10
One of each (4 cards, all four types)	sum × 5
One pair / group (≥2 same type)	each ≥2 group sum × 2; other cards × 1
No match	sum × 1

Special cards modify scoring or manipulate the hand/deck. Each deck has its own 4 specials (12 total), all with distinct artwork.

Winning

A round is won when your score ≥ the round target. After 4 rounds, you win the game when the floor of your average round score ≥ the floor of the average round target (equal averages count as a win).

Persistence & logging

• Accounts and game history are stored in data/users.txt (passwords are salted + SHA‑256 hashed, never plaintext).
• Saved games are saves/<session>.txt; deck definitions are the editable text files in decks/.
• All important events are appended to a single human-readable log.txt.

---

Project Structure

src/com/kulatro/
  Main.java                 launches the Swing GUI
  model/                    cards, deck, hand, player, game state (no GUI/IO)
  engine/                   ScoreManager, RoundManager, DiscardPile,
                            GameEngine facade, 12 special-effect classes
  persistence/              deck loader, save/load, user store, logger
  exception/                custom checked exception hierarchy
  gui/                      Swing screens; gui/assets card-art mapping/loader
test/com/kulatro/selftest/  the SelfTest harness and suites
assets/                     card / medal / login PNG artwork
decks/                      alchemy.txt, element.txt, quantum.txt
*.ps1                       compile / run / selftest / javadoc scripts

---