Lucky Robots Blog Open Roles

DM · Directory Map

A field guide to the LuckyEngine repository: top-level layout, what each subdirectory under Hazel/src/Hazel/ contains, and how the static-lib core, editor executable, script runtime, and runtime executable depend on each other.

Hazel/ — engine LuckyEditor/ Hazel-ScriptCore/ Hazel-ScriptGen/ LuckyRuntime/ Resources/ wasm/ Hazelnut/ legacy
High-level dependency layers Hazel/vendor/ · Conan packages ~38 third-party libs: glfw, imgui, entt, glm, nvrhi, JoltPhysics, mujoco, Coral, Box2D, miniaudio, yaml-cpp, spdlog, tracy, simdjson, … Hazel/ (StaticLib core) Core, Renderer, Scene, Physics, Script, Asset, Audio, Animation, Data, Net, Editor framework, … Linked into every consumer below. LuckyEditor/ editor exe + panels LuckyRuntime/ standalone runtime exe Hazel-ScriptCore / ScriptGen C# runtime + gen tool Resources/ shaders, textures, fonts
Hazel/ is the static core; LuckyEditor, LuckyRuntime, and ScriptCore all sit on top of it.

Repository tree

LuckyEngine/
├── Hazel/                   # Core engine (StaticLib)
│   ├── src/Hazel/
│   │   ├── Core/            # Application, Window, Ref, Events, Input, TimeManager, Log, RenderThread
│   │   ├── Renderer/        # Renderer, SceneRenderer, Renderer2D, Material, Shader, Pipeline, Mesh
│   │   ├── Scene/           # Scene, Entity, Components, Serializer, Prefab, TransformHierarchy
│   │   ├── Physics/         # PhysicsScene/Body/Shape abstraction + JoltPhysics/ + Mujoco/
│   │   ├── Physics2D/       # Box2D
│   │   ├── Script/          # ScriptEngine, ScriptGlue, ScriptBuilder, ScriptEntityStorage
│   │   ├── Asset/           # AssetManager facade + Editor/Runtime impls + serializers
│   │   ├── Audio/           # MiniAudioEngine, Sound, SourceManager, SoundBank
│   │   ├── Editor/          # PanelManager, EditorPanel base, SelectionManager, EditorOperation
│   │   ├── ImGui/           # ImGuiLayer, ImGuiEx, Colors
│   │   ├── Robots/          # MotionGraph + Nodes/, Policy/
│   │   ├── Learn/           # RobotManager, RobotAgent, RobotEnv, PolicyNetwork
│   │   ├── Animation/       # AnimationGraph, blending
│   │   ├── Data/            # Observer, Recorders/, Writers/, EpisodeReportStreamer
│   │   ├── Hub/             # HubRecordingClient
│   │   ├── Auth/            # AuthService
│   │   ├── Net/             # gRPC service implementations
│   │   ├── Platform/        # GLFW/, Null/ window implementations
│   │   ├── Project/         # Project, settings, user prefs, tiering
│   │   ├── Serialization/   # AssetPack, YAML helpers, macros
│   │   ├── Utilities/       # FileSystem, StringUtils, ContainerUtils, ProcessHelper
│   │   ├── Math/            # Frustum, math helpers
│   │   └── Reflection/      # Runtime reflection
│   └── vendor/              # ~38 third-party libs (glfw, imgui, entt, glm, nvrhi, JoltPhysics,
│                            #  mujoco, Coral, Box2D, miniaudio, yaml-cpp, spdlog,
│                            #  msdf-atlas-gen, tracy, simdjson, …)
├── LuckyEditor/             # Editor executable
│   ├── src/
│   │   ├── EditorLayer.{h,cpp}      # Top-level orchestrator (PROTECTED — don't add code)
│   │   ├── Panels/                  # ContentBrowser, AppSettings, ContentVault, …
│   │   ├── Viewport/                # Viewport rendering + interaction
│   │   ├── SimpleUX/                # Simplified UX mode (Welcome, Sidebar, …)
│   │   ├── Popups/                  # Modal flows (CreateProjectFromTemplate, NewProjectForm, …)
│   │   ├── Utilities/Content/       # *Job (Import/Export/SaveProjectAs/CreateFromTemplate)
│   │   ├── Agent/                   # In-editor AI agent (MainThreadDispatcher, AgentChatPanel,
│   │   │                            #  LLM/LocalClaudeRunner)
│   │   ├── McpServer/               # JSON-RPC 2.0 server (TCP+HTTP) exposing McpTool registry
│   │   └── …
│   └── RobotSandbox/                # Default robot project
├── Hazel-ScriptCore/        # C# script runtime library (Source/Hazel/)
├── Hazel-ScriptGen/         # C# binding code generator
├── LuckyRuntime/            # Standalone runtime executable
├── Resources/               # Shaders, default textures, fonts
├── wasm/                    # WASM port (.NET 9 browser-wasm AOT under wasm/dotnet/ is active)
├── scripts/                 # Build/setup scripts
├── premake5.lua             # Root workspace
├── Dependencies.lua         # Vendor path mappings
├── conanfile.py             # Conan packages
└── .github/workflows/       # CI

Notes on conventions: every Hazel/src/Hazel/<Subsystem>/ directory pairs implementation (.cpp) with a small set of public headers. Platform-specific code lives under Platform/<Platform>/; vendor code stays under Hazel/vendor/ and is mapped through Dependencies.lua.

Hazelnut/ is the legacy editor

Hazelnut/ is the pre-LuckyEditor sample project from upstream Hazel. It is deprecated — do not add new code there. New panels, popups, and editor-side jobs belong in LuckyEditor/.

Top-level folders

Hazel/

The engine itself, built as a StaticLib. src/Hazel/ is partitioned by subsystem; vendor/ holds about 38 third-party libraries. Every other top-level executable links this lib.

StaticLib C++

LuckyEditor/

The editor executable. EditorLayer is the orchestrator (protected — do not extend it directly). New work lands in Panels/, Popups/, Utilities/Content/, or Agent/. Ships with the RobotSandbox default project.

Executable EditorLayer protected

Hazel-ScriptCore/

The C# library scripts compile against. Mirrors the engine's component / API surface; bound through ScriptGlue InternalCalls on the C++ side and InternalCalls.cs on the C# side.

C# library .NET

Hazel-ScriptGen/

Code generator that produces script bindings. Run as part of the build to keep the C++ / C# InternalCall surface in sync.

Tool

LuckyRuntime/

Standalone runtime executable — runs a packaged project without the editor. Loads AssetPack rather than the editor's loose-file asset tree.

Executable

Resources/

Engine-owned resources: HLSL shaders, default textures, fonts. Shared between editor and runtime.

HLSL fonts

wasm/

WASM port surface. wasm/dotnet/ hosts the active .NET 9 browser-wasm AOT path. See the WASM skill family for the current sub-skill set.

.NET 9 AOT browser-wasm

scripts/

Build and setup scripts (Conan install, project regeneration, premake bootstrap, CI helpers).

shell / py

premake5.lua & Dependencies.lua

Root workspace and vendor path mappings. New vendor libraries get a path entry in Dependencies.lua and a link line in Hazel/premake5.lua.

premake

conanfile.py

External Conan packages. Add the package here, then conan install to fetch.

Conan

.github/workflows/

CI definitions. Match the conventions in .claude/skills/send-pr/ for what the PR-time gate expects.

CI

Hazelnut/ legacy

The pre-LuckyEditor sample editor inherited from upstream Hazel. Deprecated. New editor work belongs in LuckyEditor/, not here.

Protected entry points

A small number of files are protected — extending them couples new work to the frame loop or top-level orchestrator in ways that bypass the engine's phase scheduling and panel registry. Use the documented extension points instead.

FileUse instead
LuckyEditor/src/EditorLayer.{h,cpp} PanelManager::RegisterPanel, EditorPanelIDs, TimeManager::RegisterWithRunner — see Playbook.
Scene::OnUpdate TimeManager::RegisterWithRunner or RegisterFreeUpdate with the correct phase.

See also