Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Tetragrama/Editor.h
Original file line number Diff line number Diff line change
Expand Up @@ -193,8 +193,8 @@ namespace Tetragrama
virtual void OnClosed() override;
void OnWorldShutdown(ZEngine::EngineContext& engine) override;
bool OnCloseRequested() override;
/// The authoring world never simulates. Play requires a separate, complete
/// snapshot/restore lifecycle before this policy can be changed.
/// The authoring world never simulates. Play requires a separate runtime
/// world and a complete retained-authoring lifecycle before this policy changes.
[[nodiscard]] bool ShouldSimulate() const final
{
return false;
Expand Down
170 changes: 170 additions & 0 deletions Tetragrama/EditorPlayCoordinator.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
#include <Tetragrama/EditorPlayCoordinator.h>
#include <limits>

namespace Tetragrama
{
using namespace ZEngine::ECS;

bool EditorPlayCoordinator::OnOwnerThread() const noexcept
{
return m_owner == std::this_thread::get_id();
}

bool EditorPlayCoordinator::BeginTransition(Mode next, SceneRequestId* output) noexcept
{
if (!OnOwnerThread() || !output || m_active || !m_requests.Drained() || m_generation == std::numeric_limits<uint64_t>::max())
return false;
SceneRequestId request = {};
if (!m_requests.Admit(m_generation, &request))
return false;
// Drained admission has no outstanding asynchronous owner, so the
// freshly admitted request can always enter preparation on this thread.
if (!m_requests.TryStart(request))
{
(void) m_requests.Fail(request, SceneLoadStage::Admission, SceneLoadError::Unavailable);
(void) m_requests.Acknowledge(request);
return false;
}
m_active = request;
m_mode = next;
*output = request;
return true;
}

bool EditorPlayCoordinator::BeginEnter(SceneRequestId* output) noexcept
{
if (!OnOwnerThread() || m_mode != Mode::Edit || !BeginTransition(Mode::Starting, output))
return false;
m_last_enter = *output;
return true;
}

SceneCancelResult EditorPlayCoordinator::CancelEnter(SceneRequestId request) noexcept
{
if (!OnOwnerThread() || !request || request != m_last_enter)
return SceneCancelResult::NotFound;
const auto result = m_requests.Cancel(request);
if (result == SceneCancelResult::Cancelled && m_mode == Mode::Starting && request == m_active)
{
m_active = {};
m_mode = Mode::Edit;
}
return result;
}

bool EditorPlayCoordinator::FailTransition(Mode expected, Mode next, SceneRequestId request, SceneLoadStage stage, SceneLoadError error) noexcept
{
if (!OnOwnerThread() || m_mode != expected || request != m_active || !m_requests.Fail(request, stage, error))
return false;
m_active = {};
m_mode = next;
return true;
}

bool EditorPlayCoordinator::FailEnter(SceneRequestId request, SceneLoadStage stage, SceneLoadError error) noexcept
{
return FailTransition(Mode::Starting, Mode::Edit, request, stage, error);
}

bool EditorPlayCoordinator::BeginCommit(Mode expected, SceneRequestId request, uint64_t generation) noexcept
{
return OnOwnerThread() && m_mode == expected && request == m_active && generation == m_generation && m_requests.BeginCommit(request, generation);
}

bool EditorPlayCoordinator::FinishCommit(Mode expected, Mode next, SceneRequestId request) noexcept
{
if (!OnOwnerThread() || m_mode != expected || request != m_active || m_generation == std::numeric_limits<uint64_t>::max() || !m_requests.Commit(request, m_generation + 1))
return false;
++m_generation;
m_active = {};
m_mode = next;
return true;
}

bool EditorPlayCoordinator::BeginEnterCommit(SceneRequestId request, uint64_t generation) noexcept
{
return BeginCommit(Mode::Starting, request, generation);
}

bool EditorPlayCoordinator::FinishEnterCommit(SceneRequestId request) noexcept
{
return FinishCommit(Mode::Starting, Mode::Play, request);
}

bool EditorPlayCoordinator::Pause() noexcept
{
if (!OnOwnerThread() || m_mode != Mode::Play)
return false;
m_mode = Mode::Paused;
return true;
}

bool EditorPlayCoordinator::Resume() noexcept
{
if (!OnOwnerThread() || m_mode != Mode::Paused)
return false;
m_mode = Mode::Play;
return true;
}

bool EditorPlayCoordinator::BeginStep() noexcept
{
if (!OnOwnerThread() || m_mode != Mode::Paused)
return false;
m_mode = Mode::Stepping;
return true;
}

bool EditorPlayCoordinator::FinishStep() noexcept
{
if (!OnOwnerThread() || m_mode != Mode::Stepping)
return false;
m_mode = Mode::Paused;
return true;
}

bool EditorPlayCoordinator::BeginStop(SceneRequestId* output) noexcept
{
return OnOwnerThread() && (m_mode == Mode::Play || m_mode == Mode::Paused || m_mode == Mode::ReturnError) && BeginTransition(Mode::Stopping, output);
}

bool EditorPlayCoordinator::FailStop(SceneRequestId request, SceneLoadStage stage, SceneLoadError error) noexcept
{
return FailTransition(Mode::Stopping, Mode::ReturnError, request, stage, error);
}

bool EditorPlayCoordinator::BeginStopCommit(SceneRequestId request, uint64_t generation) noexcept
{
return BeginCommit(Mode::Stopping, request, generation);
}

bool EditorPlayCoordinator::FinishStopCommit(SceneRequestId request) noexcept
{
return FinishCommit(Mode::Stopping, Mode::Edit, request);
}

bool EditorPlayCoordinator::Poll(SceneRequestId request, SceneLoadResult* output) const noexcept
{
return m_requests.Poll(request, output);
}

bool EditorPlayCoordinator::Acknowledge(SceneRequestId request) noexcept
{
return m_requests.Acknowledge(request);
}

bool EditorPlayCoordinator::FinishCleanup(SceneRequestId request) noexcept
{
return m_requests.FinishCleanup(request);
}

EditorPlayCoordinator::Mode EditorPlayCoordinator::CurrentMode() const noexcept
{
return m_mode;
}

uint64_t EditorPlayCoordinator::Generation() const noexcept
{
return m_generation;
}
} // namespace Tetragrama
83 changes: 83 additions & 0 deletions Tetragrama/EditorPlayCoordinator.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
#pragma once
#include <ZEngine/ECS/SceneLoadCoordinator.h>
#include <cstdint>
#include <thread>

namespace Tetragrama
{
/// @brief Main-thread transition ledger for retained-authoring Play.
/// @details This ledger owns no worlds and performs no simulation or binding
/// switches. The host must prepare and guard those operations before commit,
/// and must drain worker/GPU owners before reporting cleanup complete.
class EditorPlayCoordinator final
{
public:
enum class Mode : uint8_t
{
Edit,
Starting,
Play,
Paused,
Stepping,
Stopping,
ReturnError
};

EditorPlayCoordinator() = default;
EditorPlayCoordinator(const EditorPlayCoordinator&) = delete;
EditorPlayCoordinator& operator=(const EditorPlayCoordinator&) = delete;

/// @brief Admit one Enter request; outstanding cleanup blocks admission.
[[nodiscard]] bool BeginEnter(ZEngine::ECS::SceneRequestId* output) noexcept;
/// @brief Cancel Enter before commit; cleanup remains independently owned.
[[nodiscard]] ZEngine::ECS::SceneCancelResult CancelEnter(ZEngine::ECS::SceneRequestId request) noexcept;
/// @brief Fail Enter before commit, retaining the terminal result.
[[nodiscard]] bool FailEnter(ZEngine::ECS::SceneRequestId request, ZEngine::ECS::SceneLoadStage stage, ZEngine::ECS::SceneLoadError error) noexcept;
/// @brief Seal a prepared Enter against cancellation and reentrant transitions.
[[nodiscard]] bool BeginEnterCommit(ZEngine::ECS::SceneRequestId request, uint64_t expected_generation) noexcept;
/// @brief Record a successfully published Enter after the host switches bindings.
[[nodiscard]] bool FinishEnterCommit(ZEngine::ECS::SceneRequestId request) noexcept;
/// @brief Pause simulation without restoring authoring.
[[nodiscard]] bool Pause() noexcept;
/// @brief Resume continuous simulation from Paused.
[[nodiscard]] bool Resume() noexcept;
/// @brief Reserve a single paused step; the host executes it separately.
[[nodiscard]] bool BeginStep() noexcept;
/// @brief Finish a reserved step and return to Paused.
[[nodiscard]] bool FinishStep() noexcept;
/// @brief Admit Stop from Play, Paused, or a failed-return recovery state.
[[nodiscard]] bool BeginStop(ZEngine::ECS::SceneRequestId* output) noexcept;
/// @brief Record a failed return; retry remains possible after cleanup.
[[nodiscard]] bool FailStop(ZEngine::ECS::SceneRequestId request, ZEngine::ECS::SceneLoadStage stage, ZEngine::ECS::SceneLoadError error) noexcept;
/// @brief Seal a prepared return against reentrant transitions.
[[nodiscard]] bool BeginStopCommit(ZEngine::ECS::SceneRequestId request, uint64_t expected_generation) noexcept;
/// @brief Record the successful switch back to the retained authoring world.
[[nodiscard]] bool FinishStopCommit(ZEngine::ECS::SceneRequestId request) noexcept;
/// @brief Read a retained transition outcome on the owner thread.
[[nodiscard]] bool Poll(ZEngine::ECS::SceneRequestId request, ZEngine::ECS::SceneLoadResult* output) const noexcept;
/// @brief Release a terminal outcome; this does not imply cleanup is done.
[[nodiscard]] bool Acknowledge(ZEngine::ECS::SceneRequestId request) noexcept;
/// @brief Release request cleanup ownership after transfer or retirement.
/// @details A successful Enter may release its preparation record after
/// ownership transfers to the active host. Cancelled work and retired
/// worlds retain it until their external CPU/GPU users have drained.
[[nodiscard]] bool FinishCleanup(ZEngine::ECS::SceneRequestId request) noexcept;
/// @brief Return the owner-thread mode without enabling simulation.
[[nodiscard]] Mode CurrentMode() const noexcept;
/// @brief Return the owner-thread activation generation.
[[nodiscard]] uint64_t Generation() const noexcept;

private:
[[nodiscard]] bool OnOwnerThread() const noexcept;
[[nodiscard]] bool BeginTransition(Mode next, ZEngine::ECS::SceneRequestId* output) noexcept;
[[nodiscard]] bool BeginCommit(Mode expected, ZEngine::ECS::SceneRequestId request, uint64_t generation) noexcept;
[[nodiscard]] bool FinishCommit(Mode expected, Mode next, ZEngine::ECS::SceneRequestId request) noexcept;
[[nodiscard]] bool FailTransition(Mode expected, Mode next, ZEngine::ECS::SceneRequestId request, ZEngine::ECS::SceneLoadStage stage, ZEngine::ECS::SceneLoadError error) noexcept;
const std::thread::id m_owner = std::this_thread::get_id();
ZEngine::ECS::SceneLoadCoordinator m_requests = {};
ZEngine::ECS::SceneRequestId m_active = {};
ZEngine::ECS::SceneRequestId m_last_enter = {};
Mode m_mode = Mode::Edit;
uint64_t m_generation = 1;
};
} // namespace Tetragrama
48 changes: 43 additions & 5 deletions Tetragrama/EditorSession.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -302,7 +302,7 @@ namespace Tetragrama
{
// Owner identity is stable for the initialized lifetime. Reject other
// threads before reading the main-thread-only mutable phase flag.
return m_owner == std::this_thread::get_id() && m_initialized && m_in_phase && !m_replacing;
return m_owner == std::this_thread::get_id() && m_initialized && m_in_phase && !m_replacing && !m_authoring_suspended;
}

EntityTarget EditorSession::TargetFor(EntityID entity)
Expand All @@ -328,7 +328,7 @@ namespace Tetragrama

bool EditorSession::Enqueue(const PendingRequest& request)
{
if (!m_initialized || m_owner != std::this_thread::get_id() || m_replacing)
if (!m_initialized || m_owner != std::this_thread::get_id() || m_replacing || m_authoring_suspended)
{
return false;
}
Expand Down Expand Up @@ -1046,11 +1046,13 @@ namespace Tetragrama
m_request_first = m_request_count = 0;
m_in_phase = false;
m_initialized = false;
m_authoring_suspended = false;
m_suspended_scene = nullptr;
}

bool EditorSession::BeginMutationPhase(bool editable)
{
if (!m_initialized || m_in_phase || m_owner != std::this_thread::get_id() || m_replacing)
if (!m_initialized || m_in_phase || m_owner != std::this_thread::get_id() || m_replacing || m_authoring_suspended)
{
return false;
}
Expand Down Expand Up @@ -1084,6 +1086,42 @@ namespace Tetragrama
}
}

bool EditorSession::SuspendAuthoring()
{
if (!Allowed() || !m_editable || !m_scene)
return false;

// Cancel before suspending: rollback must still have an editable owner.
Cancel();
if (m_hierarchy_pending)
SynchronizeHierarchy();
DiscardRequests();
m_suspended_scene = m_scene;
m_suspended_epoch = m_epoch;
m_suspended_revision = m_document_revision;
m_suspended_structural = m_scene->StructuralRevision();
m_suspended_hierarchy = m_scene->Hierarchy().Revision();
m_editable = false;
m_in_phase = false;
m_authoring_suspended = true;
return true;
}

bool EditorSession::ResumeAuthoring()
{
if (!m_initialized || m_owner != std::this_thread::get_id() || !m_authoring_suspended || m_in_phase || m_replacing || !m_scene || m_scene != m_suspended_scene || m_epoch != m_suspended_epoch || m_document_revision != m_suspended_revision || m_scene->StructuralRevision() != m_suspended_structural || m_scene->Hierarchy().Revision() != m_suspended_hierarchy)
return false;
m_suspended_scene = nullptr;
m_authoring_suspended = false;
m_editable = true;
return true;
}

bool EditorSession::AuthoringSuspended() const noexcept
{
return m_authoring_suspended;
}

void EditorSession::SynchronizeHierarchy()
{
if (m_scene)
Expand Down Expand Up @@ -1312,12 +1350,12 @@ namespace Tetragrama

bool EditorSession::SetHovered(EntityID entity)
{
return OnOwnerThread() && m_selection.SetHovered(m_targets, entity);
return OnOwnerThread() && !m_authoring_suspended && m_selection.SetHovered(m_targets, entity);
}

void EditorSession::ClearHovered()
{
if (OnOwnerThread())
if (OnOwnerThread() && !m_authoring_suspended)
{
m_selection.ClearHovered();
}
Expand Down
17 changes: 16 additions & 1 deletion Tetragrama/EditorSession.h
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,15 @@ namespace Tetragrama
void Shutdown();
[[nodiscard]] bool BeginMutationPhase(bool editable = true);
void EndMutationPhase();
/// @brief Cancel transient edits and suspend authoring without replacing the scene or clearing history.
/// @details Owner-thread only, during an editable mutation phase. Pending
/// requests are discarded and new requests are rejected until resume.
[[nodiscard]] bool SuspendAuthoring();
/// @brief Resume the retained scene if its identity and tracked revisions still match.
/// @details Failure leaves authoring suspended for recovery; it never reloads a scene.
[[nodiscard]] bool ResumeAuthoring();
/// @brief Report on the owner thread whether authoring is suspended for a world transition.
[[nodiscard]] bool AuthoringSuspended() const noexcept;
[[nodiscard]] bool BindScene(ZEngine::ECS::Scene* scene, bool saved = true);
[[nodiscard]] bool SetSceneMutationHooks(const EditorSceneMutationHooks& hooks);
[[nodiscard]] bool SetSceneSettingsHooks(const EditorSceneSettingsHooks& hooks);
Expand Down Expand Up @@ -352,7 +361,7 @@ namespace Tetragrama
}
[[nodiscard]] bool Editable() const
{
return m_initialized && !m_replacing && m_editable && m_scene;
return m_initialized && !m_replacing && !m_authoring_suspended && m_editable && m_scene;
}
[[nodiscard]] bool CanUndo() const
{
Expand Down Expand Up @@ -571,6 +580,12 @@ namespace Tetragrama
bool m_initialized = false;
bool m_in_phase = false;
bool m_editable = true;
bool m_authoring_suspended = false;
ZEngine::ECS::Scene* m_suspended_scene = nullptr;
uint64_t m_suspended_epoch = 0;
uint64_t m_suspended_revision = 0;
uint64_t m_suspended_structural = 0;
uint64_t m_suspended_hierarchy = 0;
bool m_preview_changed = false;
bool m_hierarchy_pending = false;
bool m_replacing = false;
Expand Down
Loading
Loading