Skip to content

feat: wait for Play Mode startup and run code once when ready #1437 - #1463

Open
haranishi wants to merge 1 commit into
CoplayDev:betafrom
haranishi:feat/play-mode-startup-1437
Open

haranishi wants to merge 1 commit into
CoplayDev:betafrom
haranishi:feat/play-mode-startup-1437

Conversation

@haranishi

@haranishi haranishi commented Oct 11, 2026 •

Copy link
Copy Markdown

Description

Entering Play Mode alone does not confirm that initialization is complete. A normal domain reload resets static variables set beforehand, and the next operation proceeds before the scene's Start finishes.
Adds startup waiting and post-startup code execution to manage_editor(action="play") so that the next operation can proceed after initialization is complete.

Type of Change

  • New feature (non-breaking change that adds functionality)
  • Documentation update
  • Test update

Changes Made

  • Adds wait_until="scene_loaded"|"first_frame", on_ready_code, and wait_timeout. Post-startup code runs once after Start and 1 frame complete, and its result is returned in data.on_ready_result.
  • Stores startup jobs and executed IDs in Unity's SessionState to support waiting across domain reloads, prevent duplicate execution when the same request ID is resent, and cancel jobs when Play Mode stops or the wait times out.
  • Saves the running state before executing code and treats execution as interrupted after a reload. Uses the existing execute_code for compiler and safety checks.
  • Shares waiting logic between Python and the local CLI's REST path. Does not automatically resend startup requests, and pins the connection target to the project hash when checking status.
  • get_play_mode_startup and the CLI's editor play-status allow status checks after a timeout or a lost response. Existing calls without startup options retain their previous behavior.

Compatibility / Package Source

  • Unity: Verified with 6000.3.20f1 and Unity Test Framework: 1.6.0.
  • Package source: Verified a dedicated working branch created from beta as a local file: package.
  • Base commit: 142ea0af4890337f0ff6658df61db23982313717.
  • The packages-lock Git resolution hash is not applicable because no Git package URL was used.
  • Ran tools/check-unity-versions.sh. The specified 4 versions were not installed, so all 4 checks were skipped.

Testing/Screenshots/Recordings

  • Python tests: 1613 passed, 18 skipped.
  • Unity EditMode tests: 13 added tests passed. Confirmed that 1 test failed before the fix because the new status retrieval action was unsupported.
  • Package import/compile check: Unity 6000.3.20f1.
  • Verified in the test project: request acceptance → normal domain reload → Start and LateUpdate → the code ran 1 time, and still only 1 time when the same ID was resent, and cancellation when Play Mode stopped.
  • Confirmed that when the wait timed out while paused, the code did not execute and Play Mode continued, and that the code did not execute after resuming.
  • Confirmed that restoring a saved running state through an actual reload treated execution as interrupted and did not execute the code again. Also confirmed that Enter Play Mode settings were preserved.
  • Performed the generated-docs --check, checked that both skill copies matched, conducted an independent review, and checked the information in the public diff and PR description.

Documentation Updates

  • I have added/removed/modified tools or resources
  • Updated using tools/UPDATE_DOCS_PROMPT.md
  • Manual review of generated changes
  • Regenerated the tool reference and updated usage examples, the manifest, the CLI reference and guide, and both skill copies.

Related Issues

Fixes #1437

Additional Notes

scene_loaded does not guarantee that Start has completed. Use first_frame or on_ready_code when initialization must be complete.
The default wait is 30 seconds, with a range of 1–300 seconds. A timeout does not stop Play Mode. Pending code is canceled on timeout, but code that has already started executing may complete.
After a lost response, check the returned job ID on the same Unity instance. Results are retained for the latest 16 jobs within the same Editor session.

Fork CI verification

Checked the GitHub Actions results for the same commit 3eaa4b23fed490a159d67e5bc564b59636cc344f. The Python tests succeeded, as did the harness tests that run without Unity.

C# compilation also succeeded with Unity 6000.0.75f1. Runtime and Editor were compiled for each of the Windows, macOS, and Linux configurations.

The docs build succeeded. The generated-docs drift check also succeeded.

The E2E tests and the Unity Editor tests that require a license were skipped.

The upstream GitHub Actions are waiting for a maintainer to approve the run for the current commit. The CI successes above are results from runs on the fork that verified the same commit.

Summary by CodeRabbit

  • New Features
    • Start Play Mode with optional waits for scene loading or the first frame, and run one-time startup code after the first frame.
    • Check startup job status and retrieve results without rerunning startup code. Jobs can be polled after timeouts or lost replies.
  • Documentation
    • Added guidance and examples for startup milestones, timeout limits, polling, and startup job behavior.

@coderabbitai

coderabbitai Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: a57c36f1-ae87-4c1b-9d8b-66189909abc8
📥 Commits

Reviewing files that changed from the base of the PR and between 142ea0a and 3eaa4b2.

📒 Files selected for processing (23)
  • .claude/skills/unity-mcp-skill/SKILL.md
  • .claude/skills/unity-mcp-skill/references/tools-reference.md
  • MCPForUnity/Editor/Services/PlayModeStartupService.cs
  • MCPForUnity/Editor/Services/PlayModeStartupService.cs.meta
  • MCPForUnity/Editor/Tools/ExecuteCode.cs
  • MCPForUnity/Editor/Tools/ManageEditor.cs
  • Server/src/cli/commands/editor.py
  • Server/src/main.py
  • Server/src/services/play_mode_startup.py
  • Server/src/services/tools/manage_editor.py
  • Server/tests/test_editor_startup_cli.py
  • Server/tests/test_play_mode_startup.py
  • Server/tests/test_play_startup_rest.py
  • TestProjects/UnityMCPTests/Assets/Scripts/TestAsmdef/PlayModeStartupTestComponent.cs
  • TestProjects/UnityMCPTests/Assets/Scripts/TestAsmdef/PlayModeStartupTestComponent.cs.meta
  • TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageEditorStartupTests.cs
  • TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageEditorStartupTests.cs.meta
  • manifest.json
  • unity-mcp-skill/SKILL.md
  • unity-mcp-skill/references/tools-reference.md
  • website/docs/guides/cli.md
  • website/docs/reference/cli.md
  • website/docs/reference/tools/core/manage_editor.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 5 remain after this review.

📝 Walkthrough

Adds Play Mode startup waits and one-time startup code to Unity editor commands. Startup jobs track readiness, execution results, and status. Server tools and CLI commands can poll jobs after timeouts or disconnected replies. Documentation and tests cover these behaviors.

Changes: Play Mode startup

Layer / File(s) Summary
Unity startup job lifecycle
MCPForUnity/Editor/Services/PlayModeStartupService.cs, MCPForUnity/Editor/Tools/ExecuteCode.cs, TestProjects/UnityMCPTests/Assets/Scripts/TestAsmdef/*, TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageEditorStartupTests.cs
Unity now tracks startup readiness and code execution in persisted jobs. Jobs report status and results, and tests cover validation, readiness, and terminal states.
Unity editor actions
MCPForUnity/Editor/Tools/ManageEditor.cs
The play action starts a startup job, and get_play_mode_startup retrieves its status. The stop action cancels waiting jobs.
Server startup request and polling
Server/src/services/play_mode_startup.py, Server/src/services/tools/manage_editor.py, Server/src/main.py, Server/tests/test_play_mode_startup.py, Server/tests/test_play_startup_rest.py
The server validates startup options, submits the request once, and polls the job on the bound Unity instance. MCP and REST routing use this flow, with tests for polling and instance binding.
CLI commands and usage documentation
Server/src/cli/commands/editor.py, Server/tests/test_editor_startup_cli.py, manifest.json, unity-mcp-skill/*, .claude/skills/unity-mcp-skill/*, website/docs/guides/cli.md, website/docs/reference/cli.md, website/docs/reference/tools/core/manage_editor.md
The CLI supports startup waits, startup code, and play-status. Tests and documentation describe the options, job polling, timeouts, and retained results.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant Server
  participant ManageEditor
  participant PlayModeStartupService
  participant ExecuteCode
  CLI->>Server: Send play request with startup options
  Server->>ManageEditor: Send startup request once
  ManageEditor->>PlayModeStartupService: Create startup job
  PlayModeStartupService->>ExecuteCode: Run on-ready code when ready
  ExecuteCode-->>PlayModeStartupService: Return code result
  Server->>ManageEditor: Poll job by ID
  ManageEditor-->>Server: Return job status and result
  Server-->>CLI: Return startup result
Loading

Suggested reviewers: scriptwonder

Merge Risk: ⚪ Minimal · up to 3eaa4

No actionable merge-blocking issue was established. First-frame timing across Play Mode entry remains unverified.

Pre-merge checks · Passed 4 · Failed 1

Failed Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 7.35% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 68 functions across 12 files. (11 skipped:… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks (4 passed)
Check name Status Explanation
Linked Issues check Passed Issue #1437 requires optional on_ready_code after the first scene load and one frame, or wait_until values scene_loaded and first_frame. The PR adds these options to `manage_editor(action="pla…
Out of Scope Changes check Passed The changes remain within issue #1437. The Unity service, Python REST and CLI paths, status polling, tests, and generated documentation support Play Mode startup waiting or one-time startup code. No u…
Title check Passed The title clearly and concisely describes the primary feature: waiting for Play Mode startup and running code once when ready.
Description check Passed The description follows the repository template and provides the feature summary, change details, compatibility information, testing results, documentation updates, related issue, and additional notes…
Full details: Docstring Coverage

Explanation

Docstring coverage is 7.35% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 68 functions across 12 files. (11 skipped: 11 unsupported.)

  • Fix all pre-merge checks with AI
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@haranishi
haranishi marked this pull request as ready for review October 13, 2026 08:35
Copilot AI balanced review requested due to automatic review settings October 13, 2026 08:35

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@haranishi haranishi changed the title feat: Play Mode開始待ちと開始後コードの実行を追加 #1437 feat: wait for Play Mode startup and run code once when ready #1437 Oct 13, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Run code (or wait) after Play Mode startup — statics set before play are wiped by domain reload

2 participants