Mobile UI Implementation for Terratomic#278
Draft
El-Magico777 wants to merge 28 commits intov0.3.0from
Draft
Conversation
Double zoom button step size for faster tap-based zooming and reduce pinch sensitivity for finer touch control.
…om tuning, and i18n fix
… sizing. Mobile: horizontal carousel map selection in lobby modals - Replace vertical scrolling map grids with horizontal carousel - Add category tabs (Continental, Regional, Fantasy) for faster navigation - Auto-switch to active category when selecting a map - Category state tracked in both SinglePlayerModal and HostLobbyModal - Mobile-optimized with touch scroll and snap behavior - Random map tile visible in all categories - Reduces scroll friction on mobile with 31 maps Lobby modals: close extra settings by default and fix dropdown contrast - Set showUnitSettings to false by default in SinglePlayerModal - Fix open() method that was resetting showUnitSettings to true - Add explicit styling for select option elements with darker background - Fixes light text on white background in dropdowns (gold multiplier, starting gold, peace timer) Lobby modals: add viewport-aware responsive sizing - Integrate mobile viewport tracking system (getMobileViewportProfile) - Add resize listeners via connectedCallback/disconnectedCallback - Apply size-class data attributes (compact/regular/large) to body - Compact portrait (360px): 0.9x scale, smaller fonts, tighter spacing - Compact landscape: 0.95x scale, optimized horizontal layout - Regular phones (361-430px): 0.98x balanced scale - Large tablets (>430px): 1.1x scale, generous spacing - Fixes: cramped UI on small phones, oversized elements in landscape - Consistent with in-game mobile UI responsive system
- Add extra-large size class for devices with shortest side over 768px - Increase action grid tiles from 70px to 85px - Increase icons from 31px to 38px and fonts from 12px to 14px - Increase padding from 18px to 24px and gaps from 9px to 12px - Add iPad Pro 12.9 inch test cases - All 395 tests passing
- Add MobileUnitSelection.ts with 40px screen-distance hit detection for forgiving tap targeting of Warship, Submarine, FighterJet, Artillery - Update MobileUI.ts with selection state, redirect-on-tap mode, floating selection banner, and unit:select action routing - Update MobileActionGrid.ts to show 'Select [Unit]' actions on ALL tile categories (own, enemy, neutral) when near a selectable unit - Add MobileUnitSelection.test.ts with 11 tests covering hit radius, owner filtering, distance sorting, and terrain validation
…talog - documented unit selection and redirection feature - updated MobileUI component map with MobileUnitSelection - added new unit-related events to EventBus table - updated ActionGrid catalog with unit selection actions - updated feature parity matrix
Added pointer-events: none to HeadsUpMessage container and message elements for mobile-ui-enabled contexts. This prevents the 'choose start location' banner from intercepting taps during spawn phase, allowing touches beneath the top bar to properly reach the canvas. Desktop positioning and behavior unchanged. Fixes #225
Adds attack troop count badges to mobile action buttons for Ground Attack, Naval Assault, and Paratroopers. Uses attackRatio-based troop amount and renderTroops display scaling to match existing UI troop formatting. Also styles the badge with a combat-focused look to avoid confusion with resource/currency badges. Closes #218
Adds a live attack troop readout beneath the Attack Ratio slider in the mobile economy overlay, using the same attack-ratio calculation and troop display formatting as mobile attack action badges. This keeps eco-tab attack planning and action-button values aligned.
Anchors mobile attack bubbles at the bottom by default and dynamically repositions them above the mobile action grid when it opens. Also removes the visual line artifact by eliminating the attack-bar container background and tightening spacing above the grid. Mobile-only UI behavior; desktop unchanged.
Pins the clock recess to the left edge and settings recess to the right edge on wider mobile portrait screens, while keeping center stats centered. Small-screen behavior remains unchanged.
Updates MobileSettingsSidebar to use the same --m-panel-top-offset token as other mobile overlays, so it opens below the top bar on larger screens instead of overlapping it. Mobile-only change.
- Fix click interception on small portrait screens by adjusting :host pointer-events area to only cover the sidebar (right side) - Add stacked layout for larger tablets: Portrait mode: large (min-height 600px) and extra-large Landscape mode: large and extra-large (min-width 1000px) Stacked mode shows Players, Leaderboard, and Events sections vertically (portrait) or in 2-column grid (landscape) instead of tabs, providing better space utilization on larger screens - Tabs remain visible on smaller screens with existing tabbed interface
Adds a mobile-only stack label refresh signal and triggers a short refresh burst after stack taps so labels repaint deterministically while still using authoritative server state. - add RefreshMobileStackLabelsEvent - listen in StructureLayer and rebuild labels when mobile + upgrade mode - emit refresh burst from MobileUI stack tap path - clean pending refresh timers on stack mode off / destroy
Removes attack-bubble anchoring from research priority modal/toast so they stay top-anchored and no longer shift downward during active attacks. Also keeps responsive horizontal alignment behavior: - phone portrait: left aligned - landscape + tablet portrait: centered
El-Magico777
changed the title
5 tasks
This was
linked to
issues
Feb 23, 2026
Closed
This was referenced Feb 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR #210 on top of v0.3.0 branch
Mobile UI Implementation for Terratomic
🎯 Player-Facing Overview
Terratomic is now fully playable on mobile devices! This implementation brings the complete PC strategy experience to touchscreen devices with a native mobile interface designed specifically for on-the-go gameplay.
What Players Get:
Target Devices:
Play anywhere, command everywhere. The full strategic depth of Terratomic now fits in your pocket.
🖼️ UI Comparison: Desktop vs Mobile
Desktop UI (Traditional)
Mobile UI (Touch-First)
Key Visual Differences:
🏗️ Technical Overview
Architecture
The mobile UI is implemented as a parallel interface layer that runs alongside the existing desktop client, sharing the same game logic and network layer but with a completely redesigned presentation layer optimized for touch interactions.
Entry Point Detection:
MobileDetector(137 lines) identifies mobile devices via user-agent, touch capability, screen size, and device-specific quirksCore Orchestrator:
MobileUI(873 lines) acts as the central coordinator for all mobile componentsMobileUIInteractions(341 lines) — attack, diplomacy, spawn, chat, emoji, donation handlersMobileUIStateSync(127 lines) — game tick → topbar/tab/trade-indicator synchronizationMobileUIEventSetup(133 lines) — centralized listener registration for UI controlsMobileUIOverlayCoordinator(55 lines) — overlay positioning + per-tick update orchestrationMobileUIMapStack(154 lines) — screen→tile conversion + stack upgrade targeting helpersGesture System:
GestureDetector(331 lines) implements a touch state machine for recognizing gestures:<200ms, movement<10px→ tile selection, button presses600ms, movement<10px→ player info, economy overlay>10px→ map panningradiusX/radiusY > 30px)Responsive Scaling:
MobileViewportProfile(247 lines) classifies viewports into profiles:430x932) as no-regression reference profileMobileUI.applyResponsiveProfile()→ ActionGrid + overlaysComponent Hierarchy:
Key Technical Decisions
1. Isomorphic Game Logic
src/core/—mobile UI calls the same execution APIs as desktopClientGameRunner) remains unchangedTransport.ts) shares network code between desktop and mobile2. Modular Orchestrator Pattern
MobileUIdelegates specialized concerns to helper modules instead of becoming a 3000+ line monolith3. Z-Index Stacking System
z-index: 0z-index: 1650z-index: 1700z-index: 1758-1760z-index: 1800z-index: 2000z-index: 2500z-index: 3000z-index: 4050+4. Haptic Feedback System
HapticFeedbackutility wrapsnavigator.vibrate()5. Responsive Token System
--mobile-*) for dynamic stylingPerformance Optimizations
Testing Coverage
Unit Tests (6 test files, 629 lines):
GestureDetector.test.ts— tap, long-press, drag, pinch, edge-swipe detectionMobileActionGrid.test.ts— tile rendering, cost formatting, context awarenessMobileDetector.test.ts— device detection, orientation, safe area parsingMobileResearchPanel.test.ts— tech tree rendering, category filteringMobileUIStateSync.test.ts— game tick synchronization, topbar updatesMobileViewportProfile.test.ts— viewport classification, token generationManual QA (see
MOBILE-GESTURE-HAPTIC-QA-MATRIX.md):📋 Complete Feature List
Core Gameplay Actions
✅ Tile Selection: Tap any tile to open context-aware ActionGrid
✅ Ground Attack: Tap enemy tile → "Ground Attack" in ActionGrid
✅ Naval Assault: Tap enemy water tile → "Naval Assault" in ActionGrid
✅ Paratroopers: Tap enemy tile → "Paratroopers" in ActionGrid (requires research)
✅ Bomber Run: Tap enemy tile → "Bomber Run" in ActionGrid (requires research)
✅ Nuclear Strike: Tap enemy tile → "Nuke (Artillery)" / "Nuke (ICBM)" (requires silo + research)
✅ Declare War: Tap enemy tile → "Declare War" in ActionGrid
✅ Spawn: Tap unclaimed land during spawn phase
Building & Structures
✅ Build Structures: Tap own tile → ActionGrid shows buildable structures (Barracks, Factory, Port, etc.)
✅ Build Naval Units: Tap own water tile → "Warship" / "Submarine" (requires Port)
✅ Build Fighter Jet: Tap own tile → "Fighter Jet" (requires Airfield + Jet Engines research)
✅ Build Artillery: Tap own tile → "Artillery" (requires Factory + research)
✅ Stack/Upgrade Structures: Toggle stack mode in ActionGrid, tap structures to upgrade
Diplomacy
✅ Alliance Request: Tap enemy tile → "Propose Alliance" in ActionGrid
✅ Break Alliance: Tap allied tile → "Break Alliance" in ActionGrid
✅ Request Peace: Tap enemy-at-war tile → "Request Peace" in ActionGrid
✅ Alliance Notifications: Auto-shown alliance request/extension warning toasts with accept/reject buttons
Economy & Resources
✅ Troop/Worker Ratio: Adjustable via
MobileEconomyOverlayslider (long-press map or Economy tab)✅ Attack Ratio: Adjustable via
MobileEconomyOverlayslider✅ Investment Sliders: Production, Road, Research sliders in
MobileEconomyOverlay✅ Economy Lock Toggles: Prevent accidental slider changes during critical moments
✅ Population & Gold Display: Always visible in
MobileTopBar✅ Game Clock: Always visible in
MobileTopBar(counts after spawn phase)✅ Trade Income Indicator: Auto-shown trade bubbles in
MobileAttackBaron income ticksIntelligence & Communication
✅ Leaderboard:
MobileIntelSidebarPlayers tab (tap Intel button or edge-swipe left)✅ Team Leaderboard:
MobileIntelSidebarTeams tab✅ Events Log:
MobileIntelSidebarEvents tab✅ Player Info: Long-press any player-owned tile →
MobilePlayerToastwith stats and actions✅ Chat: Open chat modal via player toast → chat button
✅ Emoji: Open emoji picker via player toast → emoji button or ActionGrid emoji tile
✅ Chat/Emoji Bubbles: Auto-shown in
MobileChatEmojiBarwhen messages arrive✅ Donate Troops: Long-press player tile → donate troops button in player toast
✅ Donate Gold: Long-press player tile → donate gold button in player toast
Research & Technology
✅ Research Toggle:
MobileResearchSidebar(tap Research button or edge-swipe right)✅ Research Priority Selection:
MobileResearchPriorityModalfor category prioritization✅ Tech Tree: Full tech tree display in
MobileResearchPanelwith category tabs✅ Tech Unlock Notifications: Auto-shown
MobileTechUnlockToaston research completionControls & Navigation
✅ Pan Map: Touch-drag anywhere on map (via
GestureDetector)✅ Zoom In/Out: Pinch-to-zoom gesture or tap zoom +/− buttons (left side)
✅ Center Camera: Tap center button (left side) to recenter on your territory
✅ Edge Swipe Left: Swipe from left edge → toggle Intel sidebar
✅ Edge Swipe Right: Swipe from right edge → toggle Research sidebar
Attack & Battle Feedback
✅ Attack Notifications: Auto-shown attack bubbles in
MobileAttackBarwith troop counts and timers✅ Incoming Attacks: Red bubbles show incoming attacks with tap-to-focus
✅ Outgoing Attacks: Blue/green bubbles show your attacks with tap-to-cancel
✅ Naval Units: Boat icons in attack bar for active naval assaults
✅ Airstrike Indicators: Paratrooper/bomber icons in attack bar during airborne attacks
Settings & Game Management
✅ Settings Panel:
MobileSettingsSidebar→MobileSettingsPanelwith all game settings✅ Haptic Toggle: Enable/disable vibration feedback
✅ Replay Controls: Save replay, download replay, copy replay URL
✅ Exit Game: Quit to lobby (confirmation dialog included)
✅ Win/Loss Modal:
MobileWinModalshows game-over stats, replay options, Discord inviteResponsive Scaling
✅ Compact Landscape Phones: ActionGrid uses tighter tokens to preserve map visibility
✅ Regular Landscape Phones: ActionGrid applies medium compaction
✅ Large Tablet Profiles: ActionGrid receives tablet readability bump (larger tiles/icons/text)
✅ Portrait Orientation: All overlays and ActionGrid adapt to portrait aspect ratios
✅ Baseline Reference: iPhone 14 Pro Max emulation (
430x932) as no-regression reference✅ Tablet Activation: iPad Air/Pro devices enter mobile UI path reliably
Haptic Feedback (Configurable)
✅ Tap Feedback: 10ms vibration on button taps, toggles, menu opens
✅ Long Press Feedback: 50ms vibration on long-press trigger
✅ Success Feedback: 15ms vibration on build/attack/diplomacy confirmations
✅ Warning Feedback: 30ms vibration on warnings and confirmations
✅ Error Feedback: 100ms vibration on invalid actions or locked tiles
✅ Edge Swipe Feedback: 25ms vibration on sidebar swipe triggers
🎨 Mobile Lobby Industrial Styling (Separate Commit)
The second commit (
feat(mobile): Mobile lobby industrial styling) applies a mobile-optimized industrial aesthetic to the lobby screens (game creation, user settings, map selection).What Changed:
resources/images/mobile-bg-grey.png)Files Modified:
src/client/index.html— Inline lobby CSS rewrite with industrial styling (1128 lines added)src/client/GameStartingModal.ts— New modal component for "Game Starting" countdown screensrc/client/UserSettingModal.ts— Mobile-optimized settings modal with larger inputssrc/client/components/Maps.ts— Map selection grid with touch-friendly tilesresources/images/mobile-bg-grey.png— Mobile-optimized background texture (1.8MB PNG)Why Separate Commit?
This commit is kept separate from the main mobile UI implementation because:
📊 Statistics
Code Metrics
src/client/mobile/docs/mobile/(661 lines)Component Breakdown
Device Compatibility
🔗 Related Documentation
Comprehensive technical documentation lives in
docs/mobile/:🚀 Testing & Validation
Unit Tests
Run mobile unit tests:
npm test -- tests/mobile/All tests passing:
GestureDetector.test.ts(90 lines)MobileActionGrid.test.ts(113 lines)MobileDetector.test.ts(93 lines)MobileResearchPanel.test.ts(68 lines)MobileUIStateSync.test.ts(177 lines)MobileViewportProfile.test.ts(88 lines)Manual Testing Checklist
See
docs/mobile/MOBILE-GESTURE-HAPTIC-QA-MATRIX.mdfor complete QA matrix.Devices Tested:
Key Scenarios Verified:
🎯 Commit Structure
This PR contains two sequential commits that can be merged together or separately:
Commit 1:
feat(mobile): Implement mobile UI(abf1e39)The Core Implementation
Impact: Enables mobile gameplay
Commit 2:
feat(mobile): Mobile lobby industrial styling(9baffa4)Optional Visual Polish
Impact: Visual enhancement (can be reverted without affecting mobile gameplay)
✨ Summary
This PR unlocks full mobile support for Terratomic, bringing the complete PC strategy experience to touchscreen devices. The implementation prioritizes:
The mobile UI runs in parallel with the desktop interface, sharing game logic and network code while providing a completely redesigned presentation layer optimized for touch.
Please complete the following:
Please put your Discord username so you can be contacted if a bug or regression is found:
el_magico777