添加 CLAUDE.md 文件以提供项目指导和架构说明
This commit is contained in:
ytc1012
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