The Project Manager is the standalone application surface that Godot presents when launched without a project argument. It is responsible for listing, creating, importing, running, and organizing Godot projects. This document covers the classes in editor/project_manager/: ProjectManager, ProjectList, ProjectListItemControl, ProjectDialog, QuickSettingsDialog, and ProjectTag.
For the editor UI that appears after a project is opened, see EditorNode. For project-level configuration stored in project.godot, see ProjectSettings & EditorSettings.
Component diagram: Project Manager UI
Sources: editor/project_manager/project_manager.h54-290 editor/project_manager/project_manager.cpp84-605
ProjectManagerDefined in editor/project_manager/project_manager.h54-290
ProjectManager is a Control node and a singleton (ProjectManager::get_singleton()). It is the root control for the project manager window.
Two main views are managed via MainViewTab:
| Enum Value | Description |
|---|---|
MAIN_VIEW_PROJECTS | The local project list |
MAIN_VIEW_ASSETLIB | The Asset Library browser |
Views are registered with _add_main_view() and switched with _select_main_view(int p_id). Each view has an associated toggle button stored in main_view_toggle_map.
NOTIFICATION_READY in editor/project_manager/project_manager.cpp103-112 sets the default sort order from EditorSettings (project_manager/sorting_order), calls _select_main_view(MAIN_VIEW_PROJECTS), and updates the placeholder if the list is empty.
Opening for editing is handled by _open_selected_projects(). For each selected project path it constructs a List<String> of CLI arguments and calls OS::get_singleton()->create_instance(args) with --path and --editor. The window then dims and quits via get_tree()->quit().
Running without the editor follows the same pattern in _run_project_confirm() but omits --editor.
Before opening, _open_selected_projects_check_warnings() inspects the project's config_version and unsupported_features to display migration dialogs when needed (e.g., Godot 3→4 conversion).
| Action | Method | Dialog/Tool |
|---|---|---|
| New project | _new_project() | ProjectDialog (MODE_NEW) |
| Import project | _import_project() | ProjectDialog (MODE_IMPORT) |
| Install from ZIP | _install_project() | ProjectDialog (MODE_INSTALL) |
| Rename | _rename_project() | ProjectDialog (MODE_RENAME) |
| Duplicate | _duplicate_project() | ProjectDialog (MODE_DUPLICATE) |
| Scan directory | _scan_projects() | EditorFileDialog scan_dir |
| Erase selected | _erase_project() | ConfirmationDialog erase_ask |
| Erase missing | _erase_missing_projects() | ConfirmationDialog erase_missing_ask |
| Manage tags | _manage_project_tags() | ConfirmationDialog tag_manage_dialog |
Sources: editor/project_manager/project_manager.cpp504-606 editor/project_manager/project_manager.h185-215
ProjectListDefined in editor/project_manager/project_list.h106-336 implemented in editor/project_manager/project_list.cpp
ProjectList extends ScrollContainer and is the scrollable list of all known projects. It owns the config file for persisting the project registry and handles background directory scanning.
ProjectList::ItemEach entry in _projects (a Vector<Item>) holds all metadata parsed from project.godot:
| Field | Type | Source |
|---|---|---|
project_name | String | application/config/name |
description | String | application/config/description |
project_version | String | Parsed from application/config/features |
tags | PackedStringArray | application/config/tags |
path | String | Directory path |
icon | String | application/config/icon |
main_scene | String | application/run/main_scene |
unsupported_features | PackedStringArray | Compared against current engine features |
last_edited | uint64_t | Modification time of project.godot or .fscache |
favorite | bool | Persisted in config |
grayed | bool | true when config_version > current or file missing |
missing | bool | true when project.godot not found |
recovery_mode | bool | Detected via .recovery_mode_lock file |
version | int | config_version field |
load_project_data() in editor/project_manager/project_list.cpp629-739 is the static method that reads all this data from disk.
Sorting is done by sort_projects() using ProjectListComparator. Favorites always appear first, then the selected FilterOption:
FilterOption | Sort Key |
|---|---|
EDIT_DATE | last_edited descending |
NAME | project_name ascending |
PATH | path ascending |
TAGS | tag_sort_string ascending |
Search filtering via set_search_term() supports tag:tagname prefix syntax to filter by tags.
Diagram: Project scan sequence
The ScanData struct holds the scanning thread, paths to scan, found projects list, and an atomic SafeFlag scan_in_progress. The main thread polls NOTIFICATION_PROCESS and calls _scan_finished() once the flag is cleared.
Icons are loaded lazily one per frame via NOTIFICATION_PROCESS. _update_icons_async() resets _icon_load_index to 0 and enables processing. Each frame, _load_project_icon(int p_index) loads the image from disk, resizes to match the default icon dimensions using Image::INTERPOLATE_LANCZOS, and creates an ImageTexture.
_migrate_config() in editor/project_manager/project_list.cpp591-621 reads legacy project paths from EditorSettings (keys prefixed with projects/ and favorite_projects/) and writes them to the new standalone config file. This migration only runs once if the new config file does not already exist.
| Signal | When Emitted |
|---|---|
SIGNAL_LIST_CHANGED | After update_project_list() |
SIGNAL_SELECTION_CHANGED | When selection changes |
SIGNAL_PROJECT_ASK_OPEN | When user double-clicks a project |
SIGNAL_MENU_OPTION_SELECTED | When a context menu item is selected |
Sources: editor/project_manager/project_list.h279-336 editor/project_manager/project_list.cpp492-800
ProjectListItemControlDefined in editor/project_manager/project_list.h46-104
ProjectListItemControl extends HBoxContainer and represents a single row in the project list. It is created by ProjectList::_create_project_item_control().
Diagram: ProjectListItemControl layout
Each ProjectListItemControl emits three signals: favorite_pressed, explore_pressed, and request_menu. These are connected upstream to handlers in ProjectList.
Visual state is managed through is_selected, is_hovering, and is_favorite booleans, with NOTIFICATION_DRAW drawing the appropriate style box from the ProjectList theme node (selected, hovered, hover_pressed, focus).
Sources: editor/project_manager/project_list.h46-104 editor/project_manager/project_list.cpp55-466
ProjectDialogDefined in editor/project_manager/project_dialog.h43-167 implemented in editor/project_manager/project_dialog.cpp
ProjectDialog extends ConfirmationDialog and is reused for five distinct operations controlled by the Mode enum.
| Mode | Title | Key Behavior |
|---|---|---|
MODE_NEW | "Create New Project" | Creates project.godot, default icon SVG, .editorconfig, optional VCS metadata |
MODE_IMPORT | "Import Existing Project" | Accepts a project.godot path, a directory, or a .zip file |
MODE_INSTALL | "Install Project: …" | Extracts a ZIP into the target directory |
MODE_RENAME | "Rename Project" | Edits application/config/name in an existing project.godot via ConfigFile |
MODE_DUPLICATE | "Duplicate Project" | Copies the project directory with DirAccess::copy_dir(), then renames |
show_dialog(bool p_reset_name, bool p_is_confirmed) configures which UI containers are visible for each mode before calling popup_centered().
_validate_path() editor/project_manager/project_dialog.cpp96-291 runs on every text change. It enforces:
Validation state is tracked with a BitField<InvalidStateFlag> (INVALID_STATE_FLAG_PATH_INPUT, INVALID_STATE_FLAG_RENDERER_SELECT) which gates the OK button via _update_ok_button().
When creating a new project, three renderer options are presented via a ButtonGroup:
| Rendering Method | Backend | Platforms |
|---|---|---|
forward_plus | RenderingDevice | Desktop |
mobile | RenderingDevice | Desktop + Mobile |
gl_compatibility | OpenGL 3 / ES 3.0 / WebGL2 | Desktop + Mobile + Web |
DisplayServer::is_rendering_device_supported() is queried once; if it returns false, the dialog defaults to gl_compatibility and disables the RD-based options.
The selected renderer is written to rendering/renderer/rendering_method in project.godot and also saved to EditorSettings as project_manager/default_renderer.
_update_target_auto_dir() editor/project_manager/project_dialog.cpp312-356 automatically derives a folder name from the project name using the naming convention from EditorSettings key project_manager/directory_naming_convention:
| Index | Convention |
|---|---|
| 0 | No convention |
| 1 | kebab-case |
| 2 | snake_case |
| 3 | camelCase |
| 4 | PascalCase |
| 5 | Title Case |
| Signal | When Emitted |
|---|---|
project_created | After MODE_NEW or MODE_IMPORT/INSTALL succeeds |
project_duplicated | After MODE_DUPLICATE succeeds |
projects_updated | After MODE_RENAME succeeds |
Sources: editor/project_manager/project_dialog.h43-167 editor/project_manager/project_dialog.cpp54-1015
QuickSettingsDialogDefined in editor/project_manager/quick_settings_dialog.h43-104 implemented in editor/project_manager/quick_settings_dialog.cpp
QuickSettingsDialog extends AcceptDialog and provides a compact settings form for the most commonly changed editor preferences, without opening the full EditorSettingsDialog.
Settings exposed:
| UI Control | EditorSettings Key |
|---|---|
language_option_button | interface/editor/localization/editor_language |
style_option_button | interface/theme/style |
theme_option_button | interface/theme/color_preset |
scale_option_button | interface/editor/appearance/display_scale |
network_mode_option_button | network/connection/network_mode |
check_for_update_button | network/connection/check_for_updates |
directory_naming_convention_button | project_manager/directory_naming_convention |
Each change is immediately applied via _set_setting_value(), which calls EditorSettings::notify_changes() and EditorSettings::save(). Settings that require restart (e.g., display scale) show a restart_required_label and a "Restart Now" button that calls OS::create_instance().
The "Edit All Settings" button lazily instantiates EditorSettingsDialog for full settings access.
Sources: editor/project_manager/quick_settings_dialog.h43-104 editor/project_manager/quick_settings_dialog.cpp47-453
ProjectTagDefined in editor/project_manager/project_tag.h37-53 implemented in editor/project_manager/project_tag.cpp
ProjectTag extends HBoxContainer and renders a single tag chip. It is used in two contexts:
ProjectListItemControl's tag_container to display a project's tagsProjectManagerEach tag is assigned a deterministic hue based on String::hash() of the tag text, then set_ok_hsl_s(0.8) and set_self_modulate() are used to apply the color. The visible Button inside the control can be connected to a callable via connect_button_to(), allowing clicks to either add the tag to the search filter (in the list) or remove it (in the management dialog, when display_close = true).
Sources: editor/project_manager/project_tag.cpp51-77 editor/project_manager/project_tag.h37-53
Diagram: Create project → open editor sequence
Sources: editor/project_manager/project_dialog.cpp542-816 editor/project_manager/project_manager.cpp557-606
All sources in editor/project_manager/ are compiled unconditionally via the SCsub file editor/project_manager/SCsub1-6 which adds all .cpp files to env.editor_sources. The project manager is only active when Godot is launched in tool mode without a project path argument.
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.