Editor Architecture

Editor Architecture

This page keeps the editor/runtime architecture in the same static visual style as the PocketEngine landing page.

Documentation Back Home

What this covers

  • Runtime and editor frame flow
  • Asset and scene data movement
  • Source tree layering
  • Editor scene mutation workflow

Documentation split

  • documentation/: MkDocs Lua API pages
  • architecture/: static visual overview
  • /: project landing page

Source of truth

  • These diagrams are mirrored from the markdown files in docs/architecture/*.md
  • The site page is hand-authored HTML for stable visual control

Frame Pipeline

flowchart TD subgraph RuntimeHost["Runtime host frame"] R0["Poll SDL events"] --> R1["processPendingSceneLoad"] R1 --> R2["ProcessPendingOnStart"] R2 --> R3["ProcessOnUpdate"] R3 --> R4["ProcessOnLateUpdate"] R4 --> R5["Finalize pre-physics mutations"] R5 --> R6["Step physics + queue collisions"] R6 --> R7["Update particles"] R7 --> R8["Finalize end-of-frame mutations"] R8 --> R9["Render runtime target"] R9 --> R10["PresentFrame(true)"] R10 --> R11["Input::LateUpdate"] end subgraph EditorHost["Editor host frame"] E0["SyncRuntimeMirrorIfDirty"] --> E1["Poll SDL events"] E1 --> E2["EditorOverlay::ProcessEvent"] E2 --> E3["Engine::ProcessSDLEvent if not UI-captured"] E3 --> E4{"Mode"} E4 -->|Play| E5["RunSingleFrame"] E4 -->|Pause| E6["RunPresentPausedFrame"] E4 -->|Edit| E7["RunRenderFrozenFrame"] E5 --> E8["EditorOverlay::Render"] E6 --> E8 E7 --> E8 E8 --> E9["Panels emit SceneEditCommand / play controls"] E9 --> E10["EditorSceneSession handles commands"] E10 --> E11["PresentFrame(play advances only)"] end

Asset Pipeline

flowchart TD subgraph EnginePrivate[".engine"] EditorConfigFile[".engine/editor/editor.config"] EditorPrivateState[".engine/editor_private_state.json"] EditorSystemAssets[".engine/system/*"] end subgraph ProjectAssets["resources"] GameConfigFile["resources/game.config"] RenderingConfigFile["resources/rendering.config"] SceneFile["resources/scenes/*.scene"] TemplateFile["resources/actor_templates/*.template"] ComponentScripts["resources/component_types/*.lua"] Images["resources/images/*"] Fonts["resources/fonts/*"] Audio["resources/audio/*"] end GameConfigFile --> GameConfigData["GameConfigData"] RenderingConfigFile --> GameConfigData EditorConfigFile --> EditorConfigData["EditorConfigData"] EditorPrivateState --> SceneCounters["Scene-local editor counters"] EditorSystemAssets --> EditorOverlay["EditorOverlay / ProjectPanel"] SceneFile --> SceneFormat["shared/scene_format"] TemplateFile --> SceneFormat SceneFormat --> SceneAsset["SceneAsset / ActorRecord"] SceneFormat --> SceneMutation["SceneMutation / SceneEditCommand"] SceneAsset --> SceneDocument["SceneDocument"] SceneDocument --> PlayDocument["Play sandbox SceneDocument"] SceneDocument --> SceneSave["Write .scene on save / switch / shutdown"] SceneAsset --> RuntimeLoad["Engine::LoadSceneAsset"] PlayDocument --> RuntimeLoad SceneMutation --> RuntimePatch["Engine::ApplySceneEditCommand"] ComponentScripts --> LuaRegistry["ComponentManager type registry"] LuaRegistry --> RuntimeLoad LuaRegistry --> RuntimePatch Images --> Renderer["Renderer / SpriteRenderer"] Fonts --> Renderer Audio --> AudioRuntime["AudioManager"]

Module Dependency

graph TD subgraph App["App Layer (src/app)"] RuntimeApp["runtime app"] EditorApp["editor app"] end subgraph Editor["Editor Layer (src/editor)"] EditorCore["editor/core"] EditorDoc["editor/documents"] EditorPanels["editor/panels"] end subgraph Engine["Engine Layer (src/engine)"] EngineCore["engine/core"] EngineScene["engine/scene"] EngineScript["engine/scripting"] EngineRender["engine/rendering"] EnginePhysics["engine/physics"] EngineParticles["engine/particles"] EngineAudio["engine/audio"] EngineInput["engine/input"] end subgraph Shared["Shared Layer (src/shared + include/shared)"] SharedConfig["shared/config"] SharedSceneFormat["shared/scene_format"] SharedResource["shared/resources"] SharedPhysics["shared/physics"] end subgraph Assets["Project Data"] Resources["resources/*"] EnginePrivate[".engine/*"] end RuntimeApp --> EngineCore EditorApp --> EditorCore EditorCore --> EditorDoc EditorCore --> EditorPanels EditorCore --> EngineCore EditorCore --> SharedConfig EditorDoc --> SharedSceneFormat EditorDoc --> SharedPhysics EditorPanels --> EditorDoc EditorPanels --> SharedSceneFormat EditorPanels --> EngineCore EngineCore --> EngineScene EngineCore --> EngineScript EngineCore --> EngineRender EngineCore --> EnginePhysics EngineCore --> EngineParticles EngineCore --> EngineAudio EngineCore --> EngineInput EngineCore --> SharedConfig EngineCore --> SharedPhysics EngineCore --> SharedSceneFormat EngineScene --> EngineScript EngineScene --> SharedSceneFormat EngineScene --> SharedPhysics EngineScript --> EnginePhysics EngineScript --> EngineParticles EngineScript --> SharedResource EngineRender --> EngineParticles EngineRender --> SharedResource EnginePhysics --> SharedPhysics SharedSceneFormat --> SharedResource Resources --> SharedConfig Resources --> SharedSceneFormat Resources --> EngineScript Resources --> EngineRender Resources --> EngineAudio EnginePrivate --> EditorCore EnginePrivate --> EditorPanels

Editor Workflow

flowchart TD Project["Project panel"] -->|open .scene| Session["EditorSceneSession"] Session --> Authoring["Authoring SceneDocument"] Authoring --> Hierarchy["Hierarchy panel"] Authoring --> Inspector["Inspector panel"] Authoring --> Scene["Scene panel"] Session -->|sync preview| Engine["Engine preview runtime"] Engine --> Viewport["Viewport panel"] Engine --> Status["Status panel"] Hierarchy -->|SceneEditCommand| Authoring Inspector -->|SceneEditCommand| Authoring Scene -->|SceneEditCommand| Authoring Authoring -->|Play| PlayDoc["Play sandbox SceneDocument"] PlayDoc -->|Load snapshot| Engine Hierarchy -->|play-mode edits| PlayDoc Inspector -->|play-mode edits| PlayDoc Scene -->|play-mode edits| PlayDoc PlayDoc -->|incremental mutations| Engine Engine -->|Stop| Authoring