From a0c371fbff61e17a1858d7e7268aab3c55050102 Mon Sep 17 00:00:00 2001
From: ytc1012 <18001193130@163.com>
Date: Wed, 19 Nov 2025 14:14:38 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20CLAUDE.md=20=E6=96=87?=
 =?UTF-8?q?=E4=BB=B6=E4=BB=A5=E6=8F=90=E4=BE=9B=E9=A1=B9=E7=9B=AE=E6=8C=87?=
 =?UTF-8?q?=E5=AF=BC=E5=92=8C=E6=9E=B6=E6=9E=84=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .claude/settings.local.json |   9 ++
 CLAUDE.md                   | 176 ++++++++++++++++++++++++++++++++++++
 2 files changed, 185 insertions(+)
 create mode 100644 .claude/settings.local.json
 create mode 100644 CLAUDE.md

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 0000000..fccd125
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cat:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..84fef28
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,176 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a **Cocos Creator 3D** strategy game client (SLG - Strategy/Simulation Game) for a Three Kingdoms-themed multiplayer game. The client is built with TypeScript and Cocos Creator 3.4.0, targeting both web-desktop and Windows platforms.
+
+## Build Commands
+
+The project uses Cocos Creator's built-in build system. Builds are generated through the Cocos Creator IDE (Project → Build menu):
+- Web Desktop builds: `build/web-desktop/`
+- Windows native builds: `build/windows/`
+
+## Architecture
+
+### Core Design Pattern: Command-Proxy Pattern
+
+The codebase follows a **Command-Proxy architecture** where:
+- **Command classes** handle business logic, network communication, and event responses
+- **Proxy classes** manage data models and state
+- **EventMgr** serves as the central event bus for cross-module communication
+
+Example module structure:
+```
+login/
+  ├── LoginCommand.ts    # Business logic & network handlers
+  ├── LoginProxy.ts      # Data model
+  └── LoginLogic.ts      # UI component logic
+```
+
+Key modules follow this pattern:
+- `login/` - Authentication and role creation
+- `map/` - Map rendering, tiles, cities, and buildings
+- `general/` - General (hero) management
+- `chat/` - Chat system
+- `map/ui/` - Map UI overlays
+
+### Network Communication
+
+**Dual-Protocol Architecture:**
+1. **WebSocket** ([NetManager.ts:4](assets/scripts/network/socket/NetManager.ts#L4)) - Primary game server communication
+   - Singleton pattern for connection management
+   - Message format: `{ name: string, msg: object, seq?: number }`
+   - Connected via `GameConfig.serverUrl`
+
+2. **HTTP REST** ([HttpManager.ts:4](assets/scripts/network/http/HttpManager.ts#L4)) - Secondary API calls
+   - Used for registration and supplementary operations
+   - Connected via `GameConfig.webUrl`
+
+**Server Configuration:**
+- WebSocket endpoint: Configured in [GameConfig.ts:9](assets/scripts/config/GameConfig.ts#L9)
+- HTTP endpoint: Configured in [GameConfig.ts:11](assets/scripts/config/GameConfig.ts#L11)
+- Both use nginx reverse proxy (see `mssg-client.conf`)
+- API definitions: [ServerConfig.ts](assets/scripts/config/ServerConfig.ts) and [HttpConfig.ts](assets/scripts/config/HttpConfig.ts)
+
+### Event System
+
+The [EventMgr.ts](assets/scripts/utils/EventMgr.ts) singleton provides:
+- `EventMgr.on(name, handler, target)` - Register listener
+- `EventMgr.emit(name, ...args)` - Trigger event
+- `EventMgr.off(name, handler, target)` - Remove specific listener
+- `EventMgr.targetOff(target)` - Remove all listeners for a target (always call in `onDestroy`)
+
+**Critical Pattern:** Always unregister events in cleanup:
+```typescript
+public onDestory(): void {
+    EventMgr.targetOff(this);
+}
+```
+
+### Application Lifecycle
+
+Entry point: [Main.ts](assets/scripts/Main.ts)
+
+1. Initialize network managers (NetManager, HttpManager)
+2. Initialize all Command singletons (Login, Map, MapUI, General, Army)
+3. Enter login scene
+4. After authentication → Load resources → Enter map scene
+5. Two main scenes coexist: MapScene (world) + MapUIScene (overlays)
+
+### Resource Loading
+
+[LoaderManager.ts](assets/scripts/core/LoaderManager.ts) handles sequential resource loading:
+- Supports both file and directory loading
+- Tracks progress with callbacks
+- Critical resources loaded before map entry:
+  - TiledMapAsset for world map
+  - JSON configs (facilities, generals, skills)
+  - SpriteFrames for character portraits
+
+### Map System Architecture
+
+**Multi-Proxy Pattern:**
+- [MapProxy.ts](assets/scripts/map/MapProxy.ts) - Base map, resources, area management
+- [MapCityProxy.ts](assets/scripts/map/MapCityProxy.ts) - City data
+- [MapBuildProxy.ts](assets/scripts/map/MapBuildProxy.ts) - Building/facility data
+
+**Area-Based Loading:**
+The map uses a grid-based area system where:
+- Large world divided into fixed-size areas
+- Areas loaded on-demand as player navigates (9-grid pattern)
+- `MapUtil` provides coordinate conversion utilities
+- Server query triggered via `nationMap_scanBlock`
+
+**Key Map Concepts:**
+- Cells: Individual tile positions (x, y coordinates)
+- Areas: Larger regions containing multiple cells
+- Resources: Collectible points (wood, iron, stone, grain)
+- Facilities: Player-built structures
+- Cities: Occupiable strategic locations
+
+### Data Configuration
+
+JSON configuration files in `assets/resources/config/`:
+- `basic.json` - Core game parameters
+- `mapRes_0.json` - Map resource spawn data
+- `json/facility/` - Building definitions by type
+- `json/general/` - Hero/general definitions
+- `json/skill/` - Skill definitions
+
+These are loaded as JsonAssets and parsed at runtime.
+
+## Code Conventions
+
+### File Organization
+- Logic components: `*Logic.ts` (UI behavior attached to nodes)
+- Command modules: `*Command.ts` (singletons handling business logic)
+- Proxy modules: `*Proxy.ts` (data models)
+- Config definitions: `config/*.ts` (static configuration)
+
+### Singleton Pattern
+Most managers use a standard singleton pattern:
+```typescript
+protected static _instance: ClassName;
+public static getInstance(): ClassName {
+    if (this._instance == null) {
+        this._instance = new ClassName();
+    }
+    return this._instance;
+}
+```
+
+### TypeScript Settings
+- `strict: false` - Strict type checking disabled
+- `allowSyntheticDefaultImports: true` - CommonJS interop enabled
+
+## Deployment Architecture
+
+The nginx configuration (`mssg-client.conf`) shows:
+- Static files served from `/root/mssg/slgclient/webdesktop`
+- WebSocket proxy: `/ws` → `127.0.0.1:8004`
+- HTTP API proxy: `/api/` → `127.0.0.1:8088/`
+- Port: 6060 (to avoid filing requirements)
+
+## Common Development Patterns
+
+### Adding a New Network API
+1. Define API name constant in `ServerConfig.ts`
+2. Register event handler in Command constructor: `EventMgr.on(ServerConfig.api_name, this.onApiResponse, this)`
+3. Create response handler method
+4. Create request sender method using `NetManager.getInstance().send()`
+
+### Creating UI Components
+1. Create prefab in Cocos Creator IDE
+2. Create `*Logic.ts` component script
+3. Use `@ccclass` and `@property` decorators
+4. Implement `onLoad()`, `start()`, `onDestroy()`
+5. Register/unregister EventMgr listeners appropriately
+
+### Handling State Updates
+1. Server pushes state changes via WebSocket
+2. Command receives via event handler
+3. Command updates Proxy data model
+4. Command emits UI update event
+5. Logic components react to event and refresh display