name: Dongshan Next Map Development description: Expert guide for developing the Dongshan Next Map LBS game, covering 3-layer architecture, Zustand state management, custom Systems (LBS, Save, Quest), and HUD development.

Dongshan Next Map Development Guidelines

This skill codifies the architectural patterns and systems of the Dongshan Next Map project. Follow these guidelines strictly to ensure code consistency and system stability.

🏗️ Architecture Overview

The project uses a strict 3-Layer Architecture.

graph TD
    UI[UI/HUD Layer] -->|Reads| State[State Layer]
    UI -->|Calls| Systems[Systems Layer]
    Systems -->|Reads/Writes| State
    Systems -->|Uses| API[API Layer]
    API -->|Queries| DB[Database Layer]

1. UI/HUD Layer (Presentation)

• Location: src/components/hud/
• Role: Pure presentation. NO complex logic.
• Rules:
  • Use fixed positioning for HUD overlays.
  • Set pointer-events: none on containers, auto on interactive elements.
  • Read data ONLY from Zustand stores.
  • NEVER directly modify Three.js objects; update store state instead.

2. Systems Layer (Logic)

• Location: src/systems/
• Role: Reusable business logic and calculations.
• Pattern: Static Classes with pure functions where possible.
• Key Systems:
  • LBSManager: GPS <-> Three.js coordinate conversion.
  • InteractionSystem: Click detection and proximity triggers.
  • SaveSystem: LocalStorage and Cloud sync.
  • QuestSystem: Quest tracking and rewards.
  • InventorySystem: Item management.

3. State Layer (Data)

• Location: src/store/
• Role: Single source of truth.
• Tech: Zustand + Persist middleware.
• Stores:
  • playerStore: User progress, inventory, stats.
  • gameStore: Scenarios, levels, active models, quests.
  • uiStore: Dialogs, menus, notifications.
  • locationStore: GPS coordinates, map state.

🛠️ Development Patterns

1. Adding a New Quest

To add a quest, you typically work with QuestSystem and gameStore.

import { QuestSystem } from '@/systems/QuestSystem';

// In a logic controller or initial load
QuestSystem.startQuest({
  id: 'quest_id',
  title: 'Quest Title',
  description: 'Quest Description',
  objectives: [
    {
      id: 'obj_1',
      description: 'Collect 5 items',
      type: 'collect', // or 'talk', 'explore'
      total: 5,
      progress: 0,
      completed: false
    }
  ],
  rewards: {
    experience: 100,
    coins: 50
  }
});

2. Handling Interactions

Do not write interaction logic in components. Use InteractionSystem.

import { InteractionSystem } from '@/systems/InteractionSystem';

// In your 3D component (e.g., inside an onClick handler)
const handleClick = () => {
  InteractionSystem.handleModelClick(modelId, userLocation);
};

3. Creating UI Components

Follow the HUD pattern to ensure separation from 3D.

// src/components/hud/MyNewPanel.tsx
import { useUIStore } from '@/store/uiStore';

export default function MyNewPanel() {
  const isOpen = useUIStore(s => s.isMyPanelOpen);
  
  if (!isOpen) return null;

  return (
    <div className="fixed inset-0 z-50 pointer-events-none flex justify-center items-center">
        <div className="pointer-events-auto bg-black/80 p-4 rounded text-white">
            {/* Content */}
        </div>
    </div>
  );
}

4. Coordinate Conversion

ALWAYS use LBSManager for positioning.

import { LBSManager } from '@/systems/LBSManager';

// Convert GPS to scene position
const position = LBSManager.latLngToXYZ(lat, lng, altitude);

⚠️ Critical Rules

1. NO useState for Global State: If data needs to be shared or persisted, put it in a Zustand store.
2. Separate UI from 3D: 2D UI elements should rarely be HTML/CSS overlays, not generic HTML inside Three.js Canvas unless using regular HTML overlays is impossible.
3. Static Systems: Keep systems stateless. They should read from stores and accept arguments.
4. Type Safety: Always define interfaces for new data structures in src/types/.

📚 Reference

• Mapbox Integration: src/components/MapBase.tsx
• 3D Layers: src/components/3d/Game3DLayers.tsx
• Store Definitions: src/store/*.ts
• System Implementations: src/systems/*.ts