summer-engine 2.8.2 → 3.1.0

package/library/tools/import-from-url/resource.yaml

@@ -0,0 +1,51 @@
+id: tool/import-from-url
+kind: tool
+version: 1.0.2
+summary: Download one file from a URL and run Godot's full import pipeline so the asset is immediately usable.
+use_when:
+  - importing a model, texture, or audio file from an external URL
+  - '"grab this .glb from the link and add it to my project"'
+  - '"download this texture from the web into res://"'
+do_not_use_when:
+  - several files at once — summer_import_from_url_batch
+  - searching the Summer library instead of a known URL — summer_import_asset
+facets:
+  lifecycle:
+    - build
+  domains:
+    - project
+    - assets
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_import_from_url
+implementation:
+  module: src/mcp/tools/project-tools.ts
+  export: registerProjectTools
+surfaces:
+  mcp:
+    tool_name: summer_import_from_url
+    remote: false
+input_schema:
+  type: object
+  properties:
+    url:
+      type: string
+      description: HTTP(S) URL to download from
+    path:
+      type: string
+      description: Target path in project, e.g. 'res://assets/player.glb'. Auto-inferred from URL if omitted.
+  required:
+    - url
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - asset-imported

package/library/tools/import-from-url-batch/resource.yaml

@@ -0,0 +1,60 @@
+id: tool/import-from-url-batch
+kind: tool
+version: 1.0.2
+summary: Download multiple files by URL in one operation with a single filesystem scan afterwards.
+use_when:
+  - importing several related files, like a model plus its textures
+  - '"download the model plus its three textures together"'
+  - '"pull all these sound files into the project"'
+do_not_use_when:
+  - one file — summer_import_from_url
+facets:
+  lifecycle:
+    - build
+  domains:
+    - project
+    - assets
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_import_from_url_batch
+implementation:
+  module: src/mcp/tools/project-tools.ts
+  export: registerProjectTools
+surfaces:
+  mcp:
+    tool_name: summer_import_from_url_batch
+    remote: false
+input_schema:
+  type: object
+  properties:
+    imports:
+      type: array
+      items:
+        type: object
+        properties:
+          url:
+            type: string
+            description: URL to download
+          path:
+            type: string
+            description: Target path in project
+        required:
+          - url
+          - path
+        additionalProperties: false
+      description: Array of {url, path} objects
+  required:
+    - imports
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - asset-imported

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

@@ -0,0 +1,69 @@
+id: tool/import-hdri
+kind: tool
+version: 1.0.1
+summary: Search Poly Haven's CC0 HDRI library and import one into res://sky/ as environment lighting, with the exact run-script snippet that wires the sky.
+use_when:
+  - a 3D scene needs real environment lighting and reflections — the cheapest whole-scene visual upgrade
+  - '"give this scene realistic sky lighting" / "add a sunset sky"'
+  - '"the 3D scene looks flat and grey"'
+do_not_use_when:
+  - the project already has a sky/HDRI to reuse
+  - a 2D project — HDRIs are 3D environment lighting
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - lighting
+    - 3d
+  modalities:
+    - assets
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/run-script
+    - tool/import-from-url
+    - tool/screenshot
+  skills:
+    - skill/3d-lighting
+    - skill/skybox-panorama
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_import_hdri
+implementation:
+  module: src/mcp/tools/asset-tools.ts
+  export: registerAssetTools
+surfaces:
+  mcp:
+    tool_name: summer_import_hdri
+    remote: false
+input_schema:
+  type: object
+  properties:
+    query:
+      type: string
+      description: What kind of sky/environment, e.g. 'sunset beach', 'overcast field', 'studio'. Omit when assetId is given.
+    assetId:
+      type: string
+      description: Exact Poly Haven asset id (lowercase slug, e.g. 'kloppenheim_02'). Skips the search.
+    resolution:
+      type: string
+      enum:
+        - 1k
+        - 2k
+        - 4k
+      default: 2k
+      description: HDRI resolution. 2k (default) is right for most games; 4k for hero skies; 1k for quick blockouts.
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - asset-imported

package/library/tools/input-map-bind/resource.yaml

@@ -0,0 +1,52 @@
+id: tool/input-map-bind
+kind: tool
+version: 1.0.2
+summary: Create an input action if needed and bind keyboard or mouse events to it.
+use_when:
+  - setting up player controls like jump, move, or interact
+  - '"make E interact" / "bind shoot to left mouse"'
+  - adding a gamepad button for an existing action
+do_not_use_when:
+  - reading which keys are already bound — summer_get_project_context / project.godot
+facets:
+  lifecycle:
+    - build
+  domains:
+    - project
+    - gameplay
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_input_map_bind
+implementation:
+  module: src/mcp/tools/project-tools.ts
+  export: registerProjectTools
+surfaces:
+  mcp:
+    tool_name: summer_input_map_bind
+    remote: false
+input_schema:
+  type: object
+  properties:
+    name:
+      type: string
+      description: Action name, e.g. 'jump', 'move_forward', 'interact'
+    events:
+      type: array
+      items:
+        type: object
+        additionalProperties: {}
+      description: Array of input event objects
+  required:
+    - name
+    - events
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false

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

@@ -0,0 +1,46 @@
+id: tool/inspect-node
+kind: tool
+version: 1.0.3
+summary: Get every editable property of a node with current values, Variant types (raw int plus type_name), and resource info.
+use_when:
+  - before modifying a node, to understand its current state
+  - "\"what is the player's speed / position / collision layer?\""
+  - '"which material and mesh does this MeshInstance3D use?"'
+do_not_use_when:
+  - sub-properties of the material, mesh, or shape itself — summer_inspect_resource
+  - live values while the game runs — summer_inspect_runtime_node
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_inspect_node
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_inspect_node
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      description: Node path from scene tree, e.g. 'Player', 'World/Enemies/Boss', 'DirectionalLight3D'
+  required:
+    - path
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

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

@@ -0,0 +1,45 @@
+id: tool/inspect-resource
+kind: tool
+version: 1.0.2
+summary: Get all properties of a resource such as a material, mesh, shape, or environment.
+use_when:
+  - reading sub-properties that the node inspector only names
+  - '"what colour is this material?" / "how big is this collision shape?"'
+  - '"what settings does the WorldEnvironment resource have?"'
+do_not_use_when:
+  - top-level node properties — summer_inspect_node
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_inspect_resource
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_inspect_resource
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      description: Resource path, e.g. 'res://materials/ground.tres' or 'res://models/player.glb'
+  required:
+    - path
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/inspect-runtime-node/resource.yaml

@@ -0,0 +1,54 @@
+id: tool/inspect-runtime-node
+kind: tool
+version: 1.0.1
+summary: Live properties of one node in the RUNNING game — actual stats, position, flags — without stopping the game and losing the state.
+use_when:
+  - answering "where IS the player" or "what are this enemy's stats right now" during a playtest
+  - '"how much health does the boss have right now?"'
+  - "\"what is the player's actual velocity mid-jump?\""
+do_not_use_when:
+  - no game is running — summer_play first; for the edited scene use summer_inspect_node
+  - "requires an engine build with GetRuntimeNode (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/get-runtime-tree
+    - tool/inspect-node
+  skills:
+    - skill/verifying-scenes
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_inspect_runtime_node
+implementation:
+  module: src/mcp/tools/perception-tools.ts
+  export: registerPerceptionTools
+surfaces:
+  mcp:
+    tool_name: summer_inspect_runtime_node
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      description: Runtime node path, e.g. '/root/Main/Player'. Get it from summer_get_runtime_tree.
+  required:
+    - path
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

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

@@ -0,0 +1,62 @@
+id: tool/instantiate-scene
+kind: tool
+version: 1.0.3
+summary: Add an existing scene or 3D model file as a child node, composing scenes from prefabs.
+use_when:
+  - placing a .tscn prefab or imported 3D model into a scene
+  - '"put three copies of the enemy prefab in the level"'
+  - '"add the imported car.glb to the scene"'
+do_not_use_when:
+  - a bare built-in node type like Camera3D or Timer — summer_add_node
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_instantiate_scene
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_instantiate_scene
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Target scene to receive the instance, e.g. 'res://main.tscn'
+    parent:
+      type: string
+      description: Parent node path, e.g. './World'
+    scene:
+      type: string
+      description: Scene/model path, e.g. 'res://player.tscn' or 'res://models/tree.glb'
+    name:
+      type: string
+      description: Override the instance name
+    target_size:
+      type: number
+      exclusiveMinimum: 0
+      description: Normalize the instance's physical size - uniformly scale it so its largest world-AABB dimension equals this many units (chair 1.0, car 4.5, person 1.7). Strongly recommended for imported .glb/.gltf models. Older engine builds ignore it; the result then lacks scale_applied and carries a target_size_note.
+  required:
+    - scenePath
+    - parent
+    - scene
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/is-running/resource.yaml

@@ -0,0 +1,40 @@
+id: tool/is-running
+kind: tool
+version: 1.0.2
+summary: Check whether the game is running; returns the active scene path when it is.
+use_when:
+  - deciding whether to boot, restart, or capture the running game
+  - '"is the game already open / still playing?"'
+  - before summer_play or a game-target screenshot, to avoid a double launch
+do_not_use_when:
+  - you need the live scene contents — summer_get_runtime_tree
+facets:
+  lifecycle:
+    - build
+  domains:
+    - debug
+    - runtime
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_is_running
+implementation:
+  module: src/mcp/tools/debug-tools.ts
+  export: registerDebugTools
+surfaces:
+  mcp:
+    tool_name: summer_is_running
+    remote: false
+input_schema:
+  type: object
+  properties: {}
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

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

@@ -0,0 +1,89 @@
+id: tool/library-feedback
+kind: tool
+version: 1.0.2
+summary: Report how library entries worked out (worked, wrong, outdated, ...) so Summer can fix and re-rank them; fire-and-forget, opt-out honored.
+use_when:
+  - a natural checkpoint after using library entries, batching all outcomes in one call
+  - an entry was wrong, outdated, incomplete, or misrouted and Summer should know
+do_not_use_when:
+  - reporting outcome worked without in-engine verification
+  - the note would describe the user's project, files, or code instead of the entry
+facets:
+  lifecycle:
+    - support
+  domains:
+    - feedback
+    - meta
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_library_feedback
+implementation:
+  module: src/core/feedback/client.ts
+  export: sendLibraryFeedback
+surfaces:
+  mcp:
+    tool_name: summer_library_feedback
+    remote: true
+input_schema:
+  type: object
+  properties:
+    reports:
+      type: array
+      items:
+        type: object
+        properties:
+          entry_id:
+            type: string
+            pattern: ^(tool|skill|example|template|collection|reference)\/[a-z0-9-]+(@[a-f0-9]{8,64})?$
+            description: The library entry ID exactly as the loader printed it (kind/slug, optionally @content-hash). Never guess or reconstruct it.
+          outcome:
+            type: string
+            enum:
+              - worked
+              - worked_with_fixes
+              - wrong
+              - outdated
+              - incomplete
+              - did_not_apply
+              - misrouted
+            description: worked = verified in-engine (playtest/screenshot passed). worked_with_fixes = worked after your changes (say what in deviation). wrong = incorrect content. outdated = no longer matches this engine version. incomplete = missing a needed case. did_not_apply = loaded but irrelevant to the task. misrouted = the description/metadata led you here wrongly.
+          note:
+            type: string
+            maxLength: 280
+            description: Optional, max 280 chars. About the ENTRY only — never the user's project, files, or code.
+          deviation:
+            type: string
+            maxLength: 280
+            description: Optional, max 280 chars. What you did instead of / on top of the entry's instructions.
+        required:
+          - entry_id
+          - outcome
+        additionalProperties: false
+      minItems: 1
+      maxItems: 10
+      description: 1-10 outcome reports, batched at a natural checkpoint (one call, not one per entry).
+    engine_version:
+      type: string
+      minLength: 1
+      maxLength: 32
+      description: The Summer Engine version in use, e.g. "4.6.1".
+    agent_model:
+      type: string
+      minLength: 1
+      maxLength: 64
+      description: The model you are, e.g. claude-fable-5, gpt-5.5-codex; use "unknown" if unsure.
+  required:
+    - reports
+    - engine_version
+    - agent_model
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/list-my-assets/resource.yaml

@@ -0,0 +1,56 @@
+id: tool/list-my-assets
+kind: tool
+version: 1.0.2
+summary: List or search the signed-in user's generated and uploaded assets, returning exact asset ids plus file and import URLs.
+use_when:
+  - retrieving an asset the user just generated before importing it
+  - resolving phrases like 'the model I made' to an exact asset id
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - pipeline
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_list_my_assets
+implementation:
+  module: src/mcp/tools/asset-tools.ts
+  export: registerAssetTools
+surfaces:
+  mcp:
+    tool_name: summer_list_my_assets
+    remote: true
+input_schema:
+  type: object
+  properties:
+    query:
+      type: string
+      default: ""
+      description: Optional search term. Empty string lists recent assets.
+    assetType:
+      type: string
+      enum:
+        - 2d_image
+        - animation
+        - 3d_model
+        - audio
+        - music
+        - all
+      default: all
+      description: Filter by asset type
+    limit:
+      type: number
+      default: 10
+      description: Max results (1-20)
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false