summer-engine 3.7.0 → 4.0.0

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

@@ -0,0 +1,46 @@
+id: tool/app-get
+kind: tool
+version: 1.0.0
+summary: Read a Summer App's manifest, current files (or layout) and shared data summary.
+use_when:
+  - before changing an existing app
+  - '"what does our loot table app do"'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_get
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_get
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-guide/resource.yaml

@@ -0,0 +1,55 @@
+id: tool/app-guide
+kind: tool
+version: 1.0.0
+summary: "Read the Summer Apps build guide: when to build an app, Layout vs code, build loop, manifest, SDK, UI kit, layout format, design rules and worked examples."
+use_when:
+  - before building or changing a Summer App
+  - '"build us a loot balance tool"'
+  - '"make a tool for our team to track creatures"'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_guide
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_guide
+    remote: true
+input_schema:
+  type: object
+  properties:
+    section:
+      type: string
+      enum:
+        - all
+        - overview
+        - manifest
+        - sdk
+        - kit
+        - layout
+        - design
+        - examples
+        - types
+      default: overview
+      description: "Start with overview (the default), then read what the app needs: examples (a working app to copy), sdk, manifest, kit, design, layout, types (exact SDK TypeScript types). all returns every section but types (about 100 KB)"
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-list/resource.yaml

@@ -0,0 +1,48 @@
+id: tool/app-list
+kind: tool
+version: 1.0.0
+summary: List the Summer Apps (team tools inside Summer Studio) in the person's workspaces.
+use_when:
+  - '"which apps do we have"'
+  - finding an app id to change or read
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_list
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_list
+    remote: true
+input_schema:
+  type: object
+  properties:
+    workspaceId:
+      type: string
+      format: uuid
+      description: "Only this workspace (team). Default: every workspace the person is in"
+    q:
+      type: string
+      maxLength: 200
+      description: Search app names and purposes
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-page/resource.yaml

@@ -0,0 +1,74 @@
+id: tool/app-page
+kind: tool
+version: 1.0.0
+summary: Read or use the fields and buttons an open Summer App declared (fill values, press actions).
+use_when:
+  - '"set the budget to 60 in the balance app"'
+  - reading what the person has selected in an open app
+do_not_use_when:
+  - "changing shared data with no app open: apps.write_data"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_page
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_page
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    fill:
+      type: array
+      items:
+        type: object
+        properties:
+          field:
+            type: string
+            minLength: 1
+            maxLength: 200
+          value:
+            anyOf:
+              - type: string
+                maxLength: 10000
+              - type: number
+              - type: boolean
+        required:
+          - field
+          - value
+        additionalProperties: false
+      maxItems: 50
+      description: "Values to set: [{field, value}] with field ids from a read"
+    press:
+      type: string
+      minLength: 1
+      maxLength: 200
+      description: An action id to press after filling
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-publish/resource.yaml

@@ -0,0 +1,90 @@
+id: tool/app-publish
+kind: tool
+version: 1.0.0
+summary: Publish a new version of a Summer App from a local folder, files or a layout; the person's Studio tab boots it.
+use_when:
+  - after writing or changing an app's files
+  - fixing an app after a publish error or an app error event
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_publish
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_publish
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    dir:
+      type: string
+      minLength: 1
+      description: A local folder holding the app (index.html at its root). Every file under it is published; dotfiles and node_modules are skipped
+    files:
+      type: array
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+            minLength: 1
+            maxLength: 200
+          content:
+            type: string
+          encoding:
+            type: string
+            enum:
+              - utf8
+              - base64
+            default: utf8
+        required:
+          - path
+          - content
+        additionalProperties: false
+      maxItems: 300
+      description: "The files instead of dir: [{path, content, encoding}]"
+    layout:
+      type: object
+      additionalProperties: {}
+      description: "Layout apps: { version: 1, title, root }"
+    manifest:
+      type: object
+      additionalProperties: {}
+      description: The manifest {name, purpose, permissions, engineFiles, agentEvents, agentTools} (summer_app_guide section manifest)
+    note:
+      type: string
+      maxLength: 500
+      description: What changed, shown in the version list
+    idempotencyKey:
+      type: string
+      minLength: 8
+      maxLength: 128
+  required:
+    - appId
+    - manifest
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-report-gap/resource.yaml

@@ -0,0 +1,58 @@
+id: tool/app-report-gap
+kind: tool
+version: 1.0.0
+summary: Report an SDK capability a Summer App needed and did not have, so Summer builds it.
+use_when:
+  - an app needed to reach a service or engine feature the SDK does not offer
+  - an app needs something the Summer Apps SDK cannot do
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_report_gap
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_report_gap
+    remote: true
+input_schema:
+  type: object
+  properties:
+    capability:
+      type: string
+      minLength: 1
+      maxLength: 200
+      description: What the app needed, e.g. "read Steam reviews"
+    detail:
+      type: string
+      maxLength: 2000
+    method:
+      type: string
+      maxLength: 100
+      description: The SDK method name you wished existed
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+  required:
+    - capability
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-screenshot/resource.yaml

@@ -0,0 +1,103 @@
+id: tool/app-screenshot
+kind: tool
+version: 1.0.0
+summary: See a Summer App without the person - a headless, read-only render (PNG) with its console, errors, refused calls and declared page.
+use_when:
+  - right after every apps.publish, to check the app renders with real data
+  - '"does my app look right on a phone / in dark mode"'
+  - finding why an app shows nothing (SDK not connected, script errors)
+do_not_use_when:
+  - "testing writes, sends or paid calls: they are refused in screenshots; they work in Studio"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+    - skill/summer-apps-design
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_screenshot
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_screenshot
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    version:
+      type: integer
+      exclusiveMinimum: 0
+      description: "A published version. Default: the current one"
+    width:
+      type: integer
+      minimum: 320
+      maximum: 1920
+      default: 1280
+      description: "Viewport width in px: 390 for a phone"
+    height:
+      type: integer
+      minimum: 320
+      maximum: 1600
+      default: 800
+    theme:
+      type: string
+      enum:
+        - light
+        - dark
+      default: light
+    fullPage:
+      type: boolean
+      default: false
+      description: Capture the whole scroll height (up to 4000 px)
+    params:
+      type: object
+      additionalProperties:
+        type: string
+        maxLength: 500
+      description: Launch params, as in /studio/apps/<id>?key=value
+    steps:
+      type: array
+      maxItems: 5
+      items:
+        type: object
+        properties:
+          click:
+            type: string
+            maxLength: 300
+          press:
+            type: string
+            maxLength: 40
+          wait:
+            type: integer
+            minimum: 0
+            maximum: 3000
+        additionalProperties: false
+      description: "Before the capture, in order: click a CSS selector in the app (\">>>\" reaches inside kit components), press a declared action id, or wait ms. Use it to see a dialog or a second state"
+    out:
+      type: string
+      minLength: 1
+      description: Also save the PNG to this local path
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

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

@@ -0,0 +1,46 @@
+id: tool/app-tools
+kind: tool
+version: 1.0.0
+summary: List the agent tools a Summer App declares.
+use_when:
+  - before calling app logic with apps.call
+  - '"what can our balance app do for me"'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_tools
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_tools
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-update/resource.yaml

@@ -0,0 +1,68 @@
+id: tool/app-update
+kind: tool
+version: 1.0.0
+summary: Rename a Summer App, move it to a folder, or keep, archive or restore it.
+use_when:
+  - archiving a scratch app you made that the person did not keep
+  - '"rename the loot app to Drop tables"'
+  - '"keep this app" (status kept)'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_update
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_update
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    name:
+      type: string
+      minLength: 1
+      maxLength: 80
+    purpose:
+      type: string
+      maxLength: 280
+    status:
+      type: string
+      enum:
+        - scratch
+        - kept
+        - archived
+      description: "kept: the team keeps it. archived: hidden from the app list (restore with scratch or kept)"
+    folder:
+      type:
+        - string
+        - "null"
+      minLength: 1
+      maxLength: 80
+      description: null takes it out of its folder
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/attach-to-surface/GUIDE.md

@@ -0,0 +1,15 @@
+# summer_attach_to_surface
+
+Mount a piece on a surface: turn it so its given LOCAL backAxis faces into the surface (opposite the hit normal) with its upAxis kept toward worldUp, then seat its measured back face (the extreme of its visible bounds along backAxis, not its origin) at standoff from the surface. Pipes, gutters, lamps, AC units, signs, fire escapes. Place the piece near its mount first (summer_instantiate_scene with position); this tool turns it and pushes it onto the surface.
+
+Find the surface with surface (a node: the ray runs from the subject's origin to the nearest point of that node's bounds) or ray {origin, direction} (both: the ray, and hits on other nodes are skipped). The ray is physics first; if physics finds nothing it falls back to visual AABBs and says so (the normal is then an AABB face normal). Get backAxis from summer_inspect_asset (the piece's back plane normal), not from a guess.
+
+placeAt "current" (default): the piece keeps its height and its place along the surface and only moves along the surface normal. placeAt "hit": it also slides so the centre of its back face lands on the ray hit point.
+
+Steps (existing ops): a read-only probe (RunSceneScript) reads the piece's bounds in its own axes and casts the ray; one SetProp turns the piece and puts its back face 5 cm in front of the planned seat; SnapToSurface sweeps it along -normal (at most standoff + 0.3) and seats it at standoff (its own physics/visual_aabb evidence). Before saving, the seat is checked:
+- with surface: the seat must be on that node (or inside it), else it is refused;
+- with a ray only: a seat on another node is refused unless it lies on the hit plane (a coplanar neighbour module, warned);
+- the piece must end within maxMove (default 2) of where it started; a longer planned move is refused before anything changes, and so is (with placeAt "current") a ray hit farther than maxMove along the surface from the piece (hit_far_from_piece: aim at the piece, or pass placeAt "hit").
+A refused or failed seat puts the piece back where it started (restored: true), saves nothing, and names the cause: seated_on, the seat's failure_reason, blockers {overlapping, overlaps, first_contact} and a next_step.
+
+Returns {seated_on, final_gap (collider gap from SnapToSurface), back_face_gap (visible back face to the hit plane), moved_by, surface_hit, orientation, back_face_offset, seat {evidence, supportPath, finalGap, gapErrorBound, initiallyOverlapping, ...}, saved, warnings}. A warning visible_back_X_into_surface means the piece's collider sits behind its visible back: add X to standoff.

package/library/tools/batch/GUIDE.md

@@ -0,0 +1,27 @@
+# summer_batch
+
+Execute multiple operations (a multi-node build) in a single call. Each op is forwarded to the engine VERBATIM: this is also how you reach engine ops without a dedicated tool.
+
+UNDO: when nothing in the list forces a split (see SPLITS), the whole batch is ONE undo step (one Ctrl+Z). Single-only ops split the list into sequential requests, and EACH chunk is its own undo step (the receipt shows the chunks).
+
+Ops use the individual tools' format:
+- {"op": "AddNode", "parent": "/", "type": "MeshInstance3D", "name": "Floor"}
+- {"op": "SetProp", "path": "Floor", "key": "position", "value": "Vector3(0, -1, 0)"}
+- {"op": "SetProp", "path": "Floor", "key": "mesh", "value": "PlaneMesh"}
+- {"op": "SetResourceProperty", "nodePath": "Floor", "resourceProperty": "mesh", "subProperty": "size", "value": "Vector2(20, 20)"}
+
+SPLITS AND SAVE: scenePath selects every mutation target. Send OpenScene (a UI action) separately, never mixed with scene mutations. The tool appends one final SaveScene when the batch mutates a scene; a SaveScene you supply must appear exactly once, as the final op. The engine requires SaveScene, InstantiateScene, ReplaceNode, SimulateInput, the runtime reads (GetRuntimeSceneTree/GetRuntimeNode) and the Run*/Import* ops to travel alone, so the tool splits the list around them; if a later chunk fails, the receipt names the earlier ops that already applied.
+
+RAW RUNTIME OPS (structured failure_reason passes through verbatim):
+- RunVerification: a hidden, disposable game instance runs a GDScript probe and dies, never touching the editor: {"op": "RunVerification", "probe_source": "...", "max_seconds": 20} returns {ok, results, frames, out_dir}. Probe API: report(name, value) / save_frame(name) / press(action) / key(keycode) / finish(); save_frame() without a name is a script error. Mount scenes deferred (add_child.call_deferred) or the capture can be black; summer_get_agent_playbook has the probe rules.
+- SimulateInput: inject an action/key/mouse/axis into the RUNNING game (summer_play first), sent ALONE: {"op": "SimulateInput", "type": "action", "action": "jump", "pressed": true}. failure_reason "not_running" = start the game first; "unsupported" = the game build predates the handler: use RunVerification or ask the user.
+
+REFUSED: a raw ReplaceNode with scene (it saves the old scene reference; use summer_replace_node) and a raw ConnectSignal (no CONNECT_PERSIST, so the file never holds it; use summer_connect_signal).
+
+REPARENTNODE KEEPS ITS SUBTREE AND IS VERIFIED: the engine op re-owns only the moved node and drops its descendants from the saved file, so the tool saves, sends each ReparentNode alone plus an in-place ReparentNode per scene-owned descendant, then reads the saved .tscn back: persisted:true / verified:true only when every moved node and descendant is at its new path, else failure_reason not_persisted. A move onto a parent with a same-named child is refused (name_collision). scenePath must be a .tscn; Undo cannot share the batch.
+
+PLACED INSTANCES: an InstantiateScene op may carry position, rotation_degrees, scale ([x, y, z] or "Vector3(...)") or transform ("Transform3D(...)"), set on the created node; one op per piece. Each InstantiateScene is its own request and the transforms of a run follow together (up to 200 per request), so N pieces plus the save cost about N + 2 requests and undo steps. Later ops (SetProp, SnapToSurface, the save) see the pieces placed; if one fails, the pieces before it still get their transforms.
+
+RECEIPTS: receipt "summary" returns only counts, failures [{index, op, error}] (index into your ops), created node paths and renames, under 5 KB with any cut declared. Use it for any batch over a few ops: a large full receipt overflows the tool-output limit.
+
+scenePersistence.saved means the SaveScene ran, not what the file holds; verified:true is set only where the tool read the file back.

package/library/tools/camera-bookmark/GUIDE.md

@@ -0,0 +1,12 @@
+# summer_camera_bookmark
+
+Save, list, or delete named camera viewpoints for the edited 3D scene. A bookmark is a fixed pose (position, look_at, fov) stored IN THE PROJECT at res://.summer/camera_bookmarks.json, so it survives sessions and machines — the scene file is never touched.
+
+WHY: screenshots taken from a preset framing re-fit the scene bounds every time, so a before/after pair shifts whenever anything moves; a bookmark is the same pose every time, which makes before/after comparison real. Save once, then reuse on every capture: summer_screenshot target:"scene" framing:"bookmark" bookmark_name:"<name>" (add marks:true for numbered labels mapped to node paths).
+
+action:
+  "save"   — name (1-64 of A-Z a-z 0-9 _ -) plus EITHER position + look_at as Godot literals ("Vector3(x, y, z)", optional fov, default 60) OR neither: omit both to capture the CURRENT editor 3D viewport camera (result pose_source: "editor_viewport" vs "explicit"; overwritten says whether a same-named bookmark was replaced).
+  "list"   — every saved bookmark (names sorted, poses, created timestamps, file path).
+  "delete" — remove one by name (result lists the remaining names).
+
+Failures are structured: bad_args (name grammar, half-given pose, fov outside 1..179, position == look_at), no_editor_camera (no pose given and no 3D viewport camera to capture), not_found (+ available names), io_failed (file unreadable/unwritable; a malformed file is reported, never overwritten). Edit-time only — no running game needed. If this engine build predates the bookmark ops, the result is a structured engine_lacks_op failure (nothing is sent) naming the fallback.

package/library/tools/capture-gameplay/GUIDE.md

@@ -0,0 +1,3 @@
+# summer_capture_gameplay
+
+Capture real gameplay frames without a running editor: starts the game in Summer Engine's offscreen verify instance (--summer-offscreen: a real renderer, a window parked offscreen with no focus, never on screen), lets it run waitSeconds, runs steps, and saves PNG frames of what the game draws, HUD included. Use for store screenshots (1920x1080 landscape or 1080x1920 portrait). The main scene is often a title menu: pass the game's own flags in args (after "--", e.g. ["--autostart"]), a gameplay scene, or steps that play like a player: [{press:"Play"}, {wait:3000}, {key:"Space"}, {action:"jump"}, {click:[960,540]}, {drag:{from:[400,800],to:[1400,800]}}, {shot:true}]. With a shot step, only shot steps save frames; without one, frames are saved after the steps. A step that cannot run (no such button, key or action) becomes a warning. With an editor open, summer_screenshot target game also works. Returns each frame's path, width and height; look at them before using them.

package/library/tools/capture-gameplay/resource.yaml

@@ -1,12 +1,12 @@
 id: tool/capture-gameplay
 kind: tool
-version: 1.0.0
+version: 1.0.1
 summary: Capture real gameplay PNGs (HUD included) offscreen without a running editor; game flags and player steps (press, key, click) get past the title screen.
 use_when:
   - '"take gameplay screenshots for my store page"'
   - '"I need screenshots but the editor is not open"'
   - '"capture a 1920x1080 frame of my game"'
-  - collecting real gameplay screenshots for summer_store_set_art desktop.screenshots or mobile.screenshots
+  - collecting real gameplay screenshots for store.set_art desktop.screenshots or mobile.screenshots
   - every capture shows the title screen — pass the game's flags in args or steps like press Play
 do_not_use_when:
   - the editor is open and the game is running — tool/screenshot with target game shows the live game
@@ -23,7 +23,7 @@ compatibility:
   engine: ">=4.6"
 source: official
 license: MIT
-status: preview
+status: stable
 aliases:
   - summer_capture_gameplay
 implementation: