POKEDEX

A retro-styled Pokédex application built with JavaFX, featuring pixel-perfect UI positioning, JSON data loading, sound effects, and an authentic Pokémon lookup experience.

The application maintains several state variables in the Model:

Represents a single Pokémon with all its attributes. This POJO (Plain Old Java Object) is used by Jackson for JSON deserialization.

package com.example.model;

import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;

public class Pokemon {
    private String picture;          // Filename of sprite image
    private String name;             // Pokémon name
    private int evolutionStage;      // 1, 2, or 3
    private String shortDescription; // Brief description
    private int dexNumber;           // National Pokédex number
    
    @JsonProperty("isLegendary")
    private boolean legendary;       // Legendary status
    
    private List<String> types;      // e.g., ["Fire", "Flying"]
    
    // Getters and setters for all fields
}

The main class that extends Application and initializes the MVC components. It sets up the Scene and Stage, then delegates control to the Controller.

package com.example;

import com.example.controller.PokedexController;
import com.example.model.PokedexModel;
import com.example.view.PokedexView;
import javafx.application.Application;
import javafx.scene.Scene;
import javafx.stage.Stage;

public class App extends Application {
    @Override
    public void start(Stage stage) {
        // Initialize MVC components
        PokedexModel model = new PokedexModel();
        PokedexView view = new PokedexView(getClass());
        PokedexController controller = 
            new PokedexController(model, view, getClass());
        
        // Load data
        controller.loadData();
        
        // Create scene
        Scene scene = new Scene(
            view.getRoot(), 
            PokedexView.getWindowWidth(), 
            PokedexView.getWindowHeight()
        );
        
        // Setup stage
        stage.setTitle("Pokédex");
        stage.setScene(scene);
        stage.setResizable(false);
        stage.show();
        
        // Initialize to powered off state
        controller.initializePoweredOff();
    }
    
    public static void main(String[] args) {
        launch(args);
    }
}

The application uses Class.getResourceAsStream() to load resources, ensuring they work correctly whether running from IDE or JAR file. The Class object is passed to the View and Controller for resource access.

// In View constructor - passed from App
public PokedexView(Class resourceClass) {
    this.resourceClass = resourceClass;
    // ... initialization
}

// Loading an image
String imgPath = "/pokedex/pokemon-pictures/1.png";
InputStream stream = resourceClass.getResourceAsStream(imgPath);
if (stream != null) {
    Image image = new Image(stream);
    imageView.setImage(image);
}

// Loading font
InputStream fontStream = resourceClass
    .getResourceAsStream("/fonts/PressStart2P-Regular.ttf");
Font customFont = Font.loadFont(fontStream, 12);

// Loading audio
String audioPath = resourceClass
    .getResource("/whos-that-pokemon.mp3").toExternalForm();
Media media = new Media(audioPath);
MediaPlayer player = new MediaPlayer(media);

Jackson ObjectMapper handles the deserialization of JSON data into Java objects. The Model uses this to populate the Pokémon list at startup.

public boolean loadData(InputStream inputStream) {
    ObjectMapper mapper = new ObjectMapper();
    try {
        if (inputStream == null) {
            return false;
        }
        
        // Deserialize JSON array into List<Pokemon>
        pokedexList = mapper.readValue(
            inputStream,
            new TypeReference<List<Pokemon>>() {}
        );
        
        return !pokedexList.isEmpty();
    } catch (IOException e) {
        e.printStackTrace();
        return false;
    }
}

All UI elements use absolute positioning relative to the background image. Constants define each component's exact location to ensure pixel-perfect alignment.

// View class constants
private static final double WIN_W = 548;
private static final double WIN_H = 400;
private static final double SCREEN_X = 128, SCREEN_Y = 125;
private static final double SCREEN_W = 104, SCREEN_H = 104;

private static final double POKEMON_NUMBER_X = 79;
private static final double POKEMON_NUMBER_Y = 140;

private static final double DESC_X = 77, DESC_Y = 314;
private static final double DESC_W = 111, DESC_H = 43;

When in mystery mode (isRevealed = false), the Pokémon sprite is shown as a black silhouette using JavaFX's ColorAdjust effect.

// Create the effect (in View constructor)
silhouetteEffect = new ColorAdjust();
silhouetteEffect.setBrightness(-1.0);  // Maximum darkness

// Apply to ImageView (in displayPokemonHidden)
if (!model.isRevealed()) {
    mainScreenImage.setEffect(silhouetteEffect);
} else {
    mainScreenImage.setEffect(null);  // Clear effect
}

The application plays a "Who's That Pokemon?" sound effect when entering mystery mode. This enhances the authentic Pokemon experience.

// MediaPlayer field in View class
private MediaPlayer mediaPlayer;

// Play sound when displaying hidden Pokemon
private void playWhosThatPokemonSound() {
    try {
        // Stop existing sound if playing
        if (mediaPlayer != null) {
            mediaPlayer.stop();
        }
        
        // Load and play sound
        String path = resourceClass
            .getResource("/whos-that-pokemon.mp3")
            .toExternalForm();
        Media media = new Media(path);
        mediaPlayer = new MediaPlayer(media);
        mediaPlayer.play();
    } catch (Exception e) {
        System.err.println("Could not play sound: " + e.getMessage());
    }
}

// Called from displayPokemonHidden method
public void displayPokemonHidden(Pokemon pokemon, boolean isPoweredOn) {
    if (pokemon == null) return;
    
    // Play sound effect
    if (isPoweredOn) {
        playWhosThatPokemonSound();
    }
    
    // Apply silhouette and update UI
    // ...
}

Prerequisites:

• Java 21 or higher (JDK)
• Maven 3.6 or higher
• Git (for cloning)

Step 1: Clone Repository

Step 2: Build Project

Step 3: Run Application

module com.example {
    // JavaFX dependencies
    requires javafx.controls;
    requires javafx.graphics;
    requires javafx.media;        // Required for sound effects
    requires javafx.fxml;
    
    // Jackson dependencies
    requires com.fasterxml.jackson.databind;
    requires com.fasterxml.jackson.core;
    requires com.fasterxml.jackson.annotation;
    
    // Export packages
    exports com.example;
    exports com.example.controller;
    exports com.example.view;
    exports com.example.model;
    
    // Open for reflection (Jackson)
    opens com.example.model to com.fasterxml.jackson.databind;
}

Key sections of the Maven configuration:

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
</properties>

<dependencies>
    <dependency>
        <groupId>org.openjfx</groupId>
        <artifactId>javafx-controls</artifactId>
        <version>21</version>
    </dependency>
    <dependency>
        <groupId>org.openjfx</groupId>
        <artifactId>javafx-fxml</artifactId>
        <version>21</version>
    </dependency>
    <dependency>
        <groupId>org.openjfx</groupId>
        <artifactId>javafx-media</artifactId>
        <version>21</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.15.2</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-maven-plugin</artifactId>
            <version>0.0.8</version>
            <executions>
                <execution>
                    <id>default-cli</id>
                    <configuration>
                        <mainClass>com.example.App</mainClass>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

The Pokémon data is stored in a JSON array. Each entry follows this structure:

[
  {
    "picture": "pokemon-pictures/1.png",
    "name": "bulbasaur",
    "evolutionStage": 1,
    "shortDescription": "A strange seed was planted on its back at birth...",
    "dexNumber": 1,
    "isLegendary": false,
    "types": ["grass", "poison"]
  },
  {
    "picture": "pokemon-pictures/2.png",
    "name": "ivysaur",
    "evolutionStage": 2,
    "shortDescription": "When the bulb on its back grows large...",
    "dexNumber": 2,
    "isLegendary": false,
    "types": ["grass", "poison"]
  }
]

• Picture field: Must be a relative path from /pokedex/ directory (includes "pokemon-pictures/" subdirectory)
• Evolution stage: Must be 1, 2, or 3 (no other values)
• Dex number: Should be unique and sequential for Kanto (1-151)
• Types: Can have 1 or 2 types (no Pokémon has zero types)
• Short description: Should be brief enough to fit in the display area

The UI uses pixel-perfect absolute positioning relative to the background image. Each component is carefully aligned to create an authentic retro Pokédex experience.

• Font: Press Start 2P - Authentic retro pixel font for that classic 8-bit feel
• Text Colors:
  • Standard text: #000000 (Black)
  • Mystery mode: #C42020FF (Red)
  • Description: #084036 (Dark green)
  • Digital display: #32EE25 (Bright green)
• Silhouette Effect: ColorAdjust effect with brightness set to -1.0 creates perfect black silhouettes
• Text Wrapping: Description text wraps at 111px width to fit the screen area
• Font Sizes: Carefully calibrated for readability (6-12px depending on component)

The View class uses a Pane as the root container, allowing absolute positioning of all children. Key implementation points:

// Root container setup
root = new Pane();

// Background image
ImageView background = new ImageView(
    new Image(resourceClass.getResourceAsStream("/pokedex_bg.png"))
);
background.setFitWidth(WIN_W);
background.setFitHeight(WIN_H);
root.getChildren().add(background);

// Positioned components
mainScreenImage.setLayoutX(SCREEN_X);
mainScreenImage.setLayoutY(SCREEN_Y);
mainScreenImage.setFitWidth(SCREEN_W);
mainScreenImage.setFitHeight(SCREEN_H);

pokemonNumberLabel.setLayoutX(POKEMON_NUMBER_X);
pokemonNumberLabel.setLayoutY(POKEMON_NUMBER_Y);

Current Implementation: Fixed window size (548×400) for pixel-perfect display matching the background image.

Extension Opportunity: For a responsive version, you could:

• Scale all coordinates proportionally to window size
• Use percentage-based positioning
• Implement SVG graphics instead of PNG for scaling
• Add multiple layout profiles for different screen sizes

Before considering a feature complete, verify the following:

• Console Logging: Add System.out.println() statements to track state changes and method calls
• Resource Loading: Always check if getResourceAsStream() returns null before using the resource
• State Inspection: Print Model state variables after each interaction to verify correct updates
• JSON Validation: Use online JSON validators (jsonlint.com) to catch syntax errors
• Visual Debugging: Temporarily make button hitboxes visible (set opacity to 0.3) to verify positioning
• Maven Clean: When in doubt, run mvn clean install to ensure fresh build
• Sound Testing: Check console for MediaPlayer errors if sound doesn't play

The project uses JPMS (Java Platform Module System). The module-info.java file declares module dependencies and accessibility:

module com.example {
    // JavaFX dependencies
    requires javafx.controls;
    requires javafx.graphics;
    requires javafx.media;        // Required for sound effects!
    requires javafx.fxml;
    
    // Jackson dependencies for JSON parsing
    requires com.fasterxml.jackson.databind;
    requires com.fasterxml.jackson.core;
    requires com.fasterxml.jackson.annotation;
    
    // Export packages (make accessible to other modules)
    exports com.example;
    exports com.example.controller;
    exports com.example.view;
    exports com.example.model;
    
    // Open packages for reflection (needed for Jackson)
    opens com.example.model to com.fasterxml.jackson.databind;
}

Key Maven plugin configuration for running the JavaFX application:

<plugin>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-maven-plugin</artifactId>
    <version>0.0.8</version>
    <executions>
        <execution>
            <id>default-cli</id>
            <configuration>
                <mainClass>com.example.App</mainClass>
            </configuration>
        </execution>
    </executions>
</plugin>

This plugin handles JavaFX module path configuration automatically, allowing you to run the application with mvn javafx:run.

If not using Maven: You'll need to manually configure module paths and classpath. Here's how for different build systems:

Gradle Configuration:

plugins {
    id 'application'
    id 'org.openjfx.javafxplugin' version '0.0.14'
}

javafx {
    version = "21"
    modules = ['javafx.controls', 'javafx.fxml', 'javafx.media']
}

dependencies {
    implementation 'com.fasterxml.jackson.core:jackson-databind:2.15.2'
}

application {
    mainModule = 'com.example'
    mainClass = 'com.example.App'
}

Manual Compilation (command line):

• JSON Validation: Validate JSON structure before deserialization to prevent parsing errors
• Array Bounds: Check array bounds before accessing Pokemon list (especially with user-driven navigation)
• Resource Existence: Handle missing image files gracefully with fallback images or error messages. Same for audio files.
• Input Sanitization: If adding search functionality, sanitize user input to prevent injection issues
• Data Validation: Validate evolution stage values (1-3), dex numbers (1-151), and ensure required fields exist
• Type Safety: Use strong typing and avoid raw types or excessive casting

Current Implementation:

• Lazy Image Loading: Images are loaded on-demand per Pokemon, not all at startup - saves memory
• JSON Caching: JSON is loaded once at startup and cached in memory for the application lifetime
• Effect Reuse: ColorAdjust effect is created once and reused for all silhouettes
• Font Sharing: Custom font is loaded once and shared across all labels
• Sound Management: MediaPlayer instance is reused, stopping previous playback before starting new

Optimization Opportunities:

• Image Caching: Cache loaded images to avoid reloading when navigating back to previously viewed Pokemon
• Preloading: Preload adjacent Pokemon images in background for smoother navigation
• Virtual Scrolling: If implementing a grid view, only render visible items
• Thumbnail Generation: Create smaller thumbnails for list views to reduce memory usage
• Audio Preloading: Preload sound effect at startup to eliminate first-play delay

• Naming Conventions: Use descriptive names (handlePowerOn not doThing), follow Java naming standards
• Documentation: Add Javadoc comments to public methods explaining parameters and return values
• Method Length: Keep methods short (ideally under 30 lines) - extract complex logic into helper methods
• Magic Numbers: Avoid magic numbers in code - use named constants with descriptive names
• DRY Principle: Don't Repeat Yourself - extract repeated code into reusable methods
• Error Messages: Provide helpful error messages that guide users or developers to solutions
• Logging: Use proper logging (java.util.logging) instead of System.out.println for production code

While the current project doesn't include tests, here's what you should test if expanding:

Model Layer (Easy to Unit Test):

• Navigation boundary conditions (wrap-around)
• Power state transitions
• Reveal/hide toggle behavior
• Data loading and parsing
• State consistency after operations

Controller Layer (Integration Tests):

• Event handler responses
• View update triggers
• State validation enforcement

View Layer (Manual/Visual Tests):

• UI rendering correctness
• Button positioning accuracy
• Effect application (silhouettes)
• Text wrapping and fitting
• Sound playback functionality

.gitignore recommendations:

# Build artifacts
target/
*.class
*.jar
*.war

# IDE files
.idea/
.vscode/
*.iml
.project
.classpath
.settings/

# OS files
.DS_Store
Thumbs.db

# Maven
dependency-reduced-pom.xml

# Logs
*.log

Commit Message Guidelines:

• Use present tense: "Add feature" not "Added feature"
• Be specific: "Fix navigation wrap-around bug" not "Fix bug"
• Reference issues/tickets when applicable
• Keep first line under 50 characters
• Add detailed explanation in body for complex changes