summer-engine 2.8.2 → 3.0.0

package/library/tools/navigation-probe/resource.yaml

@@ -0,0 +1,85 @@
+id: tool/navigation-probe
+kind: tool
+version: 1.0.0
+summary: Read-only reachability between two world points on the scene's Godot navigation map — readiness, snapped endpoints, route length, up to 16 route points.
+use_when:
+  - placing an NPC, pickup, portal, or encounter anchor whose route from spawn matters
+  - checking that a moved prop did not cut the navigation mesh between two areas
+do_not_use_when:
+  - the scene has no NavigationRegion3D (ready is false; there is nothing to probe)
+  - you need live agent behaviour — playtest with summer_play and read summer_get_runtime_tree
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+    - navigation
+    - verification
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/test-placement
+    - tool/world-snapshot
+    - tool/play
+  skills:
+    - skill/world-building-3d
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_navigation_probe
+implementation:
+  module: src/mcp/tools/spatial-tools.ts
+  export: registerSpatialTools
+surfaces:
+  mcp:
+    tool_name: summer_navigation_probe
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Exact 3D scene whose World3D navigation map should be queried.
+    start:
+      type: array
+      items:
+        type: number
+      minItems: 3
+      maxItems: 3
+      description: Requested world-space route start [x,y,z].
+    end:
+      type: array
+      items:
+        type: number
+      minItems: 3
+      maxItems: 3
+      description: Requested world-space route destination [x,y,z].
+    navigationLayers:
+      type: integer
+      minimum: 1
+      maximum: 4294967295
+      default: 1
+      description: Godot navigation-layer bitmask; only enabled matching regions are used.
+    optimize:
+      type: boolean
+      default: true
+      description: Use Godot's corridor-funnel path post-processing; false uses edge-centered points.
+  required:
+    - scenePath
+    - start
+    - end
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/open/resource.yaml

@@ -0,0 +1,80 @@
+id: tool/open
+kind: tool
+version: 1.0.1
+summary: Open the exact summerengine.com page or editor surface by intent name — billing, my games, an MCP guide, a scene, a node, a dock — or print the URL/op.
+use_when:
+  - the user wants to SEE or DECIDE something on the website — "open my billing page", "show me my published games", "take me to pricing", "open the MCP setup guide for Cursor"
+  - the user wants to LOOK at something in the running editor — "show me the scene", "select the Player node", "open player.gd", "reveal that texture in the file dock"
+  - '"open the main scene in the editor" / "open the scene I am editing so I can look at it" — an editor surface the USER should see, navigated for them (the scene tools open a tab for the agent, not for the user)'
+  - 'handing the user a link instead of opening a browser (open: false), or checking which destination an intent maps to'
+  - resolving where a user intent lives ("where do I change my plan?") before acting
+do_not_use_when:
+  - the user wants a result, not a view — add the node, set the property, publish; use the mutation tools (summer_add_node, summer_set_prop, summer_creator_publish)
+  - opening a project directory in the engine — that is the CLI's `summer open <path>` / `summer run <path>` project launcher, not a navigation target
+  - the destination is not on summerengine.com or docs.summerengine.com — the tool refuses other origins
+facets:
+  lifecycle:
+    - build
+    - launch
+    - support
+  domains:
+    - navigation
+    - agent-workflow
+    - project
+  modalities:
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  references:
+    - reference/product-map
+  skills:
+    - skill/navigate-summer
+  tools:
+    - tool/open-scene
+    - tool/select-node
+    - tool/open-main-scene
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_open
+implementation:
+  module: src/mcp/tools/navigation-tools.ts
+  export: registerNavigationTools
+surfaces:
+  mcp:
+    tool_name: summer_open
+    remote: false
+  cli:
+    command: summer open
+input_schema:
+  type: object
+  properties:
+    target:
+      type: string
+      description: 'Where to go: a target id (billing, my-games, mcp-guide, scene, node, inspector, …), an intent phrase ("change my plan", "show me my published games"), a res:// path (routed by extension to scene / script / file), or a summerengine.com path ("/pricing"). Omit to list every target.'
+    params:
+      type: object
+      additionalProperties:
+        type: string
+      description: 'Slot values for the target: gameId, section (builds, releases, store-page, …), username, version, guide (agent name or guide slug), path (res://…), node (Player/Camera3D), scene (res://…tscn to open before selecting a node), line and col (script), tab (project-settings).'
+    surface:
+      type: string
+      enum:
+        - auto
+        - web
+        - editor
+      description: Restrict matching to the website or the editor. "auto" (default) considers both.
+    open:
+      type: boolean
+      description: Default true. false = resolve only — return the URL or engine op and open nothing (works without the engine and without a browser); the CLI's --print.
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - target-resolved

package/library/tools/open-main-scene/resource.yaml

@@ -0,0 +1,40 @@
+id: tool/open-main-scene
+kind: tool
+version: 1.0.2
+summary: Open the project's configured main scene from project settings instead of guessing scene filenames.
+use_when:
+  - any tool reports that no scene is open
+  - "\"get me back to the game's main scene\""
+  - a fresh session with no active scene tab
+do_not_use_when:
+  - a specific non-main scene — summer_open_scene with its path
+facets:
+  lifecycle:
+    - build
+  domains:
+    - project
+    - scenes
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_open_main_scene
+implementation:
+  module: src/mcp/tools/project-tools.ts
+  export: registerProjectTools
+surfaces:
+  mcp:
+    tool_name: summer_open_main_scene
+    remote: false
+input_schema:
+  type: object
+  properties: {}
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false

package/library/tools/open-scene/resource.yaml

@@ -0,0 +1,46 @@
+id: tool/open-scene
+kind: tool
+version: 1.0.2
+summary: Open a scene file in the editor to switch tabs.
+use_when:
+  - switching the editor to an explicitly known scene path
+  - '"switch to level2.tscn" / "open the player prefab in the editor"'
+  - a tool needs a different scene to be the active tab
+do_not_use_when:
+  - guessing scene filenames (resolve them from project context first)
+  - the project's main scene — summer_open_main_scene
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_open_scene
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_open_scene
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      description: Scene path, e.g. 'res://main.tscn' or 'res://levels/level1.tscn'
+  required:
+    - path
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false

package/library/tools/play/resource.yaml

@@ -0,0 +1,91 @@
+id: tool/play
+kind: tool
+version: 1.2.0
+summary: Start the game quietly by default (editor keeps tab and focus; focus true for a toolbar-style launch) — main or a given scene, embedded or offscreen, with pins.
+use_when:
+  - runtime verification after edits
+  - the user wants to try the game or one level after a change
+  - reproducing a bug that only shows at runtime
+  - a deterministic, repeatable playtest run — pin the global RNG with seed and the timestep with fixed_fps
+  - launching a deterministic or parallel offscreen playtest instance (seed, fixed frame rate, named offscreen instance) for the runtime tools to drive
+  - launching while the user works on the same machine — the default (focus omitted or false) sends PlayGame agent:true, so the editor does not switch to the Game tab or grab focus; the game still runs embedded and is visible to the runtime tools
+do_not_use_when:
+  - the game is already running and needs a restart — summer_stop first (seed/fixed_fps cannot reach a game that is already up)
+  - "focus: true unless the user is watching and asked to see the game come up — it launches like the toolbar Play button (Game tab + focus). Quiet play does not hide the game; on engines without the background launch posture a user whose Embed Game on Play is off still gets the game in its own OS window as always, while engines with the posture (0.5.66+) also launch that window with --summer-background so it never takes focus"
+  - only checking whether it is running — summer_is_running
+  - "instance/mode/deterministic need an engine build with the runtime-control ops (Summer Engine 0.5.66 or newer); older engines return for those parameters engine_lacks_op (plain play still works)"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - debug
+    - runtime
+    - verification
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_play
+implementation:
+  module: src/mcp/tools/debug-tools.ts
+  export: registerDebugTools
+surfaces:
+  mcp:
+    tool_name: summer_play
+    remote: false
+related:
+  tools:
+    - tool/stop
+    - tool/is-running
+    - tool/game-probe
+    - tool/game-control
+    - tool/game-input
+  skills:
+    - skill/agent-playtesting
+    - skill/playtesting-a-feature
+input_schema:
+  type: object
+  properties:
+    scene:
+      type: string
+      description: Scene to run instead of main scene, e.g. 'res://levels/test_level.tscn'
+    instance:
+      type: string
+      description: Name a game instance. 'main' (default) = the editor's embedded game. Any other name with mode 'offscreen' spawns a disposable parallel instance (at most 3) that the runtime tools address by this name.
+    mode:
+      type: string
+      enum:
+        - embedded
+        - offscreen
+      description: "'embedded' (default) plays in the editor; 'offscreen' spawns a hidden child process (requires instance != 'main')."
+    deterministic:
+      type: boolean
+      description: Offscreen only — launch with --fixed-fps 60 --summer-seed <seed> --audio-driver Dummy so the run is reproducible and input replays with seed are accepted.
+    seed:
+      type: integer
+      description: "Pin the game's GLOBAL RNG for this launch (child gets --summer-seed <seed>; default 20260725 when deterministic:true and seed is omitted). Pins randi/randf/randi_range/randf_range/randfn, Array.shuffle/pick_random. Does NOT pin RandomNumberGenerator instances, scripts calling randomize(), or wall-clock reads. Omitted = randomized, as always."
+    fixed_fps:
+      type: integer
+      exclusiveMinimum: 0
+      description: "Fixed timestep for this launch (child gets --fixed-fps <n>): scene time decouples from the wall clock, the game runs as fast as it renders, frame-count-derived state repeats run to run, and at_ms input timing / GameStep frames map exactly. Opt-in per launch, never the default."
+    time_scale:
+      type: number
+      exclusiveMinimum: 0
+      description: Engine time scale for this launch (child gets --time-scale <f>). Not a determinism pin on its own.
+    speed:
+      type: number
+      description: User time scale applied on session start, (0, 100] — e.g. 0.5 for half speed.
+    focus:
+      type: boolean
+      description: "Default false = QUIET play (PlayGame agent:true): the editor does not switch to the Game tab or grab focus for the embedded game, so the user keeps working. Pass true to launch the way the toolbar Play button does (Game tab + focus) — only when the user is watching and asked to see it. The result echoes agent_quiet:true when honoured; a launch result without it (posture_note) means the engine predates quiet play and most likely took focus."
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - is-running

package/library/tools/project-setting/resource.yaml

@@ -0,0 +1,53 @@
+id: tool/project-setting
+kind: tool
+version: 1.0.2
+summary: Set one project.godot setting, like main scene, window size, renderer, or gravity.
+use_when:
+  - configuring project-level behavior
+  - '"make the game start on Level1" — changing the main scene'
+  - '"set the resolution / fullscreen / gravity / physics tick rate"'
+do_not_use_when:
+  - per-node properties — summer_set_prop
+  - key bindings — summer_input_map_bind
+facets:
+  lifecycle:
+    - build
+  domains:
+    - project
+    - engine
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_project_setting
+implementation:
+  module: src/mcp/tools/project-tools.ts
+  export: registerProjectTools
+surfaces:
+  mcp:
+    tool_name: summer_project_setting
+    remote: false
+input_schema:
+  type: object
+  properties:
+    key:
+      type: string
+      description: Setting key path, e.g. 'application/config/name'
+    value:
+      type:
+        - string
+        - number
+        - boolean
+      description: Setting value
+  required:
+    - key
+    - value
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false

package/library/tools/read-file/resource.yaml

@@ -0,0 +1,47 @@
+id: tool/read-file
+kind: tool
+version: 1.0.2
+summary: Read a text file from the engine-bound project and return its full-file sha256 receipt for guarded overwrites.
+use_when:
+  - reading project files through the engine
+  - getting the sha256 required before overwriting a file
+facets:
+  lifecycle:
+    - build
+  domains:
+    - file
+    - project
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_read_file
+implementation:
+  module: src/mcp/tools/file-tools.ts
+  export: registerFileTools
+surfaces:
+  mcp:
+    tool_name: summer_read_file
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      description: Project path, e.g. res://scripts/player.gd
+    max_bytes:
+      type: integer
+      exclusiveMinimum: 0
+      maximum: 1000000
+      default: 200000
+  required:
+    - path
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/read-library/resource.yaml

@@ -0,0 +1,67 @@
+id: tool/read-library
+kind: tool
+version: 1.0.0
+summary: Load one library entry by id — a skill's body and metadata, a tool's call recipe, a template's pin, a reference's text — ending in the feedback footer.
+use_when:
+  - summer_search_library returned an id and you need the entry itself before acting
+  - re-reading a skill or reference the current version of (entries evolve — never rely on memory of one)
+  - checking how to call a tool or how a template is pinned without walking the library folders
+do_not_use_when:
+  - you do not know the id yet — summer_search_library first
+  - the skill is installed in your host — invoking it there (Claude Code /<slug>) loads the same body
+facets:
+  lifecycle:
+    - build
+    - launch
+    - grow
+    - support
+  domains:
+    - agent-workflow
+    - meta
+    - mcp
+  modalities:
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/search-library
+    - tool/library-feedback
+  skills:
+    - skill/using-summer
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_read_library
+implementation:
+  module: src/mcp/tools/library-tools.ts
+  export: registerLibraryTools
+surfaces:
+  mcp:
+    tool_name: summer_read_library
+    remote: true
+input_schema:
+  type: object
+  properties:
+    id:
+      type: string
+      minLength: 1
+      maxLength: 200
+      description: The entry id as returned by summer_search_library, <kind>/<slug>, e.g. skill/vfx-water-ripple or tool/screenshot.
+    part:
+      type: string
+      enum:
+        - skill
+        - resource
+        - all
+      description: skill = the body only (SKILL.md for skills, markdown body for references, how-to-call for tools, pin for templates); resource = the resource.yaml descriptor only; all (default) = both.
+  required:
+    - id
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/recent-events/resource.yaml

@@ -0,0 +1,71 @@
+id: tool/recent-events
+kind: tool
+version: 1.0.0
+summary: Read the newest engine events (saves, plays, op receipts, script errors, imports) in one zero-wait poll — and the next_seq cursor to wait from.
+use_when:
+  - '"what just happened in the engine?" / "show me the recent events" — the last saves, plays, op receipts, script errors, imports'
+  - taking a cursor BEFORE triggering an action you will wait on — pass its next_seq as `since` to summer_wait_for_event
+  - after a summer_wait_for_event timeout, reading everything that arrived since its next_seq
+do_not_use_when:
+  - blocking until something happens — summer_wait_for_event
+  - full console or debugger bodies — summer_get_console / summer_get_debugger_errors (events carry compact payloads, clamped at 4 KB)
+  - "requires an engine build with the events channel (capabilities.events, /api/events; Summer Engine 0.5.66 or newer); older engines return engine_lacks_events"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - runtime
+    - verification
+    - debug
+  modalities:
+    - project
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/wait-for-event
+    - tool/play
+    - tool/run-script
+    - tool/get-console
+  skills:
+    - skill/verifying-scenes
+    - skill/playtesting-a-feature
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_recent_events
+implementation:
+  module: src/mcp/tools/event-tools.ts
+  export: registerEventTools
+surfaces:
+  mcp:
+    tool_name: summer_recent_events
+    remote: false
+  cli:
+    command: summer events
+input_schema:
+  type: object
+  properties:
+    since:
+      type: integer
+      minimum: 0
+      description: "Deliver events with seq > since. Omit = the newest `limit` sequence numbers. 0 = the whole retained ring from the oldest (paged: pass next_seq back while truncated is true)."
+    kinds:
+      type: array
+      items:
+        type: string
+      description: "Event kinds to deliver (default: all). v1 kinds: op.applied, op.failed, script.error, play.started, play.stopped, scene.saved, scene.opened, import.completed, selection.changed, snapshot.published."
+    limit:
+      type: integer
+      minimum: 1
+      maximum: 200
+      default: 50
+      description: Maximum events to return (default 50, cap 200).
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/remove-node/resource.yaml

@@ -0,0 +1,51 @@
+id: tool/remove-node
+kind: tool
+version: 1.0.2
+summary: Remove a node and all its children from a scene; undoable, but destructive.
+use_when:
+  - deleting scene content the user asked to remove
+  - '"delete the old camera" / "get rid of the debug label"'
+  - removing the placeholder cube now that the real model is in
+do_not_use_when:
+  - bulk-deleting top-level nodes without an explicit user request
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_remove_node
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_remove_node
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Target scene path, e.g. 'res://main.tscn'
+    path:
+      type: string
+      description: Node path to remove, e.g. './World/OldEnemy'
+  required:
+    - scenePath
+    - path
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/replace-node/resource.yaml

@@ -0,0 +1,57 @@
+id: tool/replace-node
+kind: tool
+version: 1.0.2
+summary: Replace a node with a different type or scene, preserving its tree position and children.
+use_when:
+  - swapping a placeholder for a prefab or changing a body type
+  - '"turn this StaticBody3D into a RigidBody3D but keep its children"'
+  - swapping the placeholder cube for the real prefab in place
+do_not_use_when:
+  - adding alongside instead of replacing — summer_add_node / summer_instantiate_scene
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_replace_node
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_replace_node
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Target scene path, e.g. 'res://main.tscn'
+    path:
+      type: string
+      description: Node path to replace
+    type:
+      type: string
+      description: New node type, e.g. 'RigidBody3D'
+    scene:
+      type: string
+      description: Scene to replace with, e.g. 'res://enemies/boss.tscn'
+  required:
+    - scenePath
+    - path
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid