Metadata-Version: 2.4
Name: WGameEngine
Version: 0.1
Summary: A Python game engine module designed for educational scenarios
Author-email: Walimaker Team <contact@walimaker.org>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Kylo94/WGameEngine
Project-URL: Documentation, https://github.com/Kylo94/WGameEngine#readme
Project-URL: Repository, https://github.com/Kylo94/WGameEngine.git
Project-URL: Bug Tracker, https://github.com/Kylo94/WGameEngine/issues
Keywords: game,engine,education,pygame,physics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Education
Classifier: Topic :: Games/Entertainment
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pygame>=2.6.0
Requires-Dist: pymunk>=6.6.0
Requires-Dist: pytmx>=3.30
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# WGameEngine

> 基于 ECS 架构的 Python 游戏引擎模块（内测版 0.1.0）

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Pygame](https://img.shields.io/badge/pygame-2.6.1-green.svg)](https://www.pygame.org)
[![Pymunk](https://img.shields.io/badge/pymunk-6.6.0-orange.svg)](https://www.pymunk.org)

WGameEngine 是一个基于 ECS（Entity-Component-System）架构设计的 Python 游戏引擎模块，提供完整的渲染、物理、音频、输入和资源管理系统。该引擎专注于模块化设计，可作为其他游戏框架的基础引擎。

## ✨ 特性

- 🏗️ **ECS 架构** - 基于 Entity-Component-System 的现代游戏引擎架构
- 🎮 **完整的引擎系统** - 渲染、物理、音频、输入、资源管理
- 📦 **模块化设计** - 清晰的模块分离，易于扩展和维护
- 🚀 **高性能** - 资源缓存机制，大幅提升加载速度
- 🎨 **丰富的组件系统** - SpriteRenderer、Animation、Camera、RigidBody、AudioSource 等
- 🖱️ **输入系统** - 完整的鼠标和键盘事件支持
- 🔊 **音频系统** - 音频管理和播放支持

## 🚀 快速开始

### 安装

```bash
pip install WGameEngine
```

### 基本用法

```python
from WGameEngine.core import Engine
from WGameEngine.renderer import Window
from WGameEngine.ecs import Entity, Scene, SceneManager
from WGameEngine.components import SpriteRenderer, Transform

# 创建引擎实例
engine = Engine()

# 初始化引擎
engine.initialize(width=800, height=600, title="My Game", fps=60)

# 创建场景
scene_manager = engine.scene_manager
scene = scene_manager.create_scene("main")
scene_manager.set_scene_direct(scene)

# 创建实体
entity = Entity("player")
entity.add_component(Transform(position=(100, 100)))

# 添加精灵渲染器
sprite_data = SpriteData("player.png")
renderer = SpriteRenderer(sprite_data)
entity.add_component(renderer)

# 添加到场景
scene.add_entity(entity)

# 游戏主循环
while engine.is_running:
    engine.update()
```

## 📖 核心模块

### 引擎核心 (core)

```python
from WGameEngine.core import Engine

engine = Engine()
engine.initialize(width=800, height=600, title="Game", fps=60)

# 获取引擎子系统
window = engine.window          # 窗口管理
scene_manager = engine.scene_manager  # 场景管理
resource_manager = engine.resource_manager  # 资源管理
input_manager = engine.input_manager  # 输入管理
physics_space = engine.physics_space  # 物理系统
audio_manager = engine.audio_manager  # 音频管理
```

### ECS 系统 (ecs)

```python
from WGameEngine.ecs import Entity, Scene, SceneManager, Component, Transform

# 创建实体
entity = Entity("player")
transform = Transform(position=(100, 100))
entity.add_component(transform)

# 创建场景
scene_manager = SceneManager()
scene = scene_manager.create_scene("main")
scene.add_entity(entity)
scene_manager.set_scene_direct(scene)
```

### 组件系统 (components)

```python
from WGameEngine.components import SpriteRenderer, Animation, Camera, RigidBody, AudioSource
from WGameEngine.data import SpriteData, AnimationData

# 精灵渲染器组件
sprite_data = SpriteData("character.png")
renderer = SpriteRenderer(sprite_data)

# 动画组件
animation_data = AnimationData("walk", frames=["frame1.png", "frame2.png"])
animation = Animation(animation_data)

# 相机组件
camera = Camera(width=800, height=600)

# 物理刚体组件
rigid_body = RigidBody(body_type=RigidBody.DYNAMIC, collider_type=ColliderType.BOX, collider_size=(50, 50))

# 音频源组件
audio_source = AudioSource("sound.wav")
```

### 渲染系统 (renderer)

```python
from WGameEngine.renderer import Window

window = Window(width=800, height=600, title="Game", fps=60)
window.clear((0, 0, 0))  # 清空屏幕为黑色
window.refresh()          # 刷新显示
```

### 输入系统 (input)

```python
from WGameEngine.input import InputManager, KeyboardState, MouseState

input_manager = InputManager()
keyboard = input_manager.keyboard
mouse = input_manager.mouse

# 键盘输入
if keyboard.is_pressed("space"):
    print("空格键按下")

# 鼠标输入
mouse_position = mouse.position
if mouse.is_pressed(1):  # 左键
    print("鼠标左键按下")
```

### 物理系统 (physics)

```python
from WGameEngine.physics import PhysicsSpace

physics_space = PhysicsSpace()
physics_space.initialize()
physics_space.gravity = (0, -100)  # 设置重力

# 添加刚体
rigid_body = RigidBody(body_type=RigidBody.DYNAMIC)
physics_space.add_body(rigid_body.body)
```

### 音频系统 (audio)

```python
from WGameEngine.audio import AudioManager
from WGameEngine.data import AudioClip

audio_manager = AudioManager()
audio_clip = AudioClip("music.mp3")
audio_manager.play(audio_clip, loop=True)
```

### 资源管理 (resources)

```python
from WGameEngine.resources import ResourceManager

resource_manager = ResourceManager()
image = resource_manager.load_image("character.png")
font = resource_manager.load_font("font.ttf", size=24)
audio = resource_manager.load_audio("sound.wav")
```

## 📁 项目结构

```
WGameEngine/
├── __init__.py          # 包入口（版本信息）
├── core/
│   ├── __init__.py      # 引擎核心
│   ├── engine.py        # 主引擎类
├── data/
│   ├── __init__.py      # 数据类
│   ├── sprite.py        # Sprite数据
│   ├── animation.py     # Animation数据
│   ├── audio.py         # Audio数据
├── renderer/
│   ├── __init__.py      # 渲染系统
│   ├── window.py        # 窗口管理
├── input/
│   ├── __init__.py      # 输入系统
│   ├── input_manager.py  # 输入管理器
│   ├── keyboard.py      # 键盘状态
│   ├── mouse.py         # 鼠标状态
├── resources/
│   ├── __init__.py      # 资源管理
│   ├── resource_manager.py  # 资源管理器
│   ├── lru_cache.py      # LRU缓存
├── ecs/
│   ├── __init__.py      # ECS核心
│   ├── entity.py        # 实体类
│   ├── scene.py         # 场景类
│   ├── scene_manager.py  # 场景管理器
│   ├── component.py     # 组件基类
│   ├── transform.py     # 变换组件
├── components/
│   ├── __init__.py      # 组件系统
│   ├── sprite_renderer.py  # 精灵渲染器
│   ├── animation.py     # 动画组件
│   ├── camera.py        # 相机组件
│   ├── rigid_body.py    # 刚体组件
│   ├── audio_source.py  # 音频源组件
│   ├── collision_detector.py  # 碰撞检测器
├── physics/
│   ├── __init__.py      # 物理系统
│   ├── space.py         # 物理空间
├── audio/
│   ├── __init__.py      # 音频系统
│   ├── audio_manager.py  # 音频管理器
├── tests/
│   ├── __init__.py      # 测试模块
│   ├── test_*.py        # 单元测试
```

## 🔧 依赖要求

- Python 3.8+
- Pygame >= 2.6.0
- Pymunk >= 6.6.0
- PyTMX >= 3.30

## 📦 安装方式

### 从源码安装

```bash
# 克隆仓库
git clone https://github.com/Kylo94/WGameEngine.git
cd WGameEngine

# 安装依赖
pip install pygame pymunk pytmx

# 使用引擎
python your_game.py
```

### 作为模块导入

```python
import WGameEngine.core as engine
import WGameEngine.renderer as renderer
import WGameEngine.ecs as ecs
```

## 📋 版本说明

### v0.1.0 - 内测版

**核心功能：**
- ECS（Entity-Component-System）架构
- 完整的渲染系统（Window）
- 物理系统（基于 Pymunk）
- 音频管理系统
- 输入系统（键盘和鼠标）
- 资源管理系统（缓存优化）
- 组件系统（SpriteRenderer、Animation、Camera、RigidBody、AudioSource）

**模块化设计：**
- 清晰的模块分离，易于扩展
- 可作为其他游戏框架的基础引擎
- 完整的单元测试覆盖

## 📄 许可证

本项目采用 MIT 许可证。
