Jazz2::Editor::EditorSession class

The level editor.

The state handler of the editor. It owns the level being edited (see LevelDocument) with its history, hosts the level handler that shows it (see EditorLevelHandler) and the interface around it. The hosted handler gets the session as its root controller, so whatever it would do to the game as a whole — going to another level or to the main menu, saving a state to resume — is decided by the session.

The session coordinates what keeps state of its own: the file of the level with its recovery copy, lock and script (see DocumentFiles), the input (see EditorInputRouter), the play-tests (see PlayTestController), the comparison with the saved file (see SavedComparison) and what is shown of how the level is played (see PlayOverlays).

Base classes

class Jazz2::IStateHandler
Base interface of a state handler, only one handler runs at a time.
class Jazz2::IRootController
Base interface of a root controller.
class IEditorContext
What the panels and the dialogs of the level editor need from it.

Constructors, destructors, conversion operators

EditorSession(IRootController* root) explicit
Creates a new instance.
~EditorSession() override

Public functions

auto Initialize(const EditorInitialization& editorInit) -> bool
Opens a level, returns false if it can't be opened.
auto GetHistory() -> CommandHistory& override
Returns the history of the level being edited.
auto GetActions() -> ActionRegistry& override
Returns the actions.
auto GetTools() -> ToolManager& override
Returns the tools.
auto GetBlockGrab() -> BlockGrab& override
Returns the block grabbed by its corners with a key, marked in the level or in the picker of tiles.
auto GetEditHandler() const -> EditorLevelHandler* override
Returns the level handler that shows the level, or nullptr.
auto GetSurface() const -> Surface* override
Returns the surface of the interface.
auto GetSettings() -> EditorSettings& override
Returns the settings.
auto GetTileSetLibrary() -> ContentTileSetLibrary& override
Returns what is known about the tile sets of the game.
void OpenFile(StringView path) override
Opens a level file in the editor, asking about unsaved changes first.
void OpenRecoveryCopy(StringView recoveryPath) override
Restores a recovery copy into the editor, asking about unsaved changes first.
auto GetFilePath() const -> StringView override
Returns the path of the level file, may be empty.
auto GetLevelName() const -> StringView override
Returns the name of the level as episode/level, may be empty.
void GetFileRoots(bool forSaving, SmallVectorImpl<FileRoot>& roots) override
Returns the places levels are opened from or saved to.
void GetImageRoots(bool forSaving, SmallVectorImpl<FileRoot>& roots) override
Returns the places images are opened from or saved to, outside of the content of the game too.
void StartPlayTest(PlayStartMode mode) override
Starts playing the level.
void PlayTestWeapon(WeaponType weapon, bool poweredUp) override
Plays the level from the middle of the view with a weapon in hand and full of ammo, to try it.
void StopPlayTest(bool keep) override
Stops playing the level and returns to editing, keep keeps the play-test to resume later.
auto IsPlaying() const -> bool override
Returns true while the level is played, or is about to be.
auto GetPlayTest() -> PlayTestController&
Returns what plays the level being edited.
auto GetAccentColor() -> Colorf override
Returns the color the tile set of the level is known by, see FindAccentColor().
auto GetTileSetData(StringView name) -> const Formats::TileSetData* override
Returns a whole tile set with the pixels and masks of its tiles, read once, or nullptr if it can't be read.
auto GetTileSetDataCache() -> TileSetDataCache& override
Returns the tile sets read whole for the level being edited, see GetTileSetData().
void InvalidateTileSet(StringView name) override
Forgets what was read of a tile set, after its file was written.
auto GetLastPlayPath() const -> const PlayPath&
Returns the path the player took in the last play-test.
auto GetPlayPathHistory() const -> const PlayPathHistory& override
Returns the paths of the last play-tests, kept in the level.
auto ArePanelsShown() const -> bool override
Returns true if the panels are shown, while the level is edited and while the ring into the game grows over them.
auto GetPlayTransition() -> PlayTransition&
Returns the transition into the level being played.
auto IsPlayPathShown() const -> bool
Returns true if the path of the last play-test is shown.
auto GetPlayOverlays() -> PlayOverlays&
Returns what is shown over the level of how it's played, where the player can get and where it died.
auto ComputeReachability(SmallVectorImpl<std::int32_t>& distances) -> bool override
Finds where the player can get from the start of the play character, as the level is loaded now.
void DrawSessionOverlays(Painter& painter, const Rectf& viewRect)
Draws what is shown over the level of the editor, the differences from the saved file and the deaths in the last play-tests.
void ReloadRuntime() override
Loads the level again from the document, so the events in the game are as they are now, see ComputeReachability().
void SetCurrentLayer(std::int32_t layer) override
Changes the layer being edited.
auto IsGridShown() const -> bool
Returns true if the grid is shown.
auto AreEventsShown() const -> bool override
Returns true if events are shown over the level.
auto GetMaskMode() const -> std::int32_t
Returns how collision masks are shown, 0 not at all, 1 over the tiles, 2 instead of the tiles.
auto GetMaskOverlay() -> MaskOverlay&
Returns what shows the collision masks over the level.
auto GetPickerPanel() const -> PickerPanel override
Returns what the panel with the tiles and the events shows.
void SetPickerPanel(PickerPanel panel) override
Changes what the panel with the tiles and the events shows.
void SetEventBrush(EventStamp&& brush)
Chooses the events the event tool places, and the tool.
void PickEventFromList(Function<void(EventType)>&& callback) override
Lets the next event chosen in the list go to a callback, instead of becoming the one to place.
auto IsPickingEvent() const -> bool override
Returns true if the next event chosen in the list goes to a callback.
void CancelEventPick() override
Lets the next event chosen in the list become the one to place again, see PickEventFromList().
void OnEventChosen(EventType type) override
Called when an event is chosen in the list.
auto GetInputModality() const -> InputModality override
Returns what the editor was used with last.
auto IsEditingEvents() const -> bool override
Returns true if the editing actions work on events, not on tiles.
auto GetHoverPointer(ToolPointer& pointer) -> bool override
Returns the pointer over the view, false if it's not over the view.
auto Undo() -> bool override
Undoes the last change.
auto Redo() -> bool override
Redoes the last undone change.
void OnDocumentChanged(const DocumentChanges& changes)
Shows changes of the level being edited.
void AddChangeObserver(const std::shared_ptr<ChangeObserver>& observer) override
Tells a function about every change of the level being edited, all of it changes when another level is opened.
auto SaveAsFile(StringView path, bool move) -> bool override
Saves the level into another file and edits that one from then on, as Save As does.
auto CanSaveInPlace() const -> bool override
Returns true if the level can be saved to its file.
void ShowSaveAsDialog(bool exportOnly, Function<void()>&& onSaved = {}) override
Shows a dialog to save the level as a new file, or to export it, onSaved is called once it's saved.
void NoteLevelFileMoved(StringView from, StringView to) override
Tells that a level file was moved or renamed outside of Save As, its place among the recent files goes along.
void CancelInteractions(bool releasePointer = true)
Ends what the pointer is in the middle of, before something else changes the level.
auto RecordSnapshotStep(String name, SnapshotParts parts, Function<bool(LevelDocument&)>&& change, DocumentChangeKind kinds = DocumentChangeKind::None, std::int32_t layer = -1) -> bool override
Makes a change directly on the level and records it as an undoable step, kept as snapshots of parts.
void SetEditorState(Function<void(LevelDocument&)>&& change) override
Changes the editor state of the level, such as which layers are hidden or locked and how opaque they are shown.
void ToggleLayerFlag(std::int32_t layer, std::uint8_t flag) override
Toggles the editor state of a layer, such as whether it's hidden.
void MoveLayerTo(std::int32_t from, std::int32_t to) override
Moves a layer to another position in the list of layers, as an undoable step.
auto GetDocument() -> LevelDocument& override
Returns the level being edited.
auto GetCurrentLayer() const -> std::int32_t override
Returns the layer being edited.
auto IsLayerEditable(std::int32_t layer) const -> bool override
Returns true if a layer can be changed, it's not locked or hidden.
auto GetLayerView(std::int32_t layer) -> LayerView override
Returns how a layer is shown in the view.
auto GetStamp() -> TileStamp& override
Returns the stamp of the brush.
void SetStamp(TileStamp&& stamp) override
Sets the stamp of the brush.
auto GetSelection() -> TileSelection& override
Returns the selected tiles.
void Execute(std::unique_ptr<EditCommand> command, bool allowMerge = false) override
Executes an edit command.
void BeginChanges(String name) override
void EndChanges() override
Ends changes started by BeginChanges().
void PreviewTile(std::int32_t layer, std::int32_t x, std::int32_t y, const TileRef& tile) override
Shows a tile in the view before it's changed in the level.
void RevertPreview(std::int32_t layer, const Recti& area) override
Shows tiles of an area as the level has them, undoing a preview.
auto GetTileMap() -> Tiles::TileMap* override
Returns the shown level, or nullptr.
auto GetCamera() -> EditorCamera* override
Returns the camera, or nullptr.
void ShowMessage(StringView text) override
auto GetEventBrush() -> EventStamp& override
Returns the events the event tool places.
auto GetEventSelection() -> EventSelection& override
Returns the selected events.
auto GetEventPreviews() -> EventPreviews& override
Returns what draws events.
auto GetSmartTiles() -> SmartTileModel& override
Returns what knows how the tiles of the default tile set of the level fit together, it starts learning it.
auto GetTileShapes() -> const TileShapes& override
Returns the shapes of the masks of the default tile set of the level.
auto GetAnimTime() const -> float override
Returns the time animations of the interface are at.
auto GetViewSize() const -> Vector2i override
Returns viewport size of the handler.
void OnBeginFrame() override
Called at the beginning of each frame.
void OnEndFrame() override
Called at the end of each frame.
void OnInitializeViewport(std::int32_t width, std::int32_t height) override
Called when the viewport needs to be initialized (e.g., when the resolution is changed).
void OnKeyPressed(const KeyboardEvent& event) override
Called when a key is pressed.
void OnKeyReleased(const KeyboardEvent& event) override
Called when a key is released.
void OnTextInput(const TextInputEvent& event) override
Called when a text input is detected.
void OnTouchEvent(const TouchEvent& event) override
Called when a touch event is triggered.
void OnMouseDown(const MouseEvent& event) override
Called when a mouse button is pressed.
void OnMouseUp(const MouseEvent& event) override
Called when a mouse button is released.
void OnMouseMove(const MouseState& state) override
Called when the mouse is moved.
void OnMouseWheel(const ScrollEvent& event) override
Called when the mouse wheel is scrolled, or a touchpad is scrolled with two fingers.
void OnSuspend() override
Called when the application is about to be suspended, before the resumable state is saved.
auto GetCursorPolicy() const -> CursorPolicy override
Returns how the mouse cursor should be shown while the handler is active.
void InvokeAsync(Function<void()>&& callback) override
Invokes the specified callback asynchronously, usually at the end of current frame.
void InvokeAsync(std::weak_ptr<void> reference, Function<void()>&& callback) override
void GoToMainMenu(bool afterIntro) override
Sets current state handler to main menu.
void ChangeLevel(LevelInitialization&& levelInit) override
Sets current state handler to level described by LevelInitialization.
auto HasResumableState() const -> bool override
Returns true if any resumable state exists.
void ResumeSavedState() override
Resumes saved resumable state.
auto SaveCurrentStateIfAny() -> bool override
Saves current state if it's resumable.
void ApplyCursorPolicy() override
Shows or hides the mouse cursor as the current state handler wants.
void OpenEditor(EditorInitialization&& editorInit) override
auto GetFlags() const -> Flags override
Returns current state flags.
auto GetNewestVersion() const -> StringView override
Returns version of the latest update.
auto GetInitializationProgress() const -> float override
Returns progress of the initialization in the range 0-1, or -1 if there is nothing to show.
void RefreshCacheLevels(bool recreateAll, Compatibility::ConversionProgress progress = {}) override
Recreates level cache from Source directory.

Private functions

void StoreViewState() override
Puts how the level is seen and played into it, see DocumentViewState.
void PrepareForSave() override
Gets the level ready to be written, what the pointer is in the middle of ends and how it's seen goes into it.
void OnScriptChanged() override
Called when the script of the level changed on disk, a play-test kept to resume runs the old one.
auto GetViewRect() const -> Rectf override
Returns the view of the level on the screen, what the panels don't cover.
void ClearSelection() override
Clears the selection of what the editing actions work on, the events or the tiles.
void ChangeUiScale(std::int32_t direction) override
Makes the interface larger or smaller by a step, or chooses its size by the window with 0.
auto GetDocumentRevision() const -> std::uint32_t override
Returns the revision of the level being edited, see CommandHistory::GetRevision().
auto GetPlayTestRoot() -> IRootController& override
Returns the root controller the level handlers of play-tests get, it ends the play-test when they leave the level.
auto GetPlayTestHostReference() -> std::weak_ptr<void> override
Returns a weak reference to the host, callbacks run later only while it's alive.
void OnPlayTestViewChanged() override
Sets up the view again, the game or the editor is shown now.
auto OnPlayTestReturned() -> bool override
Called once the level is edited again, the changes made meanwhile are shown then.
void ExitEditor() override
Leaves the editor, as chosen in the pause menu of a play-test.

Function documentation

void Jazz2::Editor::EditorSession::OpenRecoveryCopy(StringView recoveryPath) override

Restores a recovery copy into the editor, asking about unsaved changes first.

The level is edited as the file the copy belongs to, if that file still exists, as a new level otherwise.

bool Jazz2::Editor::EditorSession::ComputeReachability(SmallVectorImpl<std::int32_t>& distances) override

Finds where the player can get from the start of the play character, as the level is loaded now.

With the moves of any character, see PlayOverlays::ComputeReachability(). Returns false if it can't be found out, as without the start or without multiplayer compiled in, whose route tracer it uses.

void Jazz2::Editor::EditorSession::AddChangeObserver(const std::shared_ptr<ChangeObserver>& observer) override

Tells a function about every change of the level being edited, all of it changes when another level is opened.

Only a weak reference is kept, the function is called as long as its owner keeps it.

bool Jazz2::Editor::EditorSession::SaveAsFile(StringView path, bool move) override

Saves the level into another file and edits that one from then on, as Save As does.

See DocumentFiles::SaveAsFile(), the script of the level goes along, and with move the file the level was in is removed. Returns false if the level couldn't be saved, nothing is changed then.

void Jazz2::Editor::EditorSession::NoteLevelFileMoved(StringView from, StringView to) override

Tells that a level file was moved or renamed outside of Save As, its place among the recent files goes along.

SaveAsFile() does it itself for the level being edited.

void Jazz2::Editor::EditorSession::CancelInteractions(bool releasePointer = true)

Ends what the pointer is in the middle of, before something else changes the level.

The stroke of a tool that follows the pointer is cancelled, as by Esc, and with releasePointer also what the interface holds by the pointer, as a handle of the layer dragged. Called before an action, an undoable step that doesn't come from the tool itself, saving, undoing and playing, so a step of a tool started before them never takes what they changed as its own. Commands the tool runs itself aren't affected.

bool Jazz2::Editor::EditorSession::RecordSnapshotStep(String name, SnapshotParts parts, Function<bool(LevelDocument&)>&& change, DocumentChangeKind kinds = DocumentChangeKind::None, std::int32_t layer = -1) override

Makes a change directly on the level and records it as an undoable step, kept as snapshots of parts.

For changes no dedicated command makes, see SnapshotCommand. As with Execute(), a stroke of the tool going on is cancelled first, unless the tool makes the change itself. change returns false if it changed nothing, nothing is recorded then. kinds and layer are as in SnapshotCommand::Begin(). Returns true if the step was recorded.

void Jazz2::Editor::EditorSession::SetEditorState(Function<void(LevelDocument&)>&& change) override

Changes the editor state of the level, such as which layers are hidden or locked and how opaque they are shown.

It's saved with the level, but isn't a change to undo, so no step is recorded — the level counts as changed since it was saved, so it's autosaved and asked about when it's closed.

void Jazz2::Editor::EditorSession::OnMouseDown(const MouseEvent& event) override

Called when a mouse button is pressed.

The position is in window coordinates, which may differ from the pixels of the drawable on a high-DPI display. The game itself doesn't use the mouse, only the level editor does.

void Jazz2::Editor::EditorSession::InvokeAsync(std::weak_ptr<void> reference, Function<void()>&& callback) override

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Jazz2::Editor::EditorSession::ApplyCursorPolicy() override

Shows or hides the mouse cursor as the current state handler wants.

The cursor follows IStateHandler::GetCursorPolicy(), which is asked again here — a state handler calls this when what it wants changes.

float Jazz2::Editor::EditorSession::GetInitializationProgress() const override

Returns progress of the initialization in the range 0-1, or -1 if there is nothing to show.

Converting the original game files is the one part of the first start that can take long enough to be worth showing, so the loading screen turns this into a progress bar. It's -1 whenever no conversion is running — including before one has reported anything at all, so a loading screen that is shown for some other reason never shows a bar.

void Jazz2::Editor::EditorSession::RefreshCacheLevels(bool recreateAll, Compatibility::ConversionProgress progress = {}) override

Recreates level cache from Source directory.

Parameters
recreateAll
progress Reports how far the conversion has got, see ConversionProgress

bool Jazz2::Editor::EditorSession::OnPlayTestReturned() override private

Called once the level is edited again, the changes made meanwhile are shown then.

Returns true if the level shown was loaded again for them, its view is set up then, as by OnPlayTestViewChanged().