This is the beginner-facing view of a cell: instead of asking "what is the + * bitmask of this cell?", you ask plain yes/no questions like "is there a wall + * to my right?". Implementations (see the library README) translate the + * underlying N/S/E/W bitmask into these methods so the students using this + * library never touch a bitmask. + * + *
Directions are screen-relative, the way the maze is drawn: up is + * toward row 0, down is toward the last row, left is toward + * column 0, right is toward the last column. + */ +public interface Cell { + + /** The row (0-based) this cell sits in; row 0 is the top. */ + int row(); + + /** The column (0-based) this cell sits in; column 0 is the left edge. */ + int col(); + + /** {@code true} if a wall blocks movement off the top of this cell. */ + boolean wallUp(); + + /** {@code true} if a wall blocks movement off the bottom of this cell. */ + boolean wallDown(); + + /** {@code true} if a wall blocks movement off the left of this cell. */ + boolean wallLeft(); + + /** {@code true} if a wall blocks movement off the right of this cell. */ + boolean wallRight(); + + /** {@code true} if this is the maze's start cell (top-left). */ + boolean isStart(); + + /** {@code true} if this is the maze's goal cell (bottom-right). */ + boolean isGoal(); +} diff --git a/src/main/java/com/frc2713/mazesolver/DefaultMazeSolver.java b/src/main/java/com/frc2713/mazesolver/DefaultMazeSolver.java deleted file mode 100644 index d562b83..0000000 --- a/src/main/java/com/frc2713/mazesolver/DefaultMazeSolver.java +++ /dev/null @@ -1,12 +0,0 @@ -package com.frc2713.mazesolver; - -/** - * The library's {@link MazeSolver} implementation. Solving logic goes here. - */ -public final class DefaultMazeSolver implements MazeSolver { - - @Override - public int[][] solve(int[][] maze) { - throw new UnsupportedOperationException("not yet implemented"); - } -} diff --git a/src/main/java/com/frc2713/mazesolver/Maze.java b/src/main/java/com/frc2713/mazesolver/Maze.java new file mode 100644 index 0000000..13c10bd --- /dev/null +++ b/src/main/java/com/frc2713/mazesolver/Maze.java @@ -0,0 +1,35 @@ +package com.frc2713.mazesolver; + +/** + * A maze the student can explore. + * + *
A {@code Maze} is built from the raw {@code int[][]} bitmask grid the + * lesson site produces (see {@code CONTRACT.md}), but it hides that entirely: + * once you have a {@code Maze} you work with {@link Cell}s and a {@link Robot}, + * never bitmasks. + * + *
The library must provide a concrete implementation constructable from an + * {@code int[][]} grid so the site can build one — see {@code CONTRACT.md} for + * the agreed entry point. + */ +public interface Maze { + + /** Number of rows in the maze. */ + int rows(); + + /** Number of columns in the maze. */ + int cols(); + + /** + * The cell at the given position. + * + * @throws IndexOutOfBoundsException if the position is off the grid + */ + Cell cellAt(int row, int col); + + /** A fresh robot standing on the start cell (top-left), ready to solve. */ + Robot robot(); + + /** {@code true} if the given position is the goal cell (bottom-right). */ + boolean isGoalCell(int row, int col); +} diff --git a/src/main/java/com/frc2713/mazesolver/MazeSolver.java b/src/main/java/com/frc2713/mazesolver/MazeSolver.java index 488e4de..ce5a737 100644 --- a/src/main/java/com/frc2713/mazesolver/MazeSolver.java +++ b/src/main/java/com/frc2713/mazesolver/MazeSolver.java @@ -1,44 +1,35 @@ package com.frc2713.mazesolver; /** - * Solves a maze expressed as a grid of cells, where each cell is an - * N/S/E/W bitmask marking which sides are open (carved) rather than walled. + * A maze-solving algorithm — this is what a student writes. * - *
Bitmask convention (matches the {@code maze-generator} npm package used - * to author lesson content, so a maze can round-trip between the site and - * this library unchanged): - *
- * NORTH = 1 (0b0001) - * SOUTH = 2 (0b0010) - * EAST = 4 (0b0100) - * WEST = 8 (0b1000) - *- * A cell's value is the bitwise OR of every open side, e.g. a cell open to - * the north and east only is {@code NORTH | EAST == 5}. See {@link Direction}. + *
The library hands you a {@link Robot} sitting at the start of a maze; your + * job is to move it until it reaches the goal. You decide how — that + * decision is the algorithm. A simple "wall follower" might look like: * - *
Implementations must be pure: no networking, no threads, no filesystem, - * no AWT/Swing. This library runs inside a browser JVM (CheerpJ, OpenJDK 8), - * where none of those are available. + *
{@code
+ * public class MySolver implements MazeSolver {
+ * public void solve(Robot robot) {
+ * while (!robot.atGoal()) {
+ * if (robot.canMoveRight()) robot.moveRight();
+ * else if (robot.canMoveDown()) robot.moveDown();
+ * else if (robot.canMoveLeft()) robot.moveLeft();
+ * else robot.moveUp();
+ * }
+ * }
+ * }
+ * }
+ *
+ * The path the robot took is available afterwards via {@link Robot#trail()}. */ public interface MazeSolver { /** - * Finds a path through the maze. + * Drive the robot from the start cell to the goal cell. * - * @param maze a rectangular grid, indexed {@code maze[row][col]}, where - * each value is an N/S/E/W bitmask (see {@link Direction}) - * describing which sides of that cell are open. The maze is - * assumed to be a valid grid: every row the same length, and - * every "open" side agreed upon by both adjacent cells (e.g. - * if {@code maze[r][c]} has {@code EAST} set, then - * {@code maze[r][c + 1]} has {@code WEST} set). - * @return the path from the top-left cell ({@code [0][0]}) to the - * bottom-right cell ({@code [rows - 1][cols - 1]}), as an ordered - * list of {@code [row, col]} coordinate pairs starting with - * {@code {0, 0}} and ending with the destination cell. Returns - * an empty array ({@code new int[0][]}) if no path exists. - * @throws IllegalArgumentException if {@code maze} is null, empty, or - * not a valid rectangular grid + * @param robot a robot positioned at the maze's start; move it with + * {@link Robot#moveUp()} and friends until + * {@link Robot#atGoal()} is {@code true} */ - int[][] solve(int[][] maze); + void solve(Robot robot); } diff --git a/src/main/java/com/frc2713/mazesolver/Robot.java b/src/main/java/com/frc2713/mazesolver/Robot.java new file mode 100644 index 0000000..a532597 --- /dev/null +++ b/src/main/java/com/frc2713/mazesolver/Robot.java @@ -0,0 +1,69 @@ +package com.frc2713.mazesolver; + +/** + * A robot that walks through the maze, one cell at a time. + * + *
This is the main tool a student uses to write a solving algorithm. The + * robot always sits in exactly one cell (its position). You ask whether it + * can move a direction, and if so you tell it to move — for example: + * + *
{@code
+ * while (!robot.atGoal()) {
+ * if (robot.canMoveRight()) robot.moveRight();
+ * else if (robot.canMoveDown()) robot.moveDown();
+ * else robot.moveUp();
+ * }
+ * }
+ *
+ * Directions are screen-relative (see {@link Cell}). A robot never needs to + * know about bitmasks — it only knows where it is and which ways it can go. + */ +public interface Robot { + + /** The robot's current row (0-based); row 0 is the top. */ + int row(); + + /** The robot's current column (0-based); column 0 is the left edge. */ + int col(); + + /** The cell the robot is currently standing on. */ + Cell cell(); + + /** {@code true} if there is no wall above and a cell to move into. */ + boolean canMoveUp(); + + /** {@code true} if there is no wall below and a cell to move into. */ + boolean canMoveDown(); + + /** {@code true} if there is no wall to the left and a cell to move into. */ + boolean canMoveLeft(); + + /** {@code true} if there is no wall to the right and a cell to move into. */ + boolean canMoveRight(); + + /** + * Step one cell up. Implementations should throw + * {@link IllegalStateException} if {@link #canMoveUp()} is {@code false}, + * so a student learns to check before moving. + */ + void moveUp(); + + /** Step one cell down. See {@link #moveUp()} for the blocked-move rule. */ + void moveDown(); + + /** Step one cell left. See {@link #moveUp()} for the blocked-move rule. */ + void moveLeft(); + + /** Step one cell right. See {@link #moveUp()} for the blocked-move rule. */ + void moveRight(); + + /** {@code true} once the robot reaches the goal cell (bottom-right). */ + boolean atGoal(); + + /** + * Every cell the robot has stood on, in order, as {@code {row, col}} pairs — + * starting with the start cell and ending with its current cell. Handy for + * drawing the path the algorithm took. + */ + int[][] trail(); +}