Skip to content

Commit 2bf4230

Browse files
AlianBlankAlianBlank
committed
[增加] README_EN
1 parent aa20467 commit 2bf4230

1 file changed

Lines changed: 282 additions & 0 deletions

File tree

‎README_EN.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
<div align="center">
2+
3+
# GameFrameX
4+
5+
**High-Performance, Cross-Platform Game Server Framework**
6+
7+
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
8+
[![.NET](https://img.shields.io/badge/.NET-8.0-purple.svg)](https://dotnet.microsoft.com/download/dotnet/8.0)
9+
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
10+
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
11+
12+
English | [简体中文](README.md)
13+
14+
</div>
15+
16+
## 📖 Introduction
17+
18+
GameFrameX is a high-performance game server framework developed with C# .NET 8.0, designed with the Actor model and supporting cross-platform deployment. The framework features built-in hot update mechanisms and can meet the requirements of most game types, especially suitable for collaborative development with Unity3D.
19+
20+
**Design Philosophy: Simplicity is the ultimate sophistication**
21+
22+
## ✨ Core Features
23+
24+
### 🚀 High-Performance Architecture
25+
- **Actor Model**: High-performance Actor system built on TPL DataFlow
26+
- **Full Asynchronous Programming**: Uses async/await patterns for clean and elegant code
27+
- **Lock-Free Design**: Avoids performance loss from traditional locking mechanisms through Actor model
28+
- **Memory Optimization**: Automatic recycling of inactive data to reduce memory usage
29+
30+
### 🔄 Hot Update Support
31+
- **Zero-Downtime Updates**: Supports runtime hot updates of game logic
32+
- **State-Logic Separation**: State persistence with hot-updatable logic
33+
- **Safe and Reliable**: Rollback capability on update failure to ensure service stability
34+
- **Incremental Updates**: Only updates modified parts for improved efficiency
35+
36+
### 🌐 Network Communication
37+
- **Multi-Protocol Support**: TCP, UDP, WebSocket, HTTP
38+
- **High Concurrency**: Asynchronous I/O model based on SuperSocket
39+
- **Message Processing**: Built-in message fragmentation and sticky packet handling
40+
- **Secure Transmission**: SSL/TLS encryption support
41+
42+
### 💾 Data Persistence
43+
- **Transparent Persistence**: Automatic serialization/deserialization, developers don't need to worry about database operations
44+
- **NoSQL Support**: Uses MongoDB by default, supports other NoSQL databases
45+
- **Caching Mechanism**: Intelligent caching strategy to improve data access performance
46+
47+
### ⏰ Scheduled Tasks
48+
- **Multiple Timers**: One-time, periodic, and scheduled tasks
49+
- **Thread Safety**: Built-in thread-safe Timer and Scheduler
50+
- **Event System**: Complete event-driven architecture
51+
52+
## 🏗️ Architecture Design
53+
54+
```
55+
┌─────────────────────────────────────────────────────────────┐
56+
│ Client Layer │
57+
├─────────────────────────────────────────────────────────────┤
58+
│ Network Layer │
59+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
60+
│ │ TCP │ │ WebSocket │ │ HTTP │ │
61+
│ └─────────────┘ └─────────────┘ └─────────────┘ │
62+
├─────────────────────────────────────────────────────────────┤
63+
│ Message Layer │
64+
│ ┌─────────────────────────────────────────────────────────┐ │
65+
│ │ Message Handlers │ │
66+
│ └─────────────────────────────────────────────────────────┘ │
67+
├─────────────────────────────────────────────────────────────┤
68+
│ Actor Layer │
69+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
70+
│ │ Player │ │ Server │ │ Account │ │
71+
│ │ Actor │ │ Actor │ │ Actor │ │
72+
│ └─────────────┘ └─────────────┘ └─────────────┘ │
73+
├─────────────────────────────────────────────────────────────┤
74+
│ Component Layer │
75+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
76+
│ │ Component │ │ Component │ │ Component │ │
77+
│ │ + State │ │ + State │ │ + State │ │
78+
│ └─────────────┘ └─────────────┘ └─────────────┘ │
79+
├─────────────────────────────────────────────────────────────┤
80+
│ Database Layer │
81+
│ ┌─────────────────────────────────────────────────────────┐ │
82+
│ │ MongoDB │ │
83+
│ └─────────────────────────────────────────────────────────┘ │
84+
└─────────────────────────────────────────────────────────────┘
85+
```
86+
87+
## 🚀 Quick Start
88+
89+
### Requirements
90+
91+
- [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
92+
- [MongoDB 4.x+](https://www.mongodb.com/try/download/community)
93+
- Visual Studio 2022 or JetBrains Rider
94+
95+
### Installation Steps
96+
97+
1. **Clone the Project**
98+
```bash
99+
git clone https://github.com/GameFrameX/GameFrameX.git
100+
cd GameFrameX/Server
101+
```
102+
103+
2. **Install Dependencies**
104+
```bash
105+
dotnet restore
106+
```
107+
108+
3. **Configure Database**
109+
- Start MongoDB service
110+
- Modify database connection string in configuration file
111+
112+
4. **Build and Run**
113+
```bash
114+
dotnet build
115+
dotnet run --project GameFrameX.Launcher
116+
```
117+
118+
5. **Verify Running**
119+
- Open Unity project
120+
- Run Launcher scene
121+
- Check console logs to confirm successful connection
122+
123+
## 📁 Project Structure
124+
125+
```
126+
GameFrameX.Server/
127+
├── GameFrameX.Apps/ # Application Layer (State Data)
128+
│ ├── Account/ # Account Module
129+
│ ├── Player/ # Player Module
130+
│ └── Server/ # Server Module
131+
├── GameFrameX.Hotfix/ # Hot Update Layer (Business Logic)
132+
│ ├── Logic/ # Business Logic
133+
│ └── StartUp/ # Startup Logic
134+
├── GameFrameX.Core/ # Core Framework
135+
│ ├── Actors/ # Actor System
136+
│ ├── Components/ # Component System
137+
│ └── Events/ # Event System
138+
├── GameFrameX.NetWork/ # Network Module
139+
├── GameFrameX.DataBase/ # Database Module
140+
├── GameFrameX.Config/ # Configuration Module
141+
└── GameFrameX.Launcher/ # Launcher
142+
```
143+
144+
## 🔧 Core Concepts
145+
146+
### Entity-Component-State Architecture
147+
148+
- **Entity**: Game entities (players, guilds, systems, etc.)
149+
- **Component**: Functional components (inventory, quests, combat, etc.)
150+
- **State**: State data (persistent data of components)
151+
152+
### Actor Model
153+
154+
Each Entity has a corresponding Actor, and all operations on Entity are performed through Actor to ensure thread safety:
155+
156+
```csharp
157+
// Get player component agent
158+
var playerAgent = await ActorManager.GetComponentAgent<PlayerComponentAgent>(playerId);
159+
160+
// Call component method (automatically queued, thread-safe)
161+
var result = await playerAgent.AddExp(1000);
162+
```
163+
164+
### Hot Update Mechanism
165+
166+
- **Apps Project**: Contains state data, not hot-updatable
167+
- **Hotfix Project**: Contains business logic, supports hot updates
168+
- **Proxy Pattern**: Implements logic-state separation through Agent proxy
169+
170+
## 📚 Development Guide
171+
172+
### Creating New Game Modules
173+
174+
1. **Define State Class** (Apps Project)
175+
```csharp
176+
public class BagState : StateBase
177+
{
178+
public List<Item> Items { get; set; } = new();
179+
public int MaxSlots { get; set; } = 100;
180+
}
181+
```
182+
183+
2. **Create Component Class** (Apps Project)
184+
```csharp
185+
public class BagComponent : StateComponent<BagState>
186+
{
187+
// Component initialization logic
188+
}
189+
```
190+
191+
3. **Implement Business Logic** (Hotfix Project)
192+
```csharp
193+
public class BagComponentAgent : StateComponentAgent<BagComponent, BagState>
194+
{
195+
public async Task<bool> AddItem(int itemId, int count)
196+
{
197+
// Business logic implementation
198+
return true;
199+
}
200+
}
201+
```
202+
203+
### Message Processing
204+
205+
```csharp
206+
[MessageMapping(typeof(ReqLogin))]
207+
public class LoginHandler : BaseMessageHandler
208+
{
209+
public override async Task<MessageObject> Action(MessageObject message)
210+
{
211+
var request = (ReqLogin)message;
212+
// Handle login logic
213+
return new RespLogin { Success = true };
214+
}
215+
}
216+
```
217+
218+
## 🔍 Performance Optimization
219+
220+
### Actor Design Principles
221+
222+
1. **Independence**: Minimize dependencies between Actors
223+
2. **Granularity Control**: Reasonably split Actors, avoid over-fragmentation
224+
3. **Avoid Deadlocks**: Follow hierarchical calling principles (lower level calls higher level)
225+
226+
### Memory Management
227+
228+
- Automatic recycling of inactive player data
229+
- Use object pools to reduce GC pressure
230+
- Reasonable cache strategy settings
231+
232+
## 🛠️ Deployment Guide
233+
234+
### Docker Deployment
235+
236+
```bash
237+
# Build image
238+
docker build -t gameframex .
239+
240+
# Run container
241+
docker run -d -p 8080:8080 gameframex
242+
```
243+
244+
### Production Environment Configuration
245+
246+
1. **Database Configuration**: Configure MongoDB cluster
247+
2. **Load Balancing**: Use Nginx or HAProxy
248+
3. **Monitoring and Alerting**: Integrate Prometheus + Grafana
249+
4. **Log Collection**: Use ELK or similar solutions
250+
251+
## 🤝 Contributing
252+
253+
We welcome all forms of contributions!
254+
255+
1. Fork this repository
256+
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
257+
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
258+
4. Push to the branch (`git push origin feature/AmazingFeature`)
259+
5. Create a Pull Request
260+
261+
## 📄 License
262+
263+
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
264+
265+
## 🔗 Related Links
266+
267+
- [📖 Detailed Documentation](https://gameframex.doc.alianblank.com)
268+
- [🎥 Video Tutorials](https://www.bilibili.com/video/BV1yrpeepEn7)
269+
- [🏠 Project Homepage](https://github.com/GameFrameX)
270+
- [💬 Community Discussions](https://github.com/GameFrameX/GameFrameX/discussions)
271+
272+
## 🙏 Acknowledgments
273+
274+
Thanks to all developers who have contributed to GameFrameX!
275+
276+
---
277+
278+
<div align="center">
279+
280+
**If this project helps you, please give us a ⭐**
281+
282+
</div>

0 commit comments

Comments
 (0)