summer-engine 3.1.0 → 3.2.0

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

@@ -0,0 +1,142 @@
+id: tool/attach-to-surface
+kind: tool
+version: 1.0.0
+summary: Mount a piece on a wall, ceiling or floor — turn its measured back into the surface found by a ray, keep it upright, seat it at a standoff. Saves the scene.
+use_when:
+  - mounting a downpipe, gutter, lamp, AC unit, sign or fire escape on a facade
+  - turning a piece so its back faces a wall instead of guessing its rotation
+  - seating a piece against a surface at an exact standoff
+do_not_use_when:
+  - seating a prop on a floor without turning it — summer_snap_to_surface
+  - joining a pipe to another pipe's end — summer_connect_ports
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+    - level-design
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/raycast
+    - tool/snap-to-surface
+    - tool/inspect-asset
+    - tool/starcast
+  skills:
+    - skill/spatial-placement
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_attach_to_surface
+implementation:
+  module: src/mcp/tools/placement-tools.ts
+  export: registerPlacementTools
+surfaces:
+  mcp:
+    tool_name: summer_attach_to_surface
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Exact scene, e.g. 'res://levels/street.tscn'. It must be open; physics rays need it to be the active tab.
+    subject:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Piece to mount (exact path from the scene root).
+    surface:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Surface node. Without ray, the ray runs from the subject's origin to the nearest point of this node's bounds; with ray, hits on other nodes are skipped. The seat must land on this node (or inside it); a seat on any other node is refused and the piece is put back.
+    ray:
+      type: object
+      properties:
+        origin:
+          type: array
+          minItems: 3
+          maxItems: 3
+          items:
+            type: number
+          description: Ray start [x, y, z] in scene space.
+        direction:
+          type: array
+          minItems: 3
+          maxItems: 3
+          items:
+            type: number
+          description: Ray direction [x, y, z].
+      required:
+        - origin
+        - direction
+      additionalProperties: false
+      description: Explicit ray that finds the surface plane and its normal. Pass this or surface (or both). With a ray only, a seat on another node is refused unless that node lies on the hit plane (a coplanar neighbour module, warned).
+    backAxis:
+      type: string
+      enum: ["+x", "-x", "+y", "-y", "+z", "-z"]
+      default: "-z"
+      description: The subject's LOCAL axis that faces into the surface. Measure it with summer_inspect_asset.
+    upAxis:
+      type: string
+      enum: ["+x", "-x", "+y", "-y", "+z", "-z"]
+      default: "+y"
+      description: The subject's LOCAL axis kept toward worldUp; not on the same line as backAxis.
+    worldUp:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items:
+        type: number
+      default: [0, 1, 0]
+      description: World direction the upAxis follows (projected onto the surface).
+    standoff:
+      type: number
+      minimum: 0
+      maximum: 10
+      default: 0
+      description: Gap between the subject's measured back face (the extreme of its visible bounds along backAxis) and the surface.
+    placeAt:
+      type: string
+      enum: [current, hit]
+      default: current
+      description: "current: the piece keeps its height and its place along the surface and only moves along the surface normal. hit: it also slides so the centre of its back face lands on the ray hit point (its height then follows the ray)."
+    maxMove:
+      type: number
+      exclusiveMinimum: 0
+      maximum: 100
+      default: 2
+      description: Refuse, changing nothing, when the piece would end farther than this from where it starts. Place the piece near its mount first; raise this only for a deliberate long move.
+    maxDistance:
+      type: number
+      exclusiveMinimum: 0
+      maximum: 1000
+      default: 20
+      description: Maximum ray length when looking for the surface.
+    collisionMask:
+      type: integer
+      minimum: 0
+      maximum: 4294967295
+      default: 4294967295
+      description: Godot 3D physics layer mask for the ray.
+  required:
+    - scenePath
+    - subject
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/batch/resource.yaml

@@ -1,12 +1,14 @@
 id: tool/batch
 kind: tool
-version: 1.0.3
-summary: Run multiple engine ops in one call, forwarded verbatim; one undo step unless single-only ops force a split (then one per chunk). Also reaches raw ops.
+version: 1.1.0
+summary: Run engine ops in one call, verbatim; one undo step unless single-only ops split it. ReparentNode keeps and verifies its subtree; raw ConnectSignal is refused.
 use_when:
   - multi-node builds that should undo as one step (no single-only ops in the list)
   - reaching engine ops that have no dedicated tool
+  - placing many kit pieces, one InstantiateScene op per piece with its position and rotation, read back with receipt summary
 do_not_use_when:
   - you need the whole list to be exactly one undo step but it contains a single-only op (the engine splits it; expect one undo step per chunk)
+  - connecting a signal — a raw ConnectSignal is refused; use summer_connect_signal
 facets:
   lifecycle:
     - build
@@ -38,7 +40,11 @@ input_schema:
       items:
         type: object
         additionalProperties: {}
-      description: Array of operation objects, each with 'op' plus its parameters
+      description: Array of operation objects, each with 'op' plus its parameters. InstantiateScene ops may also carry position, rotation_degrees, scale or transform; the tool sets them on the created node. Each InstantiateScene is its own engine request; the transforms of a run of them travel together before the next other op, so N placed pieces plus the save cost about N + 2 requests.
+    receipt:
+      type: string
+      enum: [full, summary]
+      description: "full (default): every engine receipt. summary: counts, failures with their op index, created node paths only (under 5 KB)."
   required:
     - ops
   additionalProperties: false

package/library/tools/connect-ports/resource.yaml

@@ -0,0 +1,120 @@
+id: tool/connect-ports
+kind: tool
+version: 1.0.0
+summary: Join one piece's port (a Marker3D, or an open pipe end id such as '+Y') to another's, facing it; refuses joins that tilt the piece. Saves the scene.
+use_when:
+  - joining a pipe, duct or gutter section end to end with the previous one
+  - fitting a bend, funnel or outlet onto a run
+  - snapping any two pieces together by named Marker3D anchors
+do_not_use_when:
+  - mounting a piece on a wall — summer_attach_to_surface
+  - putting bounds faces together without ports — summer_place_adjacent
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/inspect-asset
+    - tool/attach-to-surface
+    - tool/measure
+  skills:
+    - skill/spatial-placement
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_connect_ports
+implementation:
+  module: src/mcp/tools/placement-tools.ts
+  export: registerPlacementTools
+surfaces:
+  mcp:
+    tool_name: summer_connect_ports
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Exact scene, e.g. 'res://levels/street.tscn'. It must be open in the editor (any tab).
+    subject:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Piece to move.
+    subjectPort:
+      oneOf:
+        - type: string
+          minLength: 1
+          maxLength: 128
+        - type: integer
+          minimum: 0
+          maximum: 255
+      description: "An open-loop id from summer_inspect_asset, e.g. '+Y' (the outermost open loop facing +Y in the piece's own axes) or '+Y#2' (the next one facing +Y); or a Marker3D (or Node3D) name under the subject, whose -Z axis points out of the port; or an open-loop index. Ids and indices follow the stable order (facing, then position), never the radius."
+    target:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Piece that stays put.
+    targetPort:
+      oneOf:
+        - type: string
+          minLength: 1
+          maxLength: 128
+        - type: integer
+          minimum: 0
+          maximum: 255
+      description: Port on the target (open-loop id such as '-Y', marker name, or open-loop index).
+    gap:
+      type: number
+      minimum: -1
+      maximum: 10
+      default: 0
+      description: Distance between the ports along the target port's direction.
+    rollDegrees:
+      type: number
+      minimum: -360
+      maximum: 360
+      default: 0
+      description: "Extra turn of the subject, in degrees, about the joined port axis, applied after the ports are lined up. Axis: the target port's direction reversed, pointing from the joint into the target (receipt roll_axis). Sign: right-hand rule about that axis; positive turns counter-clockwise when you look back along the axis from inside the target toward the subject. Zero: the shortest turn that makes the subject's port face the target's from the subject's CURRENT orientation, so the same value gives different results from different start poses. Read other_ports in the receipt; once the ports are joined, a second call turns by exactly rollDegrees about the joint (180 flips a bend's free end to the other side)."
+    maxTiltDegrees:
+      type: number
+      minimum: 0
+      maximum: 180
+      default: 5
+      description: Refuse the join, changing nothing, when it would tilt the subject's up axis (its local +Y) more than this many degrees from where it points now. Turning about the up axis is never tilt. The refusal names the predicted tilt and the subject ports that would join within the limit.
+    allowTilt:
+      type: boolean
+      default: false
+      description: true joins even when the subject tilts more than maxTiltDegrees (a bend laid on its side, a sloped run). The receipt still reports tilt_degrees.
+    maxTriangles:
+      type: integer
+      minimum: 100
+      maximum: 300000
+      default: 60000
+      description: Triangle budget (100-300000) per node when ports are open-loop ids or indices.
+  required:
+    - scenePath
+    - subject
+    - subjectPort
+    - target
+    - targetPort
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/connect-signal/resource.yaml

@@ -1,13 +1,14 @@
 id: tool/connect-signal
 kind: tool
-version: 1.0.2
-summary: Connect a signal between two nodes; the receiver's script must define the target method.
+version: 1.1.0
+summary: Connect a signal between two nodes so the saved scene keeps it (CONNECT_PERSIST, verified from the saved .tscn); the receiver should define the target method.
 use_when:
   - wiring events like body_entered, pressed, or timeout
   - '"when the button is pressed, call my function"'
   - running code when the player enters an Area3D or a Timer finishes
 do_not_use_when:
   - the receiver script does not define the target method yet — write it first with summer_write_file / summer_replace_text
+  - the scene is a binary .scn — connect from summer_run_script with CONNECT_PERSIST, then summer_save_scene
 facets:
   lifecycle:
     - build

package/library/tools/debug-views/resource.yaml

@@ -0,0 +1,94 @@
+id: tool/debug-views
+kind: tool
+version: 1.0.0
+summary: 'One pose as a grid of beauty, lighting-only, unshaded/albedo, world normals, overdraw and wireframe views.'
+use_when:
+  - 'understanding WHY a shot reads badly: light direction and pools, texture/value balance, normal seams, overdraw hot spots, triangle density'
+  - 'checking floating or duplicated geometry, flipped normals or missing light in one framed view'
+  - 'judging an environment like an artist, on the weakest shot of a sheet'
+do_not_use_when:
+  - 'you only need the final image — summer_shot_sheet or summer_frame_nodes'
+  - 'a pixel-exact close-up of a problem — summer_zoom with the same pose'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - verification
+    - scenes
+    - 3d
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/shot-sheet
+    - tool/zoom
+    - tool/frame-shot
+    - tool/camera-bookmark
+  skills:
+    - skill/verifying-scenes
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_debug_views
+implementation:
+  module: src/mcp/tools/seeing-tools.ts
+  export: registerSeeingTools
+surfaces:
+  mcp:
+    tool_name: summer_debug_views
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Scene to look at, e.g. "res://levels/town.tscn" (the SAVED file). Omit for the scene open in the editor.
+    bookmark_name:
+      type: string
+      description: Pose from a camera bookmark (summer_camera_bookmark). Use INSTEAD of camera_position/camera_look_at.
+    camera_position:
+      type: string
+      description: 'Explicit pose: camera position, "Vector3(x, y, z)". Goes with camera_look_at.'
+    camera_look_at:
+      type: string
+      description: 'Explicit pose: point the camera looks at, "Vector3(x, y, z)".'
+    fov:
+      type: number
+      description: "Vertical field of view in degrees (1..179). Default: the bookmark's own, or 60."
+    views:
+      type: array
+      items:
+        type: string
+        enum:
+          - beauty
+          - lighting
+          - unshaded
+          - normals
+          - overdraw
+          - wireframe
+      maxItems: 8
+      description: "Which views, in grid order (default all six: beauty, lighting, unshaded, normals, overdraw, wireframe)."
+    update_previous:
+      type: boolean
+      description: 'bookmark_name only: replace the bookmark''s previous image (compare baseline) with this beauty tile. Default false: only a missing slot is created.'
+    max_size:
+      type: integer
+      minimum: 64
+      maximum: 4096
+      description: Longest edge of the returned JPEG in pixels (default 1536). Bigger costs more context; up to 4096 for detail work on a PC.
+    aspect:
+      type: number
+      description: Frame width/height (default 1.7778 = 16:9). Every tile uses it.
+    save_to:
+      type: string
+      description: Also write the returned image to res://.summer/shots/saved/<name>.jpg (1-64 of A-Z a-z 0-9 _ -; needs max_size <= 1024). Nothing is written without it, except one previous-image slot per rendered bookmark.
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/frame-nodes/resource.yaml

@@ -0,0 +1,104 @@
+id: tool/frame-nodes
+kind: tool
+version: 1.0.0
+summary: 'Frame nodes by their world bounds and render with the scene''s REAL environment and lights (optionally save the pose as a bookmark).'
+use_when:
+  - '"show me the houses/props with the real lighting" — fit a camera to one or more nodes and render it with the scene''s WorldEnvironment'
+  - 'framing a node from a chosen side (front/back/left/right/top/iso or an explicit direction) for a lighting or mood check; an explicit direction is checked for walls and back faces between the camera and the nodes'
+  - 'creating a hero-view bookmark that fits a group of nodes, so later shot sheets and compares line up'
+do_not_use_when:
+  - 'the editor viewport or a game frame is what you need — summer_screenshot'
+  - 'you do not know a good view — summer_frame_shot finds and scores poses for a shot type'
+  - 'requires an engine build with ScenePreview fixed-pose framings (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op or framing_unsupported'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - verification
+    - scenes
+    - 3d
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/screenshot
+    - tool/camera-bookmark
+    - tool/shot-sheet
+    - tool/frame-shot
+    - tool/zoom
+  skills:
+    - skill/verifying-scenes
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_frame_nodes
+implementation:
+  module: src/mcp/tools/seeing-tools.ts
+  export: registerSeeingTools
+surfaces:
+  mcp:
+    tool_name: summer_frame_nodes
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Scene to look at, e.g. "res://levels/town.tscn" (the SAVED file). Omit for the scene open in the editor.
+    nodes:
+      type: array
+      items:
+        type: string
+      minItems: 1
+      maxItems: 16
+      description: Node paths relative to the scene root ("House1", "Props/Crate_02"). The camera fits their combined WORLD bounds (visible meshes, children included).
+    direction:
+      type: string
+      enum:
+        - front
+        - back
+        - left
+        - right
+        - top
+        - iso
+      description: 'Side the camera sits on: "front" (+Z), "back" (-Z), "left" (-X), "right" (+X), "top", "iso" (default, 3/4 from -X,+Y,-Z like summer_screenshot). Use from for anything else.'
+    from:
+      type: string
+      description: 'Explicit direction FROM the nodes TOWARD the camera, "Vector3(1, 0.4, 2)". Replaces direction. The fitted pose is checked in-engine: when walls block it, or it puts the camera behind or inside a one-sided surface (whose back is not drawn, so the image would look THROUGH it), the caption opens with a WARNING and offers the nearest valid from (+ fov); the requested view is still rendered.'
+    fill:
+      type: number
+      description: Share of the frame the nodes span along their limiting dimension (0.1..1.5, default 0.8).
+    fov:
+      type: number
+      description: Vertical field of view in degrees (default 50).
+    max_size:
+      type: integer
+      minimum: 64
+      maximum: 4096
+      description: Longest edge of the returned JPEG in pixels (default 1024). Bigger costs more context; up to 4096 for detail work on a PC.
+    aspect:
+      type: number
+      description: Frame width/height (default 1.7778 = 16:9). Every tile uses it.
+    marks:
+      type: boolean
+      description: 'Numbered Set-of-Mark labels over the largest visible nodes; the caption maps label -> node path (feed a label to summer_zoom mark). Each labelled node gets an occlusion test (centre + 4 bounds points); a node hidden behind other geometry is noted "(hidden behind <path>)" — ignore its label.'
+    max_marks:
+      type: integer
+      minimum: 1
+      maximum: 128
+      description: "marks only: cap on labels (engine default 32)."
+    bookmark_name:
+      type: string
+      description: Also save the fitted pose as this camera bookmark (1-64 of A-Z a-z 0-9 _ -), so later renders line up with it.
+  required:
+    - nodes
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/frame-shot/resource.yaml

@@ -0,0 +1,134 @@
+id: tool/frame-shot
+kind: tool
+version: 1.0.0
+summary: 'Smart framing: find, score and bookmark camera poses for a shot type (establishing, eye level, low-angle, detail, corridor) with in-engine visibility tests.'
+use_when:
+  - '"find a good view of X" / "frame an establishing shot" / "show it from the player''s eye" / "look down the street"'
+  - 'choosing hero views to bookmark for an environment review loop'
+  - 'checking whether walls or terrain block the view of a subject, and which props frame it (a camera behind or inside a one-sided wall is rejected; transparent foliage and glass are see-through cover)'
+  - 'three different establishing views at once (one per side while the score allows), scored on the key light''s direction and the world edge below the horizon'
+do_not_use_when:
+  - 'you already have the pose — summer_shot_sheet, summer_frame_nodes or summer_screenshot'
+  - 'gameplay camera collision in the running game — that is the camera rig''s job (camera-collision-avoidance knowledge)'
+  - 'a 2D scene'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - verification
+    - scenes
+    - 3d
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/shot-sheet
+    - tool/camera-bookmark
+    - tool/frame-nodes
+    - tool/debug-views
+    - tool/zoom
+  skills:
+    - skill/verifying-scenes
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_frame_shot
+implementation:
+  module: src/mcp/tools/seeing-tools.ts
+  export: registerSeeingTools
+surfaces:
+  mcp:
+    tool_name: summer_frame_shot
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Scene to look at, e.g. "res://levels/town.tscn" (the SAVED file). Omit for the scene open in the editor.
+    shot:
+      type: string
+      enum:
+        - establishing
+        - eye_level
+        - low_angle
+        - detail
+        - corridor
+      description: '"establishing" (wide, whole subject, 12-40 deg up; a pose showing more than 15% empty ground or world edge ranks below every pose showing less), "eye_level" (player eye at spawn: its Camera3D kept inside 1.5-1.8 m, or eye_height, above the walkable surface under the camera), "low_angle" (hero, camera near the ground looking up), "detail" (close-up), "corridor" (down a lane/corridor inside the subject, found by a free-space scan, at eye height; prefers looking in from its open end). Eye-level and corridor cameras are never raised: a pose that cannot stand at eye height moves horizontally or is rejected. Every top pose states its camera height above the surface below it and its absolute y.'
+    subject:
+      type: array
+      items:
+        type: string
+      maxItems: 8
+      description: Node paths to frame (required except for eye_level, where it is what the player looks at).
+    spawn:
+      type: string
+      description: "eye_level only: node the player stands at, e.g. the player or a spawn marker. Its own geometry never counts as an occluder."
+    eye_height:
+      type: number
+      description: "eye_level/corridor: exact camera height in metres above the walkable surface under the camera (default: 1.6; an eye_level spawn's own Camera3D keeps its height clamped into 1.5-1.8)."
+    fov:
+      type: number
+      description: Override the shot type's field of view (establishing 55, eye_level 60/75, low_angle 60 then widened, detail 40, corridor 60/75).
+    aspect:
+      type: number
+      description: Frame width/height (default 1.7778 = 16:9). Every tile uses it.
+    occluders:
+      type: object
+      properties:
+        hard:
+          type: array
+          items:
+            type: string
+          description: "Path prefixes that must never block the view (walls, terrain): a pose they block is rejected."
+        soft:
+          type: array
+          items:
+            type: string
+          description: Path prefixes that may sit in front as framing (foliage, fences, props).
+        ignore:
+          type: array
+          items:
+            type: string
+          description: Path prefixes left out of the visibility pass entirely.
+        hard_layers:
+          type: integer
+          description: "Physics layer mask: geometry whose nearest CollisionObject3D is on these layers is hard."
+        soft_layers:
+          type: integer
+          description: Physics layer mask for soft geometry.
+      additionalProperties: false
+      description: "Override the occluder classification. Default: path names (wall/house/terrain... = hard; tree/fence/lamp/prop/pipe... = soft), MultiMesh = soft, else size (<= 2.5 m = soft). The caption reports the counts by rule."
+    max_soft_fraction:
+      type: number
+      description: Most of the subject that soft geometry may cover before a pose is rejected (0..1, default 0.67).
+    bookmark_name:
+      type: string
+      description: Name for the saved best pose (default <shot>_<subject leaf>).
+    save_bookmark:
+      type: boolean
+      description: Save the best pose as a camera bookmark (default true).
+    render:
+      type: string
+      enum:
+        - sheet
+        - best
+        - none
+      description: '"sheet" (default): the top 3 in one labelled grid with real lighting; "best": the winner only; "none": scores only.'
+    max_size:
+      type: integer
+      minimum: 64
+      maximum: 4096
+      description: Longest edge of the returned JPEG in pixels (default 1536). Bigger costs more context; up to 4096 for detail work on a PC.
+  required:
+    - shot
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false