slgclient/CLAUDE.md

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) - 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) - Secondary API calls

   • Used for registration and supplementary operations
   • Connected via GameConfig.webUrl

Server Configuration:

• WebSocket endpoint: Configured in GameConfig.ts:9
• HTTP endpoint: Configured in GameConfig.ts:11
• Both use nginx reverse proxy (see mssg-client.conf)
• API definitions: ServerConfig.ts and HttpConfig.ts

Event System

The 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:

public onDestory(): void {
    EventMgr.targetOff(this);
}

Application Lifecycle

Entry point: 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 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 - Base map, resources, area management
• MapCityProxy.ts - City data
• 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:

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