EG/AGENTS.md

EG 项目概览与开发指南

项目简介

EG 是一个基于 Panda3D 引擎开发的 3D 编辑器和游戏引擎，集成了高级渲染管线、VR 支持、物理模拟、脚本系统等功能。该项目主要用于创建 3D 场景、游戏开发和交互式应用程序。

核心技术栈

• 渲染引擎: Panda3D 1.10.15 + RenderPipeline (延迟渲染、PBR材质)
• GUI框架: imgui_bundle + p3dimgui (用于编辑器界面)
• VR支持: OpenVR 2.2.0
• 脚本系统: Python 3.11
• 其他依赖: openvr, numpy, aiohttp, pyassimp, pillow 等

项目架构

核心模块

• main.py - 应用程序入口点，初始化所有系统
• Start_Run.py - 启动脚本，设置环境变量和路径
• core/ - 核心功能模块
  • world.py - 世界管理器，处理场景渲染和更新
  • selection.py - 选择系统，处理对象选择
  • event_handler.py - 事件处理系统
  • tool_manager.py - 工具管理器
  • script_system.py - 脚本系统
  • patrol_system.py - 巡逻系统
  • Command_System.py - 命令系统
  • terrain_manager.py - 地形管理
  • vr_manager.py - VR 功能管理
  • collision_manager.py - 碰撞检测管理
  • resource_manager.py - 资源管理
  • assembly_interaction.py - 装配交互
  • maintenance_gui.py - 维护界面
  • render_pipeline_utils.py - 渲染管线工具
  • InfoPanelManager.py - 信息面板管理
  • CustomMouseController.py - 自定义鼠标控制器

GUI 系统

• gui/gui_manager.py - GUI管理器，处理2D/3D界面元素
• ui/icon_manager.py - 图标管理器

场景管理

• scene/scene_manager.py - 场景管理器，处理模型导入、场景树构建
• scene/util.py - 场景工具函数

项目管理

• project/project_manager.py - 项目管理器，处理项目创建、保存、加载

脚本系统

• scripts/ - 包含各种预定义脚本
  • MoverScript.py - 移动脚本
  • RotatorScript.py - 旋转脚本
  • ScalerScript.py - 缩放脚本
  • ColorChangerScript.py - 颜色变化脚本
  • FollowerScript.py - 跟随脚本
  • BouncerScript.py - 弹跳脚本
  • ComboAnimatorScript.py - 组合动画脚本

VR 系统

• vr_actions/ - VR动作配置
  • actions.json - VR动作定义
  • bindings_*.json - 不同VR设备的绑定配置

资源管理

• Resources/ - 资源目录
  • models/ - 3D模型
  • textures/ - 纹理贴图
  • materials/ - 材质文件
  • animations/ - 动画文件
  • icons/ - 图标资源

渲染管线

• RenderPipelineFile/ - 高级渲染管线
  • rpcore/ - 渲染管线核心
  • rpplugins/ - 渲染插件
  • effects/ - 后处理效果
  • config/ - 渲染配置

启动和运行

环境要求

• Python 3.11
• Panda3D 1.10.15
• OpenVR 2.2.0 (VR功能)

运行方式

1. 直接运行主程序:

   python Start_Run.py
   

2. 带项目路径运行:

   python Start_Run.py /path/to/project
   

3. 从main.py运行:

   python main.py
   

配置文件

• config/vr_settings.json - VR渲染配置
• imgui.ini - ImGui界面配置
• .gitignore - Git忽略文件配置

开发约定

代码风格

• 使用UTF-8编码
• 遵循PEP 8代码规范
• 类名使用驼峰命名法
• 函数和变量使用下划线命名法
• 文件头部包含模块说明和导入信息

脚本开发

• 所有用户脚本应继承 ScriptBase 类
• 脚本文件放在 scripts/ 目录下
• 使用 ScriptManager 管理脚本生命周期
• 脚本API通过 world 对象提供

插件开发

• 插件系统支持动态加载
• 插件配置文件使用JSON格式
• 插件应实现标准接口

VR开发

• VR动作配置在 vr_actions/actions.json 中定义
• 支持多种VR设备（Vive、Oculus、Index）
• VR渲染配置在 config/vr_settings.json 中

构建和部署

依赖安装

pip install -r requirements/requirements.txt

测试

项目包含多个测试脚本：

• test_quick_script.py - 快速测试脚本
• TestMover.py - 移动测试
• TestRotator.py - 旋转测试
• TestScaler.py - 缩放测试

项目文件

• 项目配置使用JSON格式
• 项目文件包含场景、资源、脚本等信息
• 使用 ProjectManager 管理项目生命周期

常见问题

VR相关问题

1. 确保VR设备已正确连接
2. 检查OpenVR运行时是否安装
3. 验证VR动作配置是否正确

渲染问题

1. 检查显卡驱动是否最新
2. 确认RenderPipeline配置正确
3. 验证材质和纹理路径

性能优化

1. 使用合适的LOD设置
2. 优化场景复杂度
3. 调整渲染质量设置

扩展开发

添加新脚本

1. 在 scripts/ 目录创建新脚本文件
2. 继承 ScriptBase 类
3. 实现必要的方法
4. 通过 ScriptManager 注册脚本

添加新工具

1. 在 core/tool_manager.py 中注册新工具
2. 实现工具逻辑
3. 添加GUI界面元素

添加新渲染效果

1. 在 RenderPipelineFile/rpplugins/ 目录创建插件
2. 实现渲染逻辑
3. 添加配置选项

联系和支持

• 项目Git仓库: http://10.0.0.99:4000/Rowland/EG.git
• 当前分支: imgui
• 最新提交: 移除qt依赖 (33e62bd1e4)

---

该文档由iFlow CLI自动生成，最后更新时间: 2026年3月17日