添加CLAUDE.md
This commit is contained in:
ytc1012
246
CLAUDE.md
Normal file
246
CLAUDE.md
Normal file
@@ -0,0 +1,246 @@
|
|||||||
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
This is a Three Kingdoms strategy game (SLG) server written in Go, featuring a microservices architecture with WebSocket-based real-time communication. The game includes army management, city building, coalition systems, and turn-based combat mechanics.
|
||||||
|
|
||||||
|
## Build Commands
|
||||||
|
|
||||||
|
Build all servers for Linux deployment:
|
||||||
|
```bash
|
||||||
|
cd shell
|
||||||
|
./build.bat # Cross-compiles for Linux even on Windows
|
||||||
|
```
|
||||||
|
|
||||||
|
Individual server builds (from project root):
|
||||||
|
```bash
|
||||||
|
go build -o bin/slgserver main/slgserver.go # Main game logic server
|
||||||
|
go build -o bin/loginserver main/loginserver.go # Authentication server
|
||||||
|
go build -o bin/chatserver main/chatserver.go # Chat/messaging server
|
||||||
|
go build -o bin/gateserver main/gateserver.go # Gateway/proxy server
|
||||||
|
go build -o bin/httpserver main/httpserver.go # HTTP API server
|
||||||
|
```
|
||||||
|
|
||||||
|
Run servers individually (from bin directory):
|
||||||
|
```bash
|
||||||
|
./slgserver # Port 8001
|
||||||
|
./loginserver # Port 8003
|
||||||
|
./chatserver # Port 8002
|
||||||
|
./gateserver # Port 8004
|
||||||
|
./httpserver # Port 8088
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
All configuration is in [data/conf/env.ini](data/conf/env.ini):
|
||||||
|
- Database connection settings (MySQL)
|
||||||
|
- Server ports and addresses
|
||||||
|
- XORM logging and SQL debugging
|
||||||
|
- WebSocket proxy routes for gateserver
|
||||||
|
- Server ID for multi-server support
|
||||||
|
|
||||||
|
Configuration is loaded via the `config` package using `spf13/viper`.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Microservices Structure
|
||||||
|
|
||||||
|
The system consists of 5 independent servers:
|
||||||
|
|
||||||
|
1. **slgserver** - Core game logic server handling:
|
||||||
|
- Army operations (conscription, movement, combat)
|
||||||
|
- City management (facilities, resources, building)
|
||||||
|
- Coalition/alliance systems
|
||||||
|
- National map and territory control
|
||||||
|
- General (hero) management and skills
|
||||||
|
|
||||||
|
2. **loginserver** - Authentication and session management:
|
||||||
|
- User login/logout with password hashing
|
||||||
|
- Session token generation and validation
|
||||||
|
- Server list for multi-server support
|
||||||
|
|
||||||
|
3. **chatserver** - Real-time messaging:
|
||||||
|
- Chat groups and channels
|
||||||
|
- Message queuing and delivery
|
||||||
|
- Broadcast notifications
|
||||||
|
|
||||||
|
4. **gateserver** - Gateway and routing:
|
||||||
|
- Central entry point for clients
|
||||||
|
- WebSocket proxy to backend services
|
||||||
|
- Connection lifecycle management
|
||||||
|
- Routes requests to slg/chat/login servers based on message prefix
|
||||||
|
|
||||||
|
5. **httpserver** - HTTP REST API (Gin framework):
|
||||||
|
- Alternative HTTP endpoints for web clients
|
||||||
|
- Account operations via REST
|
||||||
|
|
||||||
|
### WebSocket Message Protocol
|
||||||
|
|
||||||
|
All servers use a custom WebSocket message format defined in [net/conn.go](net/conn.go):
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Request
|
||||||
|
{
|
||||||
|
"seq": 12345, // Message sequence number
|
||||||
|
"name": "army.myList", // Route: <group>.<handler>
|
||||||
|
"msg": {...}, // Payload
|
||||||
|
"proxy": "slg" // Target service (for gateserver routing)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Response
|
||||||
|
{
|
||||||
|
"seq": 12345,
|
||||||
|
"name": "army.myList",
|
||||||
|
"code": 0, // Response code (0 = OK)
|
||||||
|
"msg": {...}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Message routing uses dot notation: `<group>.<handler>`. The router ([net/router.go](net/router.go)) supports:
|
||||||
|
- Grouped routes with middleware
|
||||||
|
- Per-route and per-group middleware
|
||||||
|
- Wildcard handlers (`*`)
|
||||||
|
|
||||||
|
### Data Layer Architecture
|
||||||
|
|
||||||
|
**Database**: MySQL accessed via XORM ORM ([db/conn.go](db/conn.go))
|
||||||
|
- Connection pooling with configurable limits
|
||||||
|
- Automatic database creation on first run
|
||||||
|
- SQL logging to file for debugging
|
||||||
|
|
||||||
|
**In-Memory Managers**: Core game state is cached in memory for performance:
|
||||||
|
- `mgr.AMgr` - Army manager ([logic/mgr/army_mgr.go](server/slgserver/logic/mgr/army_mgr.go))
|
||||||
|
- `mgr.RCMgr` - Role city manager
|
||||||
|
- `mgr.NMMgr` - National map manager
|
||||||
|
- `mgr.GMgr` - General manager
|
||||||
|
- `mgr.SkillMgr` - Skill manager
|
||||||
|
- `mgr.UnionMgr` - Coalition/alliance manager
|
||||||
|
|
||||||
|
Managers maintain indexed maps (by ID, by RID, by CityId) loaded at startup. Database writes happen via XORM but reads primarily from cache.
|
||||||
|
|
||||||
|
**Static Configuration**: JSON files loaded at startup:
|
||||||
|
- [data/conf/json/facility/](data/conf/json/facility/) - Building definitions
|
||||||
|
- [data/conf/json/general/](data/conf/json/general/) - Hero stats and attributes
|
||||||
|
- [data/conf/json/skill/](data/conf/json/skill/) - Skill effects
|
||||||
|
- [data/conf/json/basic.json](data/conf/json/basic.json) - Game constants
|
||||||
|
- [data/conf/json/map_build.json](data/conf/json/map_build.json) - Map structure
|
||||||
|
|
||||||
|
Loaded via `static_conf` package during `run.Init()`.
|
||||||
|
|
||||||
|
### Game Logic Patterns
|
||||||
|
|
||||||
|
**Model-Controller-Logic Pattern**:
|
||||||
|
- `model/` - Database entities with `ToProto()` methods
|
||||||
|
- `controller/` - WebSocket handlers, parse requests, validate
|
||||||
|
- `logic/` - Business logic, game rules, calculations
|
||||||
|
- `proto/` - Protocol buffers/data transfer objects
|
||||||
|
|
||||||
|
**Key Systems**:
|
||||||
|
|
||||||
|
1. **Army System** ([server/slgserver/logic/army_war.go](server/slgserver/logic/army_war.go)):
|
||||||
|
- Turn-based combat with 10 max rounds
|
||||||
|
- Position-based strategy (3 general positions per army)
|
||||||
|
- Attributes: force, defense, strategy, speed, destroy
|
||||||
|
- Facility bonuses from cities
|
||||||
|
- Battle results stored as war reports
|
||||||
|
|
||||||
|
2. **City/Facility System**:
|
||||||
|
- Cities have multiple facility slots
|
||||||
|
- Each facility type provides bonuses (TypeForce, TypeDefense, etc.)
|
||||||
|
- Upgrade system with resource costs and time delays
|
||||||
|
- Facilities loaded from JSON config
|
||||||
|
|
||||||
|
3. **General/Skill System**:
|
||||||
|
- Generals have arms (兵种), levels, experience
|
||||||
|
- Skills categorized: 主动 (active), 被动 (passive), 追击 (pursuit), 指挥 (command)
|
||||||
|
- Conscription system for recruiting troops
|
||||||
|
|
||||||
|
4. **Coalition System**:
|
||||||
|
- Player alliances with leadership structure
|
||||||
|
- Must load before other systems (dependency in `run.Init()`)
|
||||||
|
|
||||||
|
### Middleware Pipeline
|
||||||
|
|
||||||
|
WebSocket handlers support middleware ([middleware/](middleware/)):
|
||||||
|
- `ElapsedTime()` - Request timing
|
||||||
|
- `Log()` - Request/response logging
|
||||||
|
- `CheckLogin()` - Session validation (checks `uid` property on connection)
|
||||||
|
- `CheckRole()` - Role validation (checks `role` property)
|
||||||
|
- `CheckRid()` - Role ID validation
|
||||||
|
|
||||||
|
Middleware wraps handlers in reverse order (last added = innermost).
|
||||||
|
|
||||||
|
### Connection State Management
|
||||||
|
|
||||||
|
WebSocket connections ([net/conn.go](net/conn.go), [net/serverconn.go](net/serverconn.go)) maintain properties:
|
||||||
|
- `uid` - User ID (set after login)
|
||||||
|
- `role` - Role object (set after role selection)
|
||||||
|
- Properties stored in sync.Map for concurrent access
|
||||||
|
|
||||||
|
The `ConnMgr` singleton tracks all active connections.
|
||||||
|
|
||||||
|
## Development Workflow
|
||||||
|
|
||||||
|
1. **Modify game logic**: Edit files in `server/slgserver/logic/`
|
||||||
|
2. **Add new routes**: Register in `server/slgserver/run/init.go` → `initRouter()`
|
||||||
|
3. **Add new models**: Create in `model/`, implement `ToProto()`, add to manager
|
||||||
|
4. **Update static config**: Edit JSON files in `data/conf/json/`, reload on startup
|
||||||
|
5. **Database changes**: Models use XORM tags, schema auto-syncs if configured
|
||||||
|
|
||||||
|
## Server Initialization Order
|
||||||
|
|
||||||
|
Critical: The initialization sequence in [server/slgserver/run/init.go](server/slgserver/run/init.go) must be followed:
|
||||||
|
|
||||||
|
1. Test/create database (`db.TestDB()`)
|
||||||
|
2. Load static configs (facilities, generals, skills, etc.)
|
||||||
|
3. Set server ID from config
|
||||||
|
4. `logic.BeforeInit()` - Pre-initialization hooks
|
||||||
|
5. Load managers in dependency order:
|
||||||
|
- NMMgr (national map)
|
||||||
|
- UnionMgr (coalitions - **must load first**)
|
||||||
|
- RAttrMgr, RCMgr, RBMgr, RFMgr (role data)
|
||||||
|
- SkillMgr, GMgr (generals/skills)
|
||||||
|
- AMgr (armies - depends on generals)
|
||||||
|
6. `logic.Init()` and `logic.AfterInit()`
|
||||||
|
7. Register routers (only after full initialization)
|
||||||
|
|
||||||
|
## Common Patterns
|
||||||
|
|
||||||
|
**Getting a user's role from connection**:
|
||||||
|
```go
|
||||||
|
r, _ := req.Conn.GetProperty("role")
|
||||||
|
role := r.(*model.Role)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Accessing managers**:
|
||||||
|
```go
|
||||||
|
army, ok := mgr.AMgr.Get(armyId)
|
||||||
|
general, ok := mgr.GMgr.Get(rid, generalId)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Database operations with XORM**:
|
||||||
|
```go
|
||||||
|
// Query
|
||||||
|
db.MasterDB.Table(model.Army{}).Where("rid=?", rid).Find(&armies)
|
||||||
|
|
||||||
|
// Insert
|
||||||
|
db.MasterDB.Table(model.Army{}).Insert(army)
|
||||||
|
|
||||||
|
// Update
|
||||||
|
db.MasterDB.Table(model.Army{}).ID(armyId).Cols("soldiers").Update(army)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response codes**: Use constants from [constant/code.go](constant/code.go) (OK, DBError, InvalidParam, etc.)
|
||||||
|
|
||||||
|
## Multi-Server Support
|
||||||
|
|
||||||
|
The `logic.server_id` config enables running multiple game servers with separate databases. Table names are suffixed with server ID (e.g., `tb_role_1`).
|
||||||
|
|
||||||
|
## Deployment Notes
|
||||||
|
|
||||||
|
- Build script cross-compiles for Linux (CGO_ENABLED=0, GOOS=linux)
|
||||||
|
- Servers run independently, start all 5 for full functionality
|
||||||
|
- Gateserver acts as reverse proxy, client connects only to port 8004
|
||||||
|
- Configuration file must be in working directory or specify path
|
||||||
Reference in New Issue
Block a user