# game_engine

**Repository Path**: ganyongDeveloperRoom/game_engine

## Basic Information

- **Project Name**: game_engine
- **Description**: 使用AI创建的游戏引擎
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-25
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# MyEngine 游戏引擎

MyEngine 是一个基于 Python 的轻量级现代游戏引擎，采用分层（Tier）架构设计，支持多线程渲染管线和物理模拟。

## ✨ 核心特性

- **分层架构**：逻辑层、视觉层、渲染层、GPU 层分离，各层独立运行
- **无锁消息队列**：层间通信使用无锁队列，提高并发性能
- **PBR 渲染管线**：支持延迟渲染，包括深度预通道、GBuffer 生成、光照计算、后处理等
- **脚本系统**：基于 Python 的实体组件脚本系统，支持生命周期管理
- **资源管理**：统一的资源加载与管理，支持网格、纹理、材质、着色器

## 📁 项目结构

```
myengine/
├── engine/                      # 引擎核心代码
│   ├── core/                    # 核心工具模块
│   │   ├── math.py              # 数学库（向量、四元数、矩阵运算）
│   │   ├── types.py             # 类型定义
│   │   └── logger.py            # 日志系统
│   ├── comm/                    # 通信模块
│   │   ├── double_buffer.py     # 双缓冲实现
│   │   ├── lockfree_queue.py    # 无锁队列
│   │   └── messages.py          # 消息定义
│   ├── scripting/               # 脚本系统
│   │   ├── script_base.py       # 脚本基类
│   │   ├── script_pool.py       # 脚本池
│   │   └── script_registry.py   # 脚本注册表
│   ├── threading/               # 线程管理
│   │   ├── thread_manager.py    # 线程管理器
│   │   ├── worker_loop.py       # 工作循环基类
│   │   └── event_sync.py        # 事件同步
│   ├── tiers/                   # 分层架构
│   │   ├── logic/               # 逻辑层 (L2)
│   │   │   ├── scheduler.py     # 逻辑调度器
│   │   │   ├── world_manager.py # 世界/实体管理
│   │   │   └── scripts.py       # 逻辑脚本（AI、玩家、物理）
│   │   ├── visual/              # 视觉层 (L1)
│   │   │   └── scheduler.py     # 视觉调度器
│   │   ├── render/              # 渲染层 (L2)
│   │   │   ├── pipeline.py      # 渲染管线
│   │   │   ├── scheduler.py     # 渲染调度器
│   │   │   ├── resource_manager.py # 资源管理
│   │   │   ├── render_context.py # 渲染上下文
│   │   │   ├── window.py        # 窗口管理
│   │   │   ├── phases/          # 渲染阶段
│   │   │   │   ├── depth_prepass_phase.py
│   │   │   │   ├── gbuffer_phase.py
│   │   │   │   ├── lighting_phase.py
│   │   │   │   ├── shadow_map_phase.py
│   │   │   │   ├── transparent_phase.py
│   │   │   │   ├── post_process_phase.py
│   │   │   │   ├── ui_phase.py
│   │   │   │   └── context_update_phase.py
│   │   │   └── scripts.py       # 渲染脚本（PBR、光照、调试）
│   │   └── gpu/                 # GPU 层 (L3)
│   │       ├── shader_compiler.py
│   │       ├── buffer_uploader.py
│   │       └── draw_caller.py
│   └── __init__.py
├── assets/                      # 资源目录
│   ├── meshes/                  # 网格模型
│   ├── textures/                # 纹理图片
│   └── shaders/                 # GLSL 着色器
├── main.py                      # 入口文件
└── requirements.txt             # 依赖
```

## 🚀 快速开始

### 环境要求

- Python 3.10+
- OpenGL 兼容驱动
- 依赖包：
  ```bash
  pip install -r requirements.txt
  ```

### 运行示例

```bash
python myengine/main.py
```

## 📖 核心概念

### 分层执行模型

引擎采用 3 层执行模型：

1. **视觉层 (L1)** - 处理视觉平滑、骨骼动画、位置插值
2. **逻辑层 (L2)** - 处理游戏逻辑、AI、输入、状态更新
3. **渲染层/物理层 (L3)** - 实际的渲染操作与物理计算

### 消息队列通信

各层之间通过 `LockFreeQueue` 进行异步通信：

```
L1 (视觉) → Queue → L2 (逻辑) → Queue → L3 (渲染)
                                    ↓
L1 ←─── Callback Queue ──────────────┘
```

### 脚本系统

引擎提供统一的脚本基类 `ScriptBase`，各层可扩展：

```python
class MyScript(LogicScript):
    def on_attach(self, init_payload: bytes):
        # 初始化
        pass
    
    def on_tick(self, delta_time: float):
        # 每帧更新
        pass
```

### 渲染管线

引擎使用延迟渲染管线，包含以下阶段：

1. **深度预通道 (Depth Prepass)** - 填充深度缓冲
2. **阴影图 (Shadow Map)** - 生成阴影
3. **GBuffer** - 填充几何信息（位置、法线、颜色等）
4. **光照 (Lighting)** - 光照计算
5. **透明物体 (Transparent)** - 透明物体渲染
6. **后处理 (Post-Process)** - 全屏效果
7. **UI** - 用户界面

### 资源管理

通过 `ResourceManager` 统一管理 GPU 资源：

- `load_mesh()` - 加载网格（支持 .obj 格式）
- `load_texture()` - 加载纹理
- `load_shader()` - 加载着色器
- `load_material()` - 加载/创建材质

## 🎮 内置脚本

### 逻辑层脚本

| 脚本名 | 功能描述 |
|--------|----------|
| `AIController` | 基础 AI 控制器 |
| `PhysicsBody` | 物理刚体行为 |
| `PlayerController` | 玩家输入控制 |

### 视觉层脚本

| 脚本名 | 功能描述 |
|--------|----------|
| `SmoothMove` | 平滑位置移动插值 |
| `SkeletalAnimator` | 骨骼动画系统 |

### 渲染层脚本

| 脚本名 | 功能描述 |
|--------|----------|
| `StandardPBR` | 标准 PBR 材质渲染 |
| `CameraController` | 相机控制 |
| `PointLight` | 点光源渲染 |
| `WireframeDebug` | 线框调试模式 |
| `AmbientController` | 环境光控制 |

## 🛠️ 开发指南

### 添加新脚本

1. 继承对应层的脚本基类
2. 使用 `@ScriptRegistry.register_script` 注册
3. 实现必要的生命周期方法

```python
from engine.tiers.logic.scripts import LogicScript
from engine.scripting.script_registry import ScriptRegistry
from engine.core.types import Tier

@ScriptRegistry.register_script(Tier.LOGIC, "MyCustomScript")
class MyCustomScript(LogicScript):
    def on_attach(self, init_payload: bytes):
        pass
    
    def on_tick(self, delta_time: float):
        pass
```

### 添加渲染阶段

1. 继承 `RenderPhaseBase`
2. 实现 `_begin`, `_invoke_script`, `_end` 方法
3. 注册到 `RenderPipeline`

## 📝 许可证

本项目采用 MIT 许可证开源。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！