Map Interaction and Node Selection - UQcsse3200/2026-studio-3 GitHub Wiki

The Map Interaction system handles player input on the map, turning a click on a node into a validated move, and emits events that the UI uses for visual feedback.

It sits on top of the Map Graph System and never modifies map state directly. All validation and movement is delegated to MapGraph, so an illegal move cannot be forced through interaction.

The core of node selection. It takes a single input, the player clicking a node, and decides what happens:

onNodeClicked(Integer nodeId)

• If the node is AVAILABLE, it requests the move via MapGraph.moveToNode() and fires nodeSelected.
• If the node is COMPLETED, it fires nodeCompleted.
• If the node is LOCKED or unknown, it fires nodeLocked and sends no move.
• If MapGraph rejects the move during validation, it fires nodeSelectionRejected. The controller never decides validity itself, it always defers to MapGraph.

It also exposes helpers for the UI:

• getSelectableNodeIds() - the ids of all currently AVAILABLE nodes, so the UI can highlight selectable nodes.
• isSelectable(Integer nodeId) - whether a specific node can be selected right now.

Interaction communicates with the UI through events rather than touching rendering directly. This keeps input logic and rendering independent.

• nodeSelected - a valid move was committed.
• nodeLocked - a locked or unavailable node was clicked.
• nodeCompleted - an already-completed node was clicked.
• nodeSelectionRejected - the move was rejected during validation.
• nodeHovered / nodeUnhovered - the pointer entered or left a node, for hover feedback.

Attaches scene2d input listeners to node actors and routes clicks and hovers to the MapSelectionController.

attach(NodeActor actor) wires a single actor; attachAll(List<NodeActor> actors) wires a group.

It works with any actor that exposes a node id, so it does not need to change when the final map UI actors replace the placeholder.

A minimal placeholder actor carrying a node id and clickable bounds, used to test interaction before the full map UI is in place.

• MapSelectionController - decides what a node click does.
• MapInputHandler - routes scene2d input to the controller.
• NodeActor - placeholder clickable node.

Unit tests cover:

• Clicking a locked, completed, unknown, or null node (each fires the correct event and sends no move).
• getSelectableNodeIds() returning only AVAILABLE nodes.
• isSelectable() matching node state.
• Clicks and hovers routing to the correct node id through MapInputHandler. Happy-path move tests are pending a seeded starting CURRENT node, which depends on map generation.