Vibe galaxy map
This commit is contained in:
@@ -0,0 +1,182 @@
|
||||
---
|
||||
sessionId: session-260928-131223-1ueu
|
||||
---
|
||||
|
||||
# Requirements
|
||||
|
||||
### Overview & Goals
|
||||
The goal of this initiative is to elevate the UI and user experience of `ZeroSpace.Web` and introduce an interactive **Galaxy Map** page. The Galaxy Map will visually display all planetary nodes positioned by their coordinates `(X, Y)`, render connection lines between interconnected systems, and provide instant hover information popups detailing yields, occupation buffs, masteries, and faction classifications.
|
||||
|
||||
### Scope
|
||||
#### In Scope
|
||||
- **Galaxy Page (`/galaxy`)**: Interactive star map rendering all 78 star systems from `StarSystems.All` with their actual `(X, Y)` spatial coordinates.
|
||||
- **Connection Lines**: Drawing connection paths between systems based on `StarSystemData.ConnectedSystems`.
|
||||
- **Hover Information Popup**: Dynamic floating tooltip/card showing system name, kind, occupation buffs, system masteries, yield bonuses, and connections.
|
||||
- **Click Navigation**: Direct navigation from galaxy nodes to `/StarSystem/{Id}` details page.
|
||||
- **UI & Aesthetic Overhaul**:
|
||||
- Updating `NavMenu.razor` with a dedicated Galaxy Map entry and modern styling.
|
||||
- Revamping `Home.razor` from default template placeholder to an engaging sci-fi overview dashboard.
|
||||
- Enhancing theme colors, badge indicators, cards, and typography in `app.css`.
|
||||
|
||||
#### Out of Scope
|
||||
- Backend database schema modifications (uses existing static/generated `ZeroSpace.Model` records).
|
||||
- Real-time multiplayer synchronization or editing capabilities (map editing remains in `ZeroSpace.MapEditor`).
|
||||
|
||||
### User Stories
|
||||
- **As a player / wiki reader**, I want to view a visual galaxy map with all planetary nodes and connections so that I can understand system layout and routes across the galaxy.
|
||||
- **As a player**, I want to hover over any planetary node to immediately see its occupation buff, yields, and system mastery without having to navigate to separate pages.
|
||||
- **As a user**, I want to click on a star system node on the map to navigate directly to its detailed page.
|
||||
- **As a user**, I want a sleek, cohesive dark sci-fi web interface with clear navigation and a functional dashboard.
|
||||
|
||||
### Functional Requirements
|
||||
1. **Galaxy Map Rendering**:
|
||||
- The map shall render an SVG canvas encompassing coordinate bounds (0 to 1000) preserving aspect ratio.
|
||||
- Lines must connect every system with its entries in `ConnectedSystems` without duplicate edge rendering.
|
||||
- Planetary nodes shall be rendered as circular nodes styled and colored according to `StarSystemKind`:
|
||||
- *Homeworld*: Vibrant Emerald / Green (`#43a047` / `#10b981`)
|
||||
- *Core*: Vibrant Amber / Orange (`#fb8c00` / `#f59e0b`)
|
||||
- *Side*: Vibrant Sky Blue / Cyan (`#4a90d9` / `#38bdf8`)
|
||||
2. **Hover Information Popup**:
|
||||
- Hovering over a planet node triggers a floating information popup.
|
||||
- Popup content includes:
|
||||
- Planet Name & Kind badge
|
||||
- Occupation buff (e.g. `+50 Starting Hexite`)
|
||||
- System mastery name (if present)
|
||||
- Higher yield indicators (Influence, Credits, Energy, Items)
|
||||
- Count and list of connected star systems
|
||||
- Tooltip disappears smoothly when the cursor leaves the node.
|
||||
3. **Map Interaction**:
|
||||
- Hovering a node highlights the node (glow ring) and highlights incoming/outgoing connection lines.
|
||||
- Clicking a node navigates to `/StarSystem/{Id}`.
|
||||
4. **App Navigation & Home Page**:
|
||||
- `NavMenu.razor` includes a link to `/galaxy` labeled "Galaxy Map" with an appropriate icon.
|
||||
- `Home.razor` provides quick-launch cards to Galaxy Map, Star Systems, Masteries, and Units with summary counts.
|
||||
|
||||
### Non-Functional Requirements
|
||||
- **Performance**: Instant SVG rendering with zero lag for 78 nodes and ~200 connections; pure CSS/Blazor event handling with no external heavy mapping dependencies.
|
||||
- **Responsiveness**: Map scales smoothly inside its container across desktop and mobile screens.
|
||||
- **Accessibility**: Clear contrast ratios, readable tooltips, and keyboard/touch support for node selection.
|
||||
|
||||
# Technical Design
|
||||
|
||||
### Current Implementation
|
||||
- `ZeroSpace.Model.StarSystems.All`: Contains all 78 star systems with records containing `Id`, `Name`, `Kind`, `X`, `Y`, `ConnectedSystems`, `OccupationBuff`, `SystemMastery`, and yield flags.
|
||||
- `ZeroSpace.Web`: Blazor WebAssembly application using Bootstrap 5 and Telerik Blazor components.
|
||||
- Existing pages include `StarSystemIndex.razor`, `StarSystemDetail.razor`, `SystemMasteryIndex.razor`, and `Units.razor`.
|
||||
- `Home.razor` is currently a default "Hello World" template placeholder.
|
||||
|
||||
### Key Decisions
|
||||
1. **SVG Vector Graphics for Galaxy Map**:
|
||||
- *Chosen Approach*: Native Blazor SVG rendering (`<svg viewBox="0 0 1000 1000">`).
|
||||
- *Rationale*: SVG offers vector sharpness at all display resolutions, reactive Blazor event binding (`@onmouseenter`, `@onmouseleave`, `@onclick`), lightweight footprint, and zero external JS dependency overhead.
|
||||
2. **Dynamic Overlay Tooltip**:
|
||||
- *Chosen Approach*: HTML/CSS floating glassmorphism card positioned relative to the hovered node/cursor with smooth fade transition.
|
||||
- *Rationale*: Allows rich formatting (badges, icons, multi-column yields) and styling that matches the dark sci-fi aesthetic better than native SVG `<title>` or basic browser tooltips.
|
||||
3. **Connection Line Optimization**:
|
||||
- *Chosen Approach*: Precompute unique undirected edge pairs `(From, To)` on initialization.
|
||||
- *Rationale*: Prevents duplicate overlapping lines between reciprocal connections `A -> B` and `B -> A`, improving render performance and visual clarity.
|
||||
|
||||
### Proposed Architecture & Flow
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Nav[NavMenu.razor] -->|Navigate /galaxy| GalaxyPage[Galaxy.razor]
|
||||
Home[Home.razor] -->|Quick Link| GalaxyPage
|
||||
|
||||
subgraph Galaxy.razor
|
||||
Model[StarSystems.All] --> EdgeBuilder[Connection Deduplicator]
|
||||
EdgeBuilder --> SVGCanvas[SVG Canvas ViewBox 0 0 1000 1000]
|
||||
Model --> NodeRenderer[Node Elements & Coordinates]
|
||||
|
||||
SVGCanvas --> Lines[SVG Lines: Connection Paths]
|
||||
SVGCanvas --> Nodes[SVG Circles & Glows: Planets]
|
||||
|
||||
Nodes -->|@onmouseenter| HoverState[Hovered System State]
|
||||
Nodes -->|@onclick| NavAction[NavigationManager.NavigateTo /StarSystem/Id]
|
||||
|
||||
HoverState --> Popup[Floating Planet Info Card]
|
||||
end
|
||||
```
|
||||
|
||||
### Components & File Structure
|
||||
- **New Files**:
|
||||
- `ZeroSpace.Web/Pages/Galaxy.razor`: Main Galaxy map page containing the SVG viewport, control header, node filtering/legend, and popup overlay.
|
||||
- `ZeroSpace.Web/Pages/Galaxy.razor.css`: Scoped styles for map container, SVG glow effects, connection styling, and animated hover card.
|
||||
- **Modified Files**:
|
||||
- `ZeroSpace.Web/Layout/NavMenu.razor`: Add "Galaxy Map" item with navigation icon.
|
||||
- `ZeroSpace.Web/Pages/Home.razor`: Overhaul into a sci-fi hub with hero banner and feature cards.
|
||||
- `ZeroSpace.Web/wwwroot/css/app.css`: Dark sci-fi styling improvements, badge colors, and glassmorphism utilities.
|
||||
|
||||
### Data Models / Contracts
|
||||
```csharp
|
||||
public sealed record ConnectionEdge(
|
||||
StarSystemData From,
|
||||
StarSystemData To);
|
||||
|
||||
public sealed class GalaxyMapState
|
||||
{
|
||||
public IReadOnlyList<StarSystemData> Systems { get; set; } = StarSystems.All;
|
||||
public IReadOnlyList<ConnectionEdge> Connections { get; set; } = [];
|
||||
public StarSystemData? HoveredSystem { get; set; }
|
||||
public double TooltipX { get; set; }
|
||||
public double TooltipY { get; set; }
|
||||
public string? SelectedKindFilter { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
### Risks & Mitigations
|
||||
- **Tooltip overflow near screen edges**: Clamp calculated tooltip coordinates within container boundaries to prevent viewport clipping.
|
||||
- **Coordinate overlap on small screens**: Ensure viewBox preserves 1:1 aspect ratio (`preserveAspectRatio="xMidYMid meet"`) and allow zooming/scaling via standard CSS/viewport responsiveness.
|
||||
|
||||
# Testing
|
||||
|
||||
### Validation Approach
|
||||
Verification will be performed through build checks, component markup analysis, and interactive scenario validation in the Blazor runtime.
|
||||
|
||||
### Key Scenarios
|
||||
1. **Galaxy Map Rendering**:
|
||||
- Verify that all 78 star systems are rendered at their designated `(X, Y)` positions.
|
||||
- Verify that connection lines accurately connect linked systems without orphaned or broken lines.
|
||||
- Verify node color coding matches `StarSystemKind` (Homeworld, Core, Side).
|
||||
2. **Hover Information Popup**:
|
||||
- Hovering over a planet node displays the popup immediately.
|
||||
- Verify all fields render accurately (Occupation buff, System mastery, Yields, Connected systems list).
|
||||
- Moving the mouse away dismisses the popup cleanly.
|
||||
3. **Navigation & Interactivity**:
|
||||
- Clicking a node navigates to the corresponding `/StarSystem/{Id}` route.
|
||||
- Navigating via the "Galaxy Map" link in `NavMenu.razor` loads the page properly.
|
||||
4. **UI & Responsiveness**:
|
||||
- Verify `Home.razor` renders updated dashboard cards and quick links.
|
||||
- Verify dark-theme sci-fi visual style across desktop and smaller browser viewports.
|
||||
|
||||
### Regressions & Edge Cases
|
||||
- Star systems without occupation buffs or masteries display clean fallback dashes (`—`) without layout breaks.
|
||||
- Rapid mouse movements over adjacent nodes update the hover popup smoothly without flickering.
|
||||
|
||||
# Delivery Steps
|
||||
|
||||
### ✓ Step 1: Implement Galaxy Map SVG rendering and connection lines
|
||||
A functional SVG-based Galaxy Map page (`Galaxy.razor`) renders all star system nodes and connection lines based on their world coordinates.
|
||||
|
||||
- Create `ZeroSpace.Web/Pages/Galaxy.razor` with route `@page "/galaxy"` and navigation title.
|
||||
- Parse `StarSystems.All` to extract unique undirected connection pairs and planetary node coordinate models.
|
||||
- Render connection lines (`<line>`) in SVG with dark-steel futuristic line styling (`#3a4d6b`, opacity, glow).
|
||||
- Render planetary nodes (`<circle>` / `<g>`) positioned at `(system.X, system.Y)` using color coding based on `StarSystemKind` (Homeworld = green, Core = orange/amber, Side = blue/cyan).
|
||||
- Add SVG viewBox scaling (e.g. `0 0 1000 1000`) and responsive container layout to ensure crisp vector rendering on all screen sizes.
|
||||
- Implement click handlers on nodes to navigate directly to `/StarSystem/{Id}`.
|
||||
|
||||
### ✓ Step 2: Implement dynamic planetary hover popup and interactive highlights
|
||||
Interactive hover tooltip overlays display rich star system details when the user hovers over any planet node on the galaxy map.
|
||||
|
||||
- Design a floating glassmorphism hover card component / markup positioned dynamically relative to the active node or cursor.
|
||||
- Display star system metadata: system name, `Kind` badge, `OccupationBuff`, `SystemMastery` link, and `Yield` bonuses (Influence, Credits, Energy, Items).
|
||||
- Add highlight visual effects when hovering over a node (pulsing glow radius, highlight connected lines).
|
||||
- Handle edge cases such as tooltip boundary clamping near viewport edges and debounced mouse enter/leave events.
|
||||
|
||||
### ✓ Step 3: Refine global UI, navigation menu, and dashboard landing page
|
||||
ZeroSpace.Web navigation, Home landing dashboard, and global UI styles are updated to match a polished sci-fi space aesthetic.
|
||||
|
||||
- Update `ZeroSpace.Web/Layout/NavMenu.razor` with a dedicated "Galaxy Map" navigation link with custom star/galaxy icon.
|
||||
- Transform `ZeroSpace.Web/Pages/Home.razor` into an overview hub showcasing quick links and summary stats for Galaxy Map, Star Systems, System Masteries, and Units.
|
||||
- Enhance `ZeroSpace.Web/wwwroot/css/app.css` and component stylesheets with refined dark-theme colors, glassmorphism cards, glowing badges, and smooth hover transitions.
|
||||
- Verify solution builds cleanly and all navigation flows between the Galaxy map, system details, and other pages work seamlessly.
|
||||
Reference in New Issue
Block a user