summer-engine 2.8.2 → 3.1.0

package/library/tools/get-asset/resource.yaml

@@ -0,0 +1,42 @@
+id: tool/get-asset
+kind: tool
+version: 1.0.2
+summary: Fetch one asset by exact Summer asset id, including stable file URL, metadata, license, visibility, and provider details.
+use_when:
+  - a generation job returned an asset id and you need its file URL or metadata
+  - confirming license or visibility before reuse
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - pipeline
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_asset
+implementation:
+  module: src/mcp/tools/asset-tools.ts
+  export: registerAssetTools
+surfaces:
+  mcp:
+    tool_name: summer_get_asset
+    remote: true
+input_schema:
+  type: object
+  properties:
+    assetId:
+      type: string
+      description: Summer ArtAssets id
+  required:
+    - assetId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/get-asset-download-url/resource.yaml

@@ -0,0 +1,52 @@
+id: tool/get-asset-download-url
+kind: tool
+version: 1.0.2
+summary: Get a download URL for a specific asset file (primary or thumbnail), future-proofed for signed URLs.
+use_when:
+  - the user explicitly asks to download an asset file
+  - '"give me a link to the model file / the thumbnail"'
+  - handing a file to something outside the engine (a viewer, a Blender import)
+do_not_use_when:
+  - importing into the project (import by asset id instead)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - pipeline
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_asset_download_url
+implementation:
+  module: src/mcp/tools/asset-tools.ts
+  export: registerAssetTools
+surfaces:
+  mcp:
+    tool_name: summer_get_asset_download_url
+    remote: true
+input_schema:
+  type: object
+  properties:
+    assetId:
+      type: string
+      description: Summer ArtAssets id
+    role:
+      type: string
+      enum:
+        - primary
+        - thumbnail
+      default: primary
+      description: Which file to download
+  required:
+    - assetId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/get-console/resource.yaml

@@ -0,0 +1,69 @@
+id: tool/get-console
+kind: tool
+version: 1.0.3
+summary: Read recent editor Output panel messages, deduplicated and filterable by level, type, or substring. Editor console only - never the post-play verdict.
+use_when:
+  - diagnostics report console issues and you need the message bodies
+  - '"what did the game print?" / "show me the log output"'
+  - checking whether your print() statements fired
+do_not_use_when:
+  - runtime errors with stack traces — summer_get_debugger_errors
+  - compile errors in a script you just edited — summer_get_script_errors
+  - the post-play verdict — a played game's runtime errors live in the debugger, so this can report 0 errors after a failing run; read summer_get_diagnostics first
+facets:
+  lifecycle:
+    - build
+  domains:
+    - debug
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_console
+implementation:
+  module: src/mcp/tools/debug-tools.ts
+  export: registerDebugTools
+surfaces:
+  mcp:
+    tool_name: summer_get_console
+    remote: false
+input_schema:
+  type: object
+  properties:
+    max_lines:
+      type: number
+      default: 100
+      description: Max lines to return after dedupe (default 100)
+    filter:
+      type: string
+      description: Only return lines containing this string
+    type:
+      type: string
+      enum:
+        - error
+        - warning
+        - std
+        - editor
+      description: Filter by message type at the engine level
+    errors_only:
+      type: boolean
+      default: true
+      description: Drop info/std noise, keep errors and warnings (default true)
+    strict_errors:
+      type: boolean
+      default: false
+      description: Drop warnings too — return errors only
+    raw:
+      type: boolean
+      default: false
+      description: Bypass dedupe and level filtering — return engine output verbatim
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/get-debugger-errors/resource.yaml

@@ -0,0 +1,56 @@
+id: tool/get-debugger-errors
+kind: tool
+version: 1.0.2
+summary: Read deduplicated runtime errors from the debugger, distinct from console prints; optional stack traces.
+use_when:
+  - the running game hit failures like null references or missing nodes
+  - '"the game crashed while I was playing, what was it?"'
+  - '"why did my scene fail at runtime?"'
+do_not_use_when:
+  - the script will not even compile — summer_get_script_errors
+  - plain print output — summer_get_console
+facets:
+  lifecycle:
+    - build
+  domains:
+    - debug
+    - runtime
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_debugger_errors
+implementation:
+  module: src/mcp/tools/debug-tools.ts
+  export: registerDebugTools
+surfaces:
+  mcp:
+    tool_name: summer_get_debugger_errors
+    remote: false
+input_schema:
+  type: object
+  properties:
+    max_errors:
+      type: number
+      default: 50
+      description: Max errors to return after dedupe
+    include_stack:
+      type: boolean
+      description: Include stack traces for each error
+    include_warnings:
+      type: boolean
+      default: false
+      description: Forward-compat flag — when engine supports it, returns warning bodies in the same call. Today the engine ignores it; use summer_get_debugger_warnings instead.
+    raw:
+      type: boolean
+      default: false
+      description: Bypass dedupe — return engine output verbatim
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/get-debugger-warnings/resource.yaml

@@ -0,0 +1,52 @@
+id: tool/get-debugger-warnings
+kind: tool
+version: 1.0.2
+summary: Read runtime warnings from the debugger panel as structured entries with file, line, and callstack.
+use_when:
+  - diagnostics show a non-zero debugger warning count
+  - '"the debugger shows yellow warnings, what are they?"'
+  - checking for deprecated calls or node configuration warnings after a run
+do_not_use_when:
+  - errors, not warnings — summer_get_debugger_errors
+facets:
+  lifecycle:
+    - build
+  domains:
+    - debug
+    - runtime
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_debugger_warnings
+implementation:
+  module: src/mcp/tools/debug-tools.ts
+  export: registerDebugTools
+surfaces:
+  mcp:
+    tool_name: summer_get_debugger_warnings
+    remote: false
+input_schema:
+  type: object
+  properties:
+    max_warnings:
+      type: number
+      default: 50
+      description: Max warnings to return after dedupe
+    include_stack:
+      type: boolean
+      default: true
+      description: Include stack traces
+    raw:
+      type: boolean
+      default: false
+      description: Bypass dedupe
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/get-diagnostics/resource.yaml

@@ -0,0 +1,42 @@
+id: tool/get-diagnostics
+kind: tool
+version: 1.0.3
+summary: Prioritized overview of editor console, runtime debugger, and script errors and warnings, with complete counts and a trimmed noise tail.
+use_when:
+  - first stop after any change, before targeted console or debugger reads
+  - verifying a fix removed the errors it targeted
+  - 'the post-play read after summer_play or a RunVerification probe: runtime errors land in the debugger section here, never in the console'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - debug
+    - verification
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_diagnostics
+implementation:
+  module: src/mcp/tools/debug-tools.ts
+  export: registerDebugTools
+surfaces:
+  mcp:
+    tool_name: summer_get_diagnostics
+    remote: false
+input_schema:
+  type: object
+  properties:
+    includeAll:
+      type: boolean
+      default: false
+      description: Return the full engine diagnostics payload untrimmed (no severity reordering, no info-noise cap).
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/get-project-context/resource.yaml

@@ -0,0 +1,45 @@
+id: tool/get-project-context
+kind: tool
+version: 1.1.0
+summary: Bind to the open project and return engine health, project name and path, current and main scene, trimmed settings, the template pin, and memory summary.
+use_when:
+  - first call in every fresh session, to avoid guessing scene filenames
+  - deliberately rebinding after the engine switched projects
+facets:
+  lifecycle:
+    - build
+  domains:
+    - project
+    - engine
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_project_context
+implementation:
+  module: src/mcp/tools/project-tools.ts
+  export: registerProjectTools
+surfaces:
+  mcp:
+    tool_name: summer_get_project_context
+    remote: false
+input_schema:
+  type: object
+  properties:
+    settingsPrefix:
+      type: string
+      description: Only return project settings whose key starts with this prefix, e.g. 'audio/' or 'application/config/'. Omit for the curated default set.
+    settingsPrefixes:
+      type: array
+      items:
+        type: string
+      description: Several settings groups at once, e.g. ['audio/', 'layer_names/2d_physics/', 'input/ui_']. Merged with settingsPrefix. Omit for the curated default set.
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/get-runtime-tree/resource.yaml

@@ -0,0 +1,62 @@
+id: tool/get-runtime-tree
+kind: tool
+version: 1.0.1
+summary: Scene tree of the RUNNING game — spawned enemies, autoloads, pooled nodes — live state the editor reads can never show.
+use_when:
+  - inspecting what actually spawned during a playtest without stopping the game
+  - '"which enemies are actually alive right now?"'
+  - '"what did the spawner create?" / "is the autoload there?"'
+do_not_use_when:
+  - no game is running (failure_reason game_not_running) — summer_play first, or read the edited scene with summer_get_scene_tree
+  - "requires an engine build with GetRuntimeSceneTree (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - runtime
+    - verification
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/inspect-runtime-node
+    - tool/play
+    - tool/get-scene-tree
+  skills:
+    - skill/verifying-scenes
+    - skill/playtesting-a-feature
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_get_runtime_tree
+implementation:
+  module: src/mcp/tools/perception-tools.ts
+  export: registerPerceptionTools
+surfaces:
+  mcp:
+    tool_name: summer_get_runtime_tree
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      description: Subtree root to read, e.g. '/root/Main/Enemies'. Omit for the scene tree root.
+    depth:
+      type: integer
+      exclusiveMinimum: 0
+      description: Maximum depth to walk (engine default 3).
+    limit:
+      type: integer
+      exclusiveMinimum: 0
+      description: Maximum nodes to return (engine default 500).
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/get-scene-tree/resource.yaml

@@ -0,0 +1,52 @@
+id: tool/get-scene-tree
+kind: tool
+version: 1.0.2
+summary: Read a scene's node tree, with explicit depth and limit to avoid the engine's silent default truncation.
+use_when:
+  - inspecting scene structure before or after mutations
+  - '"what nodes are in this scene?" / "how is the level structured?"'
+  - finding the path of the player node before editing it
+do_not_use_when:
+  - the RUNNING game's tree — summer_get_runtime_tree
+  - transforms and bounds, not just names — summer_world_snapshot
+facets:
+  lifecycle:
+    - build
+  domains:
+    - project
+    - scenes
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_scene_tree
+implementation:
+  module: src/mcp/tools/project-tools.ts
+  export: registerProjectTools
+surfaces:
+  mcp:
+    tool_name: summer_get_scene_tree
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Exact res:// scene path to inspect
+    depth:
+      type: integer
+      exclusiveMinimum: 0
+      description: Maximum tree depth to walk. Engine default is 2 — pass a larger value for deep hierarchies.
+    limit:
+      type: integer
+      exclusiveMinimum: 0
+      description: Maximum number of nodes to return. Engine default is 200.
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/get-script-errors/resource.yaml

@@ -0,0 +1,45 @@
+id: tool/get-script-errors
+kind: tool
+version: 1.0.2
+summary: Check one GDScript file for parse and compile errors without running the game.
+use_when:
+  - after writing or editing a .gd file, to verify it compiles
+  - '"does this script compile?" / "is there a syntax error in player.gd?"'
+  - the editor shows a red error marker on a .gd file
+do_not_use_when:
+  - runtime failures while playing — summer_get_debugger_errors
+facets:
+  lifecycle:
+    - build
+  domains:
+    - debug
+    - scripting
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_script_errors
+implementation:
+  module: src/mcp/tools/debug-tools.ts
+  export: registerDebugTools
+surfaces:
+  mcp:
+    tool_name: summer_get_script_errors
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      description: Script path, e.g. 'res://scripts/player.gd' or 'res://player_controller.gd'
+  required:
+    - path
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/get-studio-workflow/resource.yaml

@@ -0,0 +1,43 @@
+id: tool/get-studio-workflow
+kind: tool
+version: 1.0.2
+summary: "Discover Summer Studio's guided workflow recipes: starter prompts, ordered steps, required tools, and honest support levels."
+use_when:
+  - planning a multi-step asset workflow like sprite sheets or character packs
+  - '"what is the recommended sequence for a full character with animations?"'
+  - '"which tools do I need for a tileset pack?"'
+do_not_use_when:
+  - you already know the exact tool to call — call it
+facets:
+  lifecycle:
+    - build
+  domains:
+    - generate
+    - pipeline
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_studio_workflow
+implementation:
+  module: src/mcp/tools/generate-tools.ts
+  export: registerGenerateTools
+surfaces:
+  mcp:
+    tool_name: summer_get_studio_workflow
+    remote: true
+input_schema:
+  type: object
+  properties:
+    workflowId:
+      type: string
+      description: Guided workflow id, e.g. sprite-sheet, character-pack, asset-pack, or component-compiler
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/import-asset/resource.yaml

@@ -0,0 +1,73 @@
+id: tool/import-asset
+kind: tool
+version: 1.0.2
+summary: Search the asset library and import the best match into the project in one step, optionally adding 3D models to a scene.
+use_when:
+  - the user asks to add a kind of asset, like 'add a tree to the scene'
+  - '"put a rock / a barrel / a torch in the scene from the library"'
+  - '"find me a free chest model and drop it in"'
+do_not_use_when:
+  - you already know the exact asset id (import by id instead)
+  - the asset is at a URL, not in the Summer library — summer_import_from_url
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - project
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_import_asset
+implementation:
+  module: src/mcp/tools/asset-tools.ts
+  export: registerAssetTools
+surfaces:
+  mcp:
+    tool_name: summer_import_asset
+    remote: false
+input_schema:
+  type: object
+  properties:
+    query:
+      type: string
+      description: What to find, e.g. 'low-poly tree', 'wooden crate'
+    parent:
+      type: string
+      description: Parent node path to add the asset under, e.g. './World'. If omitted, only imports (no scene placement)
+    scenePath:
+      type: string
+      description: Required with parent. Exact res:// target scene path.
+    assetType:
+      type: string
+      enum:
+        - 2d_image
+        - animation
+        - 3d_model
+        - audio
+        - music
+        - all
+      default: 3d_model
+      description: Preferred asset type
+    source:
+      type: string
+      enum:
+        - library
+        - my_assets
+        - all
+      default: all
+      description: Where to search before importing
+  required:
+    - query
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - asset-imported

package/library/tools/import-asset-by-id/resource.yaml

@@ -0,0 +1,56 @@
+id: tool/import-asset-by-id
+kind: tool
+version: 1.0.2
+summary: Import an exact Summer asset id into the open project via the engine's import pipeline; optionally instantiate 3D models into a scene.
+use_when:
+  - importing a just-generated or searched asset without guessing
+  - placing a 3D model into an exact scene by parent path
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - project
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_import_asset_by_id
+implementation:
+  module: src/mcp/tools/asset-tools.ts
+  export: registerAssetTools
+surfaces:
+  mcp:
+    tool_name: summer_import_asset_by_id
+    remote: false
+input_schema:
+  type: object
+  properties:
+    assetId:
+      type: string
+      description: Summer ArtAssets id
+    path:
+      type: string
+      description: Optional target res:// path. If omitted, a path is inferred from asset type and filename.
+    parent:
+      type: string
+      description: Optional parent node path. For 3D models only; imports and instantiates under this node.
+    scenePath:
+      type: string
+      description: Required with parent. Exact res:// scene that receives the 3D model.
+    name:
+      type: string
+      description: Optional scene node name when parent is provided.
+  required:
+    - assetId
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - asset-imported