添加 CLAUDE.md 文件以提供项目指导和架构说明
This commit is contained in:
ytc1012
9
.claude/settings.local.json
Normal file
9
.claude/settings.local.json
Normal file
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"permissions": {
|
||||||
|
"allow": [
|
||||||
|
"Bash(cat:*)"
|
||||||
|
],
|
||||||
|
"deny": [],
|
||||||
|
"ask": []
|
||||||
|
}
|
||||||
|
}
|
||||||
176
CLAUDE.md
Normal file
176
CLAUDE.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user