Card Library API

Card Library API

The Card Library is Team 6's central registry of card definitions. Other systems should look up cards here instead of keeping their own copies.

Public retrieval goes through CardService. CardLibrary is the implementation that also registers cards.

• CardService: source
• CardLibrary: source
• Initial card set: Initial Cards

Team 5 and other gameplay systems should depend on CardService. Card loading within Team 6 uses CardLibrary.register(...).

Related: #32, #5

Registering Cards

Register individual cards using register():

CardLibrary library = new CardLibrary();
library.register(strike);
library.register(defend);

A collection of cards can also be registered when the library is created:

CardLibrary library = new CardLibrary(List.of(strike, defend));

register() stores each card using its unique ID.

Before registration, CardLibrary.register() validates the supplied CardConfig through CardValidator.validate(). If validation succeeds, the library then applies collection-level rules such as duplicate ID protection before storing the card.

Retrieving Cards

Look up a card using its ID:

CardService cards = library;

Optional<CardConfig> strike = cards.getCard("strike");

if (strike.isPresent()) {
    CardConfig config = strike.get();
    // Use the card configuration
}

Unknown IDs return Optional.empty() rather than null:

Optional<CardConfig> missing = cards.getCard("not-a-real-card");
// missing.isEmpty() == true

A null ID is handled in the same way and returns Optional.empty().

Retrieve all registered cards using:

List<CardConfig> allCards = cards.getAllCards();

Behaviour

Situation	Behaviour
Valid card with a unique ID	Registered and can be retrieved using that ID
Duplicate ID	Throws IllegalArgumentException; the original card is preserved
Null card	Throws IllegalArgumentException
Blank or null ID during registration	Throws IllegalArgumentException
Unknown ID passed to getCard()	Returns Optional.empty()
Null ID passed to getCard()	Returns Optional.empty()
Caller attempts to modify getAllCards() result	Throws UnsupportedOperationException; the library remains unchanged

getAllCards() returns an unmodifiable snapshot. Adding or removing elements from the returned list cannot modify the Card Library's internal collection.

What This API Does Not Do

• It does not load JSON files. This is handled by the card loading component.
• It does not define the card validation rules itself. Validation rules are implemented by CardValidator, which is called during registration. CardConfigLoader is responsible for loading card definitions from JSON..
• It does not create in-game card entities. Runtime card entity ownership is handled through Team 5 / Team 6 integration.

Example for Other Teams

Team 5 and other gameplay systems should access card definitions through CardService:

CardService cards = cardLibrary;

CardConfig strike = cards.getCard("strike")
        .orElseThrow(() ->
                new IllegalStateException("Missing card: strike"));

List<CardConfig> deckOptions = cards.getAllCards();

Calling systems are responsible for deciding how an unknown card ID should affect gameplay.

Tests

CardLibraryTest covers:

• registration of valid cards
• retrieval by ID
• retrieval of all registered cards
• duplicate ID rejection
• preservation of the original card after a duplicate registration attempt
• unknown and null ID handling
• null and blank registration inputs
• protection of the returned collection from modification

The initial CardLibraryTest suite contained 12 tests covering the core registration and retrieval behaviour. The test suite was later expanded with additional validation, edge-case, and coverage tests.

Current Integration Status

The Card Library uses the official CardConfig from #31. Cards are registered and retrieved using the public id field.

CardLibrary.register() uses CardValidator.validate() for per-card validation and also enforces collection-level rules such as duplicate ID protection.

Filtering by card type or rarity is not currently part of the Card Library API and is considered an optional extension.

Where to Get It

Merged into main as part of the Sprint 1 Team 6 integration via PR #77.