summer-engine 2.8.2 → 3.0.0

package/library/tools/screenshot/resource.yaml

@@ -0,0 +1,112 @@
+id: tool/screenshot
+kind: tool
+version: 1.1.2
+summary: Capture a frame from the editor viewport, an offscreen scene render (fixed or bookmarked pose, numbered labels), or the running game, as an actual image.
+use_when:
+  - visually verifying layout, scale, framing, or runtime state
+  - '"show me what the scene looks like right now"'
+  - '"did the model land where I put it?" / "does the UI overlap?"'
+  - '"take a screenshot of the game" / "screenshot the running game" — target "game" grabs the live frame'
+  - before/after frames from the SAME viewpoint (framing "bookmark" / "free"), or an annotated screenshot with numbered labels mapped to node paths (marks)
+do_not_use_when:
+  - verifying lighting, mood, or environment-dependent materials with a preset framing (iso/top/front/...) of the scene target - those replace the WorldEnvironment with a flat preview; use framing "camera" (the scene's own Camera3D + real environment), a fixed pose ("free" / "bookmark", real environment too), or the game target instead
+  - capturing motion or a sequence of frames (use a RunVerification probe's save_frame)
+  - 'treating a uniformly black or grey "viewport" frame as evidence about lights, cameras, or content - the editor had not redrawn its viewport texture yet; the tool recaptures once and says so in the caption, otherwise recapture yourself'
+  - saving or listing the viewpoints themselves — summer_camera_bookmark
+facets:
+  lifecycle:
+    - build
+  domains:
+    - verification
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/camera-bookmark
+    - tool/world-snapshot
+  skills:
+    - skill/verifying-scenes
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_screenshot
+implementation:
+  module: src/mcp/tools/visual-tools.ts
+  export: registerVisualTools
+surfaces:
+  mcp:
+    tool_name: summer_screenshot
+    remote: false
+input_schema:
+  type: object
+  properties:
+    target:
+      type: string
+      enum:
+        - viewport
+        - scene
+        - game
+      default: viewport
+      description: '"viewport" = editor current view (default), "scene" = offscreen render of a scene file, "game" = running game frame'
+    scenePath:
+      type: string
+      description: target:"scene" only. Full scene path, e.g. "res://main.tscn". Omit to render the currently-open scene.
+    framing:
+      type: string
+      enum:
+        - auto
+        - iso
+        - top
+        - front
+        - back
+        - left
+        - right
+        - camera
+        - free
+        - bookmark
+      description: 'target:"scene" only, 3D scenes. Camera direction preset: "iso" = 3/4 diagonal view, "top" = straight down, "front" = camera at +Z, "back" = camera at -Z, "left" = camera at -X, "right" = camera at +X. "auto" (default) is an alias of "iso". "camera" = render through the scene''s OWN Camera3D with its REAL WorldEnvironment - the only edit-time framing that truthfully shows lighting/mood. "bookmark" (+ bookmark_name) = the fixed pose saved with summer_camera_bookmark; "free" (+ camera_position, camera_look_at, fov) = an explicit fixed pose. Both keep the REAL WorldEnvironment and repeat exactly, so before/after frames line up. The result reports the resolved framing - an older engine echoes a preset instead, and the caption warns.'
+    bookmark_name:
+      type: string
+      description: 'framing:"bookmark" only (implies it when framing is omitted). Name of a bookmark saved with summer_camera_bookmark (list them with action:"list"). Fails with failure_reason "unknown_bookmark" (+ the available names) when it does not exist.'
+    size:
+      type: array
+      items:
+        type: integer
+        exclusiveMinimum: 0
+      minItems: 2
+      maxItems: 2
+      description: target:"scene" only. Output image [width, height] in pixels.
+    nodePath:
+      type: string
+      description: target:"scene" only. Node path relative to the scene root (e.g. "Player/Mesh") to frame INSTEAD of the whole scene — the camera fits that node's combined bounds (3D visual AABBs or 2D rects, children included). A bare unique name is also found recursively. Fails with failure_reason "node_not_found" when the path does not resolve (no silent whole-scene fallback). Cannot combine with a fixed pose (framing "camera"/"free"/"bookmark").
+    camera_path:
+      type: string
+      description: framing:"camera" only. Path of the Camera3D to render through (relative to the scene root) when the scene has several cameras or none marked current. Omit to use the scene's current/first Camera3D.
+    camera_position:
+      type: string
+      description: 'framing:"free" only (implies it when framing is omitted). Camera position as a Godot literal, e.g. "Vector3(0, 5, 12)". Goes together with camera_look_at.'
+    camera_look_at:
+      type: string
+      description: 'framing:"free" only. Point the camera looks at, e.g. "Vector3(0, 1, 0)". Must differ from camera_position.'
+    fov:
+      type: number
+      description: framing:"free" / "bookmark" only. Vertical field of view in degrees (1..179; default 60 for "free", the bookmark's own for "bookmark").
+    marks:
+      type: boolean
+      description: target:"scene" only, 3D scenes. Draw a Set-of-Mark overlay - numbered tags + box outlines over the largest visible VisualInstance3D nodes (lights excluded), ranked by projected screen area. The caption lists label -> node path (scene-root-relative) so you can name what you see. Works with every framing. 2D scenes return marks_unsupported. Default false.
+    max_marks:
+      type: integer
+      minimum: 1
+      maximum: 128
+      description: marks:true only. Cap on numbered labels (engine default 32, at most 128). The caption says when the cap truncated the list.
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - frame-captured

package/library/tools/search-assets/resource.yaml

@@ -0,0 +1,67 @@
+id: tool/search-assets
+kind: tool
+version: 1.0.2
+summary: Search the Summer asset library and your own assets by keyword and meaning; returns names, types, preview and import-ready URLs.
+use_when:
+  - finding an existing asset in the public library before generating a new one
+  - locating a user's generated or uploaded asset by description
+do_not_use_when:
+  - you already have the exact asset id (fetch it directly instead)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - pipeline
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_search_assets
+implementation:
+  module: src/mcp/tools/asset-tools.ts
+  export: registerAssetTools
+surfaces:
+  mcp:
+    tool_name: summer_search_assets
+    remote: true
+input_schema:
+  type: object
+  properties:
+    query:
+      type: string
+      description: Natural language search, e.g. 'low-poly tree', 'sci-fi weapon'. For my_assets, can be empty to list recent.
+    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)
+    source:
+      type: string
+      enum:
+        - library
+        - my_assets
+        - all
+      default: library
+      description: "Where to search: library (public 25k+), my_assets (your generated assets), all"
+  required:
+    - query
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

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

@@ -0,0 +1,81 @@
+id: tool/search-library
+kind: tool
+version: 1.0.0
+summary: Search the Summer library by describing the task in plain words — ranked entries of every kind, with the id to load next via summer_read_library.
+use_when:
+  - the first move for any task, before building anything — find the entry that covers what the user asked
+  - not sure which entry (skill, tool, template, reference) applies to the task at hand
+  - narrowing the library to one kind with the kinds filter, or hiding preview entries
+do_not_use_when:
+  - you already hold an exact id — load it with summer_read_library
+  - looking for assets (models, textures, sounds) — summer_search_assets searches the asset library, not the knowledge library
+  - looking up an engine class, property, or method name — summer_api_docs
+facets:
+  lifecycle:
+    - build
+    - launch
+    - grow
+    - support
+  domains:
+    - agent-workflow
+    - meta
+    - mcp
+  modalities:
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/read-library
+    - tool/library-feedback
+  skills:
+    - skill/using-summer
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_search_library
+implementation:
+  module: src/mcp/tools/library-tools.ts
+  export: registerLibraryTools
+surfaces:
+  mcp:
+    tool_name: summer_search_library
+    remote: true
+input_schema:
+  type: object
+  properties:
+    query:
+      type: string
+      minLength: 1
+      maxLength: 300
+      description: The task in plain words — what you are building, fixing, or looking for.
+    kinds:
+      type: array
+      items:
+        type: string
+        enum:
+          - tool
+          - skill
+          - example
+          - template
+          - collection
+          - reference
+      description: Restrict to these kinds. Omit for all kinds.
+    limit:
+      type: integer
+      minimum: 1
+      maximum: 20
+      description: Maximum results, 1-20 (default 8).
+    include_preview:
+      type: boolean
+      description: Include status preview entries — not yet exercised in-engine by the Summer team (default true). false = stable only.
+  required:
+    - query
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

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

@@ -0,0 +1,48 @@
+id: tool/select-node
+kind: tool
+version: 1.0.2
+summary: Select a node in the editor scene tree and show it in the inspector.
+use_when:
+  - focusing the user's editor on a specific node
+  - highlighting the player in the scene tree so the user can see it
+  - showing the user the node whose properties are about to change
+do_not_use_when:
+  - reading properties — summer_inspect_node; selection changes nothing
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_select_node
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_select_node
+    remote: false
+input_schema:
+  type: object
+  properties:
+    nodePath:
+      type: string
+      description: Node path to select
+    scenePath:
+      type: string
+      description: Open this scene first, then select the node
+  required:
+    - nodePath
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false

package/library/tools/set-prop/resource.yaml

@@ -0,0 +1,64 @@
+id: tool/set-prop
+kind: tool
+version: 1.0.2
+summary: Set a node property using Godot string syntax for vectors, colors, transforms, and resource class names.
+use_when:
+  - configuring nodes after adding them
+  - '"move the light up" / "put the player at the spawn point" / "make the sprite red" / "rotate the camera 45 degrees"'
+  - setting one node's position, rotation, scale, colour, speed, collision layer, or visible flag
+do_not_use_when:
+  - a property that lives on a mesh, material, or shape resource — summer_set_resource_property
+  - project-wide settings — summer_project_setting
+  - many nodes or computed values — summer_run_script
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_set_prop
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_set_prop
+    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, e.g. './World/Player'
+    key:
+      type: string
+      description: Property name, e.g. 'position', 'mesh', 'visible'
+    value:
+      type:
+        - string
+        - number
+        - boolean
+      description: Value in Summer Engine variant-string format for complex types, native JSON for primitives
+  required:
+    - scenePath
+    - path
+    - key
+    - value
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/set-resource-property/resource.yaml

@@ -0,0 +1,66 @@
+id: tool/set-resource-property
+kind: tool
+version: 1.0.2
+summary: Set a nested property on a resource attached to a node, like a collision shape size or material color.
+use_when:
+  - modifying sub-properties of meshes, materials, or shapes
+  - '"make the box mesh 2 metres wide" / "change the capsule radius"'
+  - setting the material albedo colour or roughness on a mesh
+do_not_use_when:
+  - the property is on the node itself (position, visible, scale) — summer_set_prop
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_set_resource_property
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_set_resource_property
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Target scene path, e.g. 'res://main.tscn'
+    nodePath:
+      type: string
+      description: Node path, e.g. './Player/CollisionShape3D'
+    resourceProperty:
+      type: string
+      description: Resource property on the node, e.g. 'shape', 'mesh', 'material_override'
+    subProperty:
+      type: string
+      description: Property on the resource, e.g. 'size', 'radius', 'albedo_color'
+    value:
+      type:
+        - string
+        - number
+        - boolean
+      description: Value in Summer Engine variant-string format
+  required:
+    - scenePath
+    - nodePath
+    - resourceProperty
+    - subProperty
+    - value
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/slice-asset-sheet/resource.yaml

@@ -0,0 +1,47 @@
+id: tool/slice-asset-sheet
+kind: tool
+version: 1.0.2
+summary: Detect and crop every distinct game asset from a generated sheet image, uploading named slices with bounding boxes.
+use_when:
+  - splitting a generated asset or UI sheet into individually usable assets
+  - '"cut the generated icon sheet into separate PNGs"'
+  - '"I have one image with 12 props on it, make them individual assets"'
+do_not_use_when:
+  - a regular animation grid — set hframes/vframes on the Sprite2D instead
+facets:
+  lifecycle:
+    - build
+  domains:
+    - generate
+    - 2d
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_slice_asset_sheet
+implementation:
+  module: src/mcp/tools/generate-tools.ts
+  export: registerGenerateTools
+surfaces:
+  mcp:
+    tool_name: summer_slice_asset_sheet
+    remote: true
+input_schema:
+  type: object
+  properties:
+    assetId:
+      type: string
+      description: Summer image asset ID to slice, usually returned by summer_generate_image
+  required:
+    - assetId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - asset-created

package/library/tools/snap-to-surface/resource.yaml

@@ -0,0 +1,90 @@
+id: tool/snap-to-surface
+kind: tool
+version: 1.0.0
+summary: Move one 3D subject along a world ray until it sits at the requested gap from the first surface (floor, ramp, shelf, table), then save the scene.
+use_when:
+  - seating a prop on a floor, ramp, table, or shelf instead of hand-tuning its Y position
+  - grounding an imported or instantiated model that floats or sinks into its support
+do_not_use_when:
+  - you only want to know whether a pose fits — summer_test_placement is read-only
+  - arranging several objects relative to each other — summer_align_distribute_3d
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/test-placement
+    - tool/align-distribute-3d
+    - tool/world-snapshot
+    - tool/set-prop
+  skills:
+    - skill/world-building-3d
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_snap_to_surface
+implementation:
+  module: src/mcp/tools/spatial-tools.ts
+  export: registerSpatialTools
+surfaces:
+  mcp:
+    tool_name: summer_snap_to_surface
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Exact scene containing the subject, e.g. 'res://levels/market.tscn'.
+    subjectPath:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Exact Node3D path relative to the scene root, e.g. './Props/Crate'.
+    direction:
+      type: array
+      items:
+        type: number
+      minItems: 3
+      maxItems: 3
+      default: [0, -1, 0]
+      description: Finite world-space cast direction [x,y,z] whose squared length exceeds 0.00001. Defaults downward.
+    maxDistance:
+      type: number
+      exclusiveMinimum: 0
+      maximum: 10000
+      default: 20
+      description: Maximum cast and overlap-recovery distance in scene units.
+    gap:
+      type: number
+      minimum: 0
+      maximum: 10000
+      default: 0
+      description: Requested separation from the support surface; must not exceed maxDistance.
+    alignUp:
+      type: boolean
+      default: false
+      description: Rotate the subject's current world up toward an exact physics contact normal before seating it.
+  required:
+    - scenePath
+    - subjectPath
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/snapshot-diff/resource.yaml

@@ -0,0 +1,58 @@
+id: tool/snapshot-diff
+kind: tool
+version: 1.0.1
+summary: Diff two world snapshots into added/removed/changed nodes and count deltas — the structural receipt that a mutation did exactly what was intended.
+use_when:
+  - verifying a mutation batch against the snapshot_id taken before it
+  - '"what changed in the scene after that script ran?"'
+  - proving a batch only moved the props it was meant to
+do_not_use_when:
+  - no baseline snapshot exists — take summer_world_snapshot first
+  - "requires an engine build with DiffWorldSnapshot (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - verification
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/world-snapshot
+    - tool/screenshot
+  skills:
+    - skill/verifying-scenes
+    - skill/scene-scripting
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_snapshot_diff
+implementation:
+  module: src/mcp/tools/perception-tools.ts
+  export: registerPerceptionTools
+surfaces:
+  mcp:
+    tool_name: summer_snapshot_diff
+    remote: false
+input_schema:
+  type: object
+  properties:
+    from_id:
+      type: string
+      description: snapshot_id of the BEFORE snapshot (from summer_world_snapshot).
+    to_id:
+      type: string
+      description: snapshot_id of the AFTER snapshot. Omit to snapshot the current state now and diff against that.
+  required:
+    - from_id
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false