WGameEngine 0.1

A Python game engine module designed for educational scenarios

WGameEngine

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

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

✨ 特性

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

🚀 快速开始

安装

pip install WGameEngine

基本用法

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)

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)

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)

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)

from WGameEngine.renderer import Window

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

输入系统 (input)

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)

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)

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)

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

📦 安装方式

从源码安装

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

# 安装依赖
pip install pygame pymunk pytmx

# 使用引擎
python your_game.py

作为模块导入

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 许可证。