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