Rowland/EG
2
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ea6ff140e9
EG/PROJECT_OPTIMIZATION_ANALYSIS.md

13 KiB
Raw Blame History

PROJECT_OPTIMIZATION_ANALYSIS

基于本地代码静态扫描生成（不含远程仓库信息，不含 RenderPipelineFile/ 第三方目录）。

  • 分析时间: 2026-03-01
  • 扫描范围: main.py, Start_Run.py, core/, scene/, project/, ui/, ssbo_component/, TransformGizmo/, scripts/, tools/, templates/

0. 执行进展（非 VR）

  • 已完成 EditorContext 适配层：core/editor_context.py
  • 已接入文件：
    • core/event_handler.py
    • core/selection.py
    • core/InfoPanelManager.py
    • ui/panels/runtime_actions.py
    • core/terrain_manager.py
    • scene/scene_manager_convert_tiles_mixin.py
    • scene/scene_manager_serialization_mixin.py
    • scene/scene_manager_model_mixin.py
  • 效果（本地静态检索）：
    • 直接访问 world.interface_manager: 0
    • 直接访问 interface_manager.treeWidget: 0
    • 旧上下文引用已从“接口访问路径”转为“上下文适配层/兼容字段”模式
  • Task B 第二轮已落地（scene_manager_io_mixin.loadScene）：
    • 已抽出流程 helper：
      • _preflight_load_scene
      • _cleanup_after_failed_load
      • _clear_current_scene_for_load
      • _load_scene_root_from_file
      • _bootstrap_scene_tree_for_loaded_root
      • _load_scene_gui_metadata
      • _retry_load_scene
      • _walk_loaded_scene
      • _process_loaded_scene_node
      • _restore_node_scripts
      • _parse_vec3_string
      • _parse_color_string
    • loadScene 行数：556 -> 74
    • 已清理重复异常分支：_rebuildParentChildRelationships 内重复 except 已移除
  • main.py::__init__ 第一轮拆分已落地（非 VR）：
    • __init__ 行数：375 -> 27
    • 已抽出初始化阶段方法：
      • _configure_main_window
      • _init_legacy_compat_fields
      • _init_core_services_non_vr
      • _init_runtime_features_non_vr
      • _init_imgui_runtime
      • _init_panel_modules
      • _init_startup_fonts
      • _init_ui_runtime_state
      • _bind_runtime_events
      • _finalize_startup
  • 本轮新增深入分析结论（非 VR）：
    • ui/panels/animation_tools.py::_getActor 第一轮拆分已完成
    • 实测指标：510 -> 39 行，近似圈复杂度 191 -> 15，内嵌局部函数 9 -> 0
  • core/selection.py::updateGizmoDrag 第一轮拆分已完成：
    • 实测指标：278 -> 32 行，近似圈复杂度 65 -> 10
    • 缩放/旋转/平移逻辑已拆到独立 helper
  • ui/LUI/lui_manager_interaction.py::_update_drag 第一轮拆分已完成：
    • 实测指标：348 -> 28 行，近似圈复杂度 79 -> 7
    • Canvas/组件拖拽流程已拆到独立 helper
  • ui/panels/editor_panels_left.py::_draw_resource_manager 保留布局版拆分已完成：
    • 实测指标：310 -> 23 行（第一轮 310 -> 163，第二轮 163 -> 23）
    • 目录/文件项渲染、展开内容、右键菜单流程已拆到独立 helper

1. 总体画像

  • Python 文件: 147
  • 代码总行数: 58,341
  • except Exception / except: 总计: 949
  • 裸 except: 总计: 62
  • 旧上下文关键词引用总量:
    • interface_manager: 20
    • treeWidget: 2
    • gui_manager: 90

结论:

  • Qt 依赖已清理后，当前主要技术债集中在三类:
    • 过大函数（可维护性差）
    • 异常处理过宽（问题可观测性差）
    • 旧 GUI 上下文命名耦合（边界不清晰）

2. 热点文件（按规模/风险）

2.1 超大文件 Top（非 VR）

  1. core/selection.py (2941 行)
  2. core/InfoPanelManager.py (1725 行)
  3. ui/LUI/lui_manager_editor.py (1724 行)
  4. ui/panels/property_helpers.py (1711 行)
  5. ui/LUI/lui_function_properties.py (1707 行)
  6. TransformGizmo/rotate_gizmo.py (1587 行)
  7. ui/panels/animation_tools.py (1579 行)
  8. templates/main_template.py (1571 行)

2.2 长函数 Top（优先拆分，非 VR 当前状态）

  1. ui/LUI/lui_function_properties.py::_draw_component_properties (1441 行)
  2. ui/LUI/lui_manager_interaction.py::_handle_resize_drag (257 行)
  3. ui/LUI/lui_manager_editor.py::_set_parent_child_relationship (234 行)
  4. ui/panels/editor_panels_top.py::draw_menu_bar (227 行)
  5. scene/scene_manager_io_mixin.py::saveScene (222 行)
  6. TransformGizmo/move_gizmo.py::_on_mouse_down (222 行)
  7. ui/LUI/lui_manager_editor.py::draw_editor (217 行)

2.3 异常处理密度高（可观测性风险）

  1. ui/panels/animation_tools.py (except* = 85)
  2. core/selection.py (56)
  3. ui/panels/property_helpers.py (54)
  4. templates/main_template.py (39)
  5. scene/scene_manager_model_mixin.py (36)
  6. ui/LUI/lui_function_properties.py (36)
  7. ui/LUI/lui_manager_editor.py (33)
  8. core/world.py (28)
  9. scene/scene_manager_serialization_mixin.py (27)

裸 except: 集中区:

  • core/selection.py (7)
  • scene/scene_manager_model_mixin.py (7)
  • ui/panels/editor_panels_right_material.py (6)
  • ui/panels/editor_panels_left.py (5)

2.4 旧上下文耦合集中区（当前分布，非 VR）

  1. ui/panels/runtime_actions.py (gui_manager=25)
  2. core/event_handler.py (interface_manager=7, gui_manager=13)
  3. ui/panels/editor_panels_right.py (gui_manager=18)
  4. scene/scene_manager_serialization_mixin.py (gui_manager=13)
  5. scene/scene_manager_model_mixin.py (interface_manager=6)
  6. ui/panels/editor_panels_left.py (gui_manager=5)
  7. ui/panels/interaction_panels.py (gui_manager=5)

3. 优化优先级（建议执行顺序）

P0: 上下文收敛（已完成主干，继续收尾）

目标: 统一 GUI/场景树访问边界，减少跨模块 hasattr(..., 'interface_manager') 与 treeWidget 语义残留。

当前状态:

  1. EditorContext 已落地并完成第一批接入。
  2. 仍有 gui_manager/interface_manager 兼容字段引用集中在少量模块。

建议动作（收尾）:

  1. 将 runtime_actions 与 editor_panels_right 中 gui_manager 读写统一迁移到 editor_context 访问方法。
  2. 给 event_handler 与 scene_manager_serialization_mixin 增加“兼容字段缺失”单点兜底函数，移除重复 hasattr 防御分支。
  3. 文档层明确“兼容字段仅保留读，不再新增写路径”。

预期收益:

  • 降低命名残留与多处 hasattr 防御代码。
  • 后续模块拆分时边界更稳定。

P1: 大函数拆分（第二阶段）

目标: 将核心长函数拆分成“流程编排 + 子步骤函数”，减少单函数认知负担。

建议拆分顺序（非 VR 当前阶段）:

  1. ui/LUI/lui_function_properties.py::_draw_component_properties（可按“变换/布局/视觉/交互/脚本”分区）
  2. ui/LUI/lui_manager_interaction.py::_handle_resize_drag
  3. ui/panels/editor_panels_top.py::draw_menu_bar

预期收益:

  • 回归问题定位更快。
  • 面板和场景加载逻辑更易测试。

P2: 异常处理治理（并行推进）

目标: 将“吞异常”改为“有边界的降级 + 可追踪日志”。

建议规则:

  1. 禁止新增裸 except:。
  2. 高风险路径必须记录上下文:
    • 节点名/资源路径/操作类型/当前工具状态
  3. 对可恢复错误使用 warning，不可恢复错误返回显式失败值。

优先文件:

  • ui/panels/animation_tools.py
  • core/selection.py
  • ui/panels/property_helpers.py
  • scene/scene_manager_io_mixin.py

4. 下一步可直接执行的任务包

Task A（已完成）

  • 建立 core/editor_context.py（或同级命名）
  • 给 event_handler/selection/InfoPanelManager/runtime_actions 接入上下文
  • 保持外部 API 不变，仅替换内部访问路径

Task B（已完成）

  • 重构 scene_manager_io_mixin.loadScene：
    • preflight
    • clear_old_scene
    • load_bam
    • rebuild_scene_tree
    • post_load_sync

Task C（待执行，1 天）

  • 统一异常日志工具（轻量封装）
  • 首批替换 animation_tools.py 与 property_helpers.py

Task D（已完成，第一轮）

  • 重构 ui/panels/animation_tools.py::_getActor：
    • resolve_owner_and_model_path_tags
    • validate_or_evict_cached_actor
    • build_candidate_paths
    • try_actor_from_path
    • try_actor_from_memory
    • cache_and_tag_actor
  • 验收:
    • _getActor 长度降到 <= 170 行（实际 39 行）
    • 保持“文件路径优先，内存 autoBind 兜底”语义一致
    • 不改 VR 逻辑

Task E（已完成，第一轮）

  • 拆分 core/selection.py::updateGizmoDrag：
    • _apply_scale_drag
    • _apply_rotation_drag
    • _compute_axis_movement_distance
    • _apply_translation_drag
  • 验收:
    • 主函数长度降到 <= 120 行（实际 32 行）
    • 保持当前 gizmo 拖拽行为一致

Task F（已完成，保留布局版两轮）

  • 拆分 ui/panels/editor_panels_left.py::_draw_resource_manager
  • 验收:
    • 主函数长度降到 <= 160 行（第一轮 163 行，第二轮 23 行）
    • 保持原有布局/样式/文案/交互顺序不变

Task G（已完成，第一轮）

  • 拆分 ui/LUI/lui_manager_interaction.py::_update_drag
  • 验收:
    • 主函数长度降到 <= 140 行（实际 28 行）
    • 拖拽与缩放交互行为保持一致

Task H（推荐下一步，2-3 天）

  • 拆分 ui/LUI/lui_function_properties.py::_draw_component_properties
  • 验收:
    • 主函数长度降到 <= 260 行
    • 按“变换/布局/视觉/交互/脚本”子区块拆分并保持渲染逻辑一致

4.1 本轮深入分析（非 VR，P1 准备）

A) scene/scene_manager_io_mixin.py::loadScene（核心优先，已完成）

  • 函数规模: 74 行（重构前 556 行）
  • 近似圈复杂度（重构前）: 114
  • 关键问题:
    • processNode 内联逻辑已外提为 _walk_loaded_scene/_process_loaded_scene_node。
    • 重复异常分支已清理。
    • 仍存在较多调试输出（print 与注释 print），后续可做日志分级。
  • 建议拆分（保持外部 API loadScene 不变）:
    • _preflight_scene_file(filename) -> (ok, normalized_path, reason)
    • _cleanup_before_load(tree_widget, retry_count)
    • _load_bam_scene(filename) -> scene_or_none
    • _bootstrap_tree_items(scene, tree_widget)
    • _walk_loaded_scene(scene, tree_widget) -> loaded_nodes
    • _restore_loaded_nodes_state(node_path, processed_lights, loaded_nodes)（从 processNode 中抽）
    • _post_load_finalize(scene, loaded_nodes, filename)
    • _retry_load_scene(filename, retry_count, error) -> bool
  • 验收标准:
    • loadScene 主体压缩到 120 行以内，只保留流程编排。
    • 节点恢复行为（位置/材质/脚本/可见性）与当前一致。
    • 失败重试逻辑保持语义一致。
  • 当前状态（2026-03-01）:
    • 第二轮已完成（loadScene 已达验收目标：74 行）。
    • 后续建议转入回归观察，优先推进 ui/LUI/lui_function_properties.py::_draw_component_properties。

B) main.py::__init__（第二优先，已完成第一轮）

  • 函数规模: 27 行（重构前 375 行）
  • 状态:
    • 初始化编排已拆分为阶段方法，VR 初始化逻辑保持原样。
  • 约束:
    • 后续仅建议做微调，不再进行结构性拆分。

C) ui/panels/animation_tools.py::_getActor（已完成第一轮）

  • 函数规模: 39 行（重构前 510 行）
  • 近似圈复杂度: 15（重构前 191）
  • 已落地 helper:
    • _sync_owner_model_path_tags
    • _get_valid_cached_actor
    • _detect_animation_nodes
    • _collect_autobind_source_candidates
    • _try_memory_fallback_actor
    • _collect_actor_candidate_paths
    • _try_actor_from_path
  • 状态:
    • 入口函数已收敛为流程编排。
    • 已通过 python -m compileall ui/panels/animation_tools.py。

D) core/selection.py::updateGizmoDrag（已完成第一轮）

  • 函数规模: 32 行（重构前 278 行）
  • 近似圈复杂度: 10（重构前 65）
  • 已落地 helper:
    • _validate_gizmo_drag_state
    • _apply_scale_drag
    • _apply_rotate_drag
    • _compute_axis_movement_distance
    • _apply_translate_drag
  • 状态:
    • 主流程已收敛为编排入口。
    • 已通过 python -m compileall core/selection.py。

E) ui/panels/editor_panels_left.py::_draw_resource_manager（已完成两轮）

  • 函数规模: 23 行（重构前 310 行）
  • 近似圈复杂度: 已由主函数分支链路转移到子流程函数（入口仅保留编排）
  • 已落地 helper:
    • _update_resource_manager_window_rect
    • _draw_resource_toolbar_and_filters
    • _draw_resource_directory_entries
    • _draw_resource_directory_entry
    • _draw_resource_directory_children
    • _draw_resource_subdir_entry
    • _draw_resource_subfile_entry
    • _draw_resource_file_entries
    • _draw_resource_file_entry
    • _draw_resource_context_menu
  • 状态:
    • 主流程已收敛为编排入口，且保持原布局与交互顺序。
    • 已通过 python -m compileall ui/panels/editor_panels_left.py。

4.2 执行顺序建议（非 VR）

  1. loadScene 已完成两轮拆分（当前建议冻结并转入回归观察）。
  2. main.__init__ 已完成第一轮拆分（建议转入回归观察）。
  3. _update_drag 已完成第一轮拆分，建议转入回归观察。
  4. 下一步处理 _draw_component_properties（属性面板分区拆分）。
  5. 然后处理 _handle_resize_drag（拖拽缩放路径补充拆分）。

5. 与现有文档关系

  • 模块总索引: PROJECT_MODULE_INDEX.md
  • 项目任务清单: PROJECT_TASK_CHECKLIST.md
  • 历史分析: IMGUI_MODULE_ANALYSIS.md

如果按此路线继续，建议下一轮直接从 Task H 开始，先落地 _draw_component_properties 的分区拆分并保持行为不变。