summer-engine 2.8.2 → 3.1.0

package/library/tools/starcast/resource.yaml

@@ -0,0 +1,120 @@
+id: tool/starcast
+kind: tool
+version: 1.0.0
+summary: Read-only 3D placement rundown for one node — 26 directional clearance casts, contact-or-overlap evidence, grounding, nearby geometry. Never moves or saves.
+use_when:
+  - learning what surrounds a placed prop before and after a correction — which direction is blocked, by what, and at what distance
+  - diagnosing an overlap or a floating object when summer_test_placement reports fits false or grounded false and you need to know which side to move
+  - checking wall gaps, shelf support, or alcove clearance for a rotated subject (directionSpace local)
+do_not_use_when:
+  - you want the engine to move the prop for you — summer_snap_to_surface or summer_align_distribute_3d
+  - you only need a yes/no on one candidate pose — summer_test_placement is cheaper
+  - the subject is 2D or has neither visual nor collision geometry
+  - "requires an engine build with Starcast3D (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+    - verification
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/test-placement
+    - tool/snap-to-surface
+    - tool/inspect-node
+    - tool/world-snapshot
+    - tool/screenshot
+  skills:
+    - skill/spatial-placement
+    - skill/world-building-3d
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_starcast
+implementation:
+  module: src/mcp/tools/spatial-tools.ts
+  export: registerSpatialTools
+surfaces:
+  mcp:
+    tool_name: summer_starcast
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Exact scene containing the subject, e.g. 'res://levels/level1.tscn'.
+    path:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Exact Node3D path relative to the scene root, e.g. './World/Crate'.
+    detail:
+      type: string
+      enum: [summary, full]
+      default: summary
+      description: "summary: compact placement report (at most 5 KB). full: adds bounded hit geometry, an objects table, and nearby lists (at most 12 KB; the engine downgrades to summary rather than exceed it)."
+    maxDistance:
+      type: number
+      exclusiveMinimum: 0
+      maximum: 10000
+      default: 20
+      description: Maximum outward cast distance in scene units.
+    nearbyRadius:
+      type: number
+      minimum: 0
+      maximum: 10000
+      default: 10
+      description: Maximum gap from the subject bounds for the nearby-object lists (full detail).
+    directionSpace:
+      type: string
+      enum: [world, local]
+      default: world
+      description: Cast along world axes, or along the subject's orthonormalized local axes for rotated subjects.
+    collisionMask:
+      type: integer
+      minimum: 0
+      maximum: 4294967295
+      default: 4294967295
+      description: Godot 3D physics layer mask queried by rays, shape contacts/overlaps, and nearby-collider scans.
+    collideWithAreas:
+      type: boolean
+      default: true
+      description: Include Area3D objects as well as physics bodies.
+    maxHitsPerDirection:
+      type: integer
+      minimum: 1
+      maximum: 8
+      default: 3
+      description: Maximum physics hits and visual AABB hits retained for each direction.
+    maxResults:
+      type: integer
+      minimum: 1
+      maximum: 128
+      default: 64
+      description: Maximum retained contact/overlap and nearby entries per evidence channel.
+    margin:
+      type: number
+      minimum: 0
+      maximum: 1
+      default: 0.001
+      description: Tolerance for exact-geometry physics shape intersection queries; touching and candidates within this margin are reported as contact_or_overlap.
+  required:
+    - scenePath
+    - path
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/start-game-task/resource.yaml

@@ -0,0 +1,91 @@
+id: tool/start-game-task
+kind: tool
+version: 1.0.2
+summary: "Plan the right Summer workflow for a game-building task: skill routes, tool groups, confirmation gates, and verification steps."
+use_when:
+  - starting any substantial AI game-building task, before mutating the project
+  - the user asks for a whole feature (inventory, boss fight, day-night cycle) and the path is not obvious
+  - choosing which skills and confirmation gates apply before touching the project
+do_not_use_when:
+  - a one-step edit (one property, one node) — call the tool directly
+facets:
+  lifecycle:
+    - build
+  domains:
+    - project
+    - agent-workflow
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_start_game_task
+implementation:
+  module: src/core/capabilities/game-task-plan.ts
+  export: buildGameTaskPlan
+surfaces:
+  mcp:
+    tool_name: summer_start_game_task
+    remote: true
+  cli:
+    command: summer plan
+input_schema:
+  type: object
+  properties:
+    goal:
+      type: string
+      description: The user's game-building goal or task.
+    mode:
+      type: string
+      enum:
+        - auto
+        - new-game
+        - feature
+        - asset
+        - debug
+        - playtest
+        - polish
+        - ship
+      default: auto
+      description: Optional task mode override.
+    target:
+      type: string
+      enum:
+        - auto
+        - 2d
+        - 3d
+        - ui
+        - audio
+        - animation
+        - level
+        - npc
+        - multiplayer
+      default: auto
+      description: Optional content/system target override.
+    assetPolicy:
+      type: string
+      enum:
+        - reuse-first
+        - ask-before-paid-generation
+        - no-paid-generation
+        - generate-when-clearly-needed
+      default: ask-before-paid-generation
+      description: How aggressively to use paid asset generation.
+    verification:
+      type: string
+      enum:
+        - none
+        - fast
+        - full
+      default: full
+      description: How much engine verification the agent should plan for.
+  required:
+    - goal
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/stop/resource.yaml

@@ -0,0 +1,51 @@
+id: tool/stop
+kind: tool
+version: 1.1.1
+summary: Stop the running game (or one named offscreen instance). Does not revert scene edits, undo anything, or save — the editor state is left exactly as it is.
+use_when:
+  - runtime verification is finished
+  - the game must restart to pick up scene or script changes
+  - a runaway or frozen playtest needs killing
+  - an offscreen playtest instance (summer_play with instance + mode offscreen) is no longer needed — pass instance
+do_not_use_when:
+  - you want to undo scene edits — stopping reverts nothing; use editor undo / summer_batch Undo
+  - saving — stopping does not save; summer_save_scene
+facets:
+  lifecycle:
+    - build
+  domains:
+    - debug
+    - runtime
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_stop
+implementation:
+  module: src/mcp/tools/debug-tools.ts
+  export: registerDebugTools
+surfaces:
+  mcp:
+    tool_name: summer_stop
+    remote: false
+related:
+  tools:
+    - tool/play
+    - tool/game-control
+input_schema:
+  type: object
+  properties:
+    instance:
+      type: string
+      description: Offscreen instance name to stop (from summer_play instance); omit for the main embedded game.
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - game-stopped

package/library/tools/test-placement/resource.yaml

@@ -0,0 +1,109 @@
+id: tool/test-placement
+kind: tool
+version: 1.0.0
+summary: Ghost-test one 3D node at a candidate global pose without moving it — overlap evidence, grounded state, signed floor gap. Read-only.
+use_when:
+  - deciding whether a prop fits in a shelf, cubby, doorway, platform, or dense set before committing the transform
+  - re-checking a saved pose after snap or align to confirm it still clears its neighbours
+do_not_use_when:
+  - you want the engine to move the prop for you — summer_snap_to_surface
+  - the prop is 2D or has no visual/collider geometry to test
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+    - verification
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/snap-to-surface
+    - tool/align-distribute-3d
+    - tool/world-snapshot
+    - tool/inspect-node
+  skills:
+    - skill/world-building-3d
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_test_placement
+implementation:
+  module: src/mcp/tools/spatial-tools.ts
+  export: registerSpatialTools
+surfaces:
+  mcp:
+    tool_name: summer_test_placement
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Exact scene path containing the subject, e.g. 'res://levels/workshop.tscn'.
+    subjectPath:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Exact node path relative to the scene root, e.g. './World/Crate'.
+    candidateGlobalPosition:
+      type: array
+      items:
+        type: number
+      minItems: 3
+      maxItems: 3
+      description: Candidate global/world position as [x, y, z].
+    candidateGlobalRotationDegrees:
+      type: array
+      items:
+        type: number
+      minItems: 3
+      maxItems: 3
+      description: Candidate global/world Euler rotation in degrees as [x, y, z]; current global scale is preserved.
+    collisionMask:
+      type: integer
+      minimum: 0
+      maximum: 4294967295
+      default: 4294967295
+      description: Godot 3D physics layers included in overlap and floor queries.
+    collideWithAreas:
+      type: boolean
+      default: true
+      description: Include Area3D objects as placement obstacles/support candidates.
+    maxFloorDistance:
+      type: number
+      minimum: 0.001
+      maximum: 1000
+      default: 5
+      description: Maximum world-space distance searched below the candidate footprint; range 0.001..1000.
+    groundTolerance:
+      type: number
+      minimum: 0
+      maximum: 1
+      default: 0.05
+      description: Absolute floor-gap tolerance used to classify grounded support.
+    margin:
+      type: number
+      minimum: 0
+      maximum: 1
+      default: 0.001
+      description: Physics shape-intersection margin; only an exact physics support collider+shape contact is excluded from overlaps.
+  required:
+    - scenePath
+    - subjectPath
+    - candidateGlobalPosition
+    - candidateGlobalRotationDegrees
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/ui-actions/resource.yaml

@@ -0,0 +1,77 @@
+id: tool/ui-actions
+kind: tool
+version: 1.0.0
+summary: List the editor's named actions or invoke one by name exactly as its menu item / shortcut would — open Project Settings, switch screens, toggle panels.
+use_when:
+  - '"open project settings in the editor" / "open the Import dock" / "toggle the animation bottom panel" — an editor-workflow step a human would do with the mouse, driven by its stable action name'
+  - finding the exact action name (mode list, filter) before invoking it, and reading which names are denied
+  - a step has no dedicated tool (summer_open_scene, summer_select_node, summer_save_scene) but the editor has a menu item or shortcut for it
+do_not_use_when:
+  - scene work — adding, moving, retuning, or reading nodes goes through summer_run_script, the scene tools, summer_world_snapshot and summer_screenshot, never through editor clicks
+  - quitting the editor, quitting to the project list, reloading the project, or deleting without confirmation — denied by the engine (denied_action); they end the session
+  - a control has no named action — read summer_ui_tree and activate it by path with summer_ui_activate
+  - "requires an engine build with UiListActions / UiInvoke (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - editor
+    - agent-workflow
+  modalities:
+    - project
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/ui-tree
+    - tool/ui-activate
+    - tool/ui-screenshot
+    - tool/project-setting
+    - tool/open-scene
+    - tool/select-node
+    - tool/get-project-context
+  skills:
+    - skill/driving-the-editor-ui
+    - skill/verification-before-completion
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_ui_actions
+implementation:
+  module: src/mcp/tools/ui-tools.ts
+  export: registerUiTools
+surfaces:
+  mcp:
+    tool_name: summer_ui_actions
+    remote: false
+input_schema:
+  type: object
+  properties:
+    mode:
+      type: string
+      enum:
+        - list
+        - invoke
+      description: "'list' enumerates the editor's named actions (UiListActions, a read). 'invoke' runs ONE named action exactly as its menu item / shortcut would (UiInvoke, mutates editor state)."
+    filter:
+      type: string
+      description: mode 'list' only. Case-insensitive substring over action name and label, e.g. 'project_settings', 'save', 'spatial_editor', 'bottom_panel'.
+    limit:
+      type: integer
+      minimum: 1
+      description: mode 'list' only. Maximum actions returned (engine default 200, max 2000). The result carries total + truncated — never assume a capped list is complete.
+    action_name:
+      type: string
+      description: mode 'invoke' only (required there). The exact action name from a 'list' result — the stable shortcut path such as 'editor/project_settings', 'editor/save_scene', 'spatial_editor/focus_selection'. Palette-only commands are accepted too.
+  required:
+    - mode
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - read-back

package/library/tools/ui-activate/resource.yaml

@@ -0,0 +1,88 @@
+id: tool/ui-activate
+kind: tool
+version: 1.0.0
+summary: Activate one editor control by tree path — press, toggle, focus, select a tab, type text, dial a value — or dismiss a blocking dialog; state is read back.
+use_when:
+  - '"dismiss the dialog that is blocking the editor" / "close that popup" — action dismiss_dialog with the path or title from summer_ui_tree root dialogs'
+  - '"switch the editor to the 3D view" / "go to the Script screen" — path main_screen, action select_tab, value 3D'
+  - pressing a button, selecting a tab, typing into a search field, or dialling a slider that no named action covers, using a path from summer_ui_tree
+do_not_use_when:
+  - a named action exists — summer_ui_actions mode invoke is the first choice; the tree walk is for the long tail
+  - scene work — nodes, properties, and placement go through summer_run_script and the scene tools, never through editor clicks
+  - confirming a quit, reload, or delete-without-confirmation button — denied by the engine (denied_action) because it ends the session or bypasses the human's confirmation
+  - "requires an engine build with UiActivate / UiDismissDialog (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - editor
+    - agent-workflow
+  modalities:
+    - project
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/ui-tree
+    - tool/ui-actions
+    - tool/ui-screenshot
+    - tool/run-script
+  skills:
+    - skill/driving-the-editor-ui
+    - skill/verification-before-completion
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_ui_activate
+implementation:
+  module: src/mcp/tools/ui-tools.ts
+  export: registerUiTools
+surfaces:
+  mcp:
+    tool_name: summer_ui_activate
+    remote: false
+input_schema:
+  type: object
+  properties:
+    action:
+      type: string
+      enum:
+        - press
+        - toggle
+        - focus
+        - select_tab
+        - set_text
+        - set_value
+        - dismiss_dialog
+      description: "Default 'press'. press = synthetic left click on a button / ItemList item / PopupMenu item (index); toggle = flip a toggle-mode button; focus = grab_focus on any control; select_tab = TabContainer/TabBar by value (title) or index — and the synthetic path 'main_screen' switches the 2D/3D/Script/Game/AssetLib editor; set_text = LineEdit/TextEdit text (submit true also emits text_submitted); set_value = Range (SpinBox/Slider) number; dismiss_dialog = close a visible dialog by path or title (UiDismissDialog)."
+    path:
+      type: string
+      description: A control path from summer_ui_tree (required for every action except dismiss_dialog, which may use title instead), or 'main_screen' with action select_tab. Auto-named paths are stable within a session only — re-read the tree rather than persist them.
+    value:
+      type:
+        - string
+        - number
+      description: "select_tab: tab title (or the main-screen editor name '2D', '3D', 'Script', 'Game', 'AssetLib'); set_text: the text; set_value: the number."
+    index:
+      type: integer
+      minimum: 0
+      description: "select_tab: tab index; press on an ItemList / PopupMenu: item index."
+    submit:
+      type: boolean
+      description: set_text on a LineEdit only — also emit text_submitted (the Enter key), e.g. to run a search box.
+    title:
+      type: string
+      description: dismiss_dialog only — a visible window title (case-insensitive; exact wins, one substring match accepted, otherwise ambiguous_dialog) from summer_ui_tree root dialogs.
+    button:
+      type: string
+      description: dismiss_dialog only. 'cancel' (default — the safe close), 'ok', or the exact text of a button in the dialog's row. Buttons whose label quits or reloads the editor are denied by the engine.
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - read-back

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

@@ -0,0 +1,63 @@
+id: tool/ui-screenshot
+kind: tool
+version: 1.0.0
+summary: PNG of the editor window or one dock/dialog/control as an image — the pixels-last fallback for looking at the editor UI, never for picking click coordinates.
+use_when:
+  - '"show me what the editor looks like right now" / "screenshot the Inspector dock" — seeing layout or an unfamiliar panel after summer_ui_tree has described it'
+  - sanity-checking an editor-UI step visually when the structured read-back is not enough
+do_not_use_when:
+  - verifying scene work — summer_screenshot (viewport, scene render with framing camera, or the running game) is the visual-verification tool for scenes
+  - reading a control's state (checked, current_tab, text) — summer_ui_tree is exact and far cheaper
+  - picking coordinates to click — there is no coordinate click; summer_ui_activate takes tree paths
+  - a headless editor — no renderer, no pixels (no_renderer); use summer_ui_tree
+  - "requires an engine build with UiScreenshot (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - editor
+    - agent-workflow
+    - verification
+  modalities:
+    - images
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/ui-tree
+    - tool/ui-actions
+    - tool/ui-activate
+    - tool/screenshot
+  skills:
+    - skill/driving-the-editor-ui
+    - skill/verifying-scenes
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_ui_screenshot
+implementation:
+  module: src/mcp/tools/ui-tools.ts
+  export: registerUiTools
+surfaces:
+  mcp:
+    tool_name: summer_ui_screenshot
+    remote: false
+input_schema:
+  type: object
+  properties:
+    root:
+      type: string
+      description: Same grammar as summer_ui_tree root — 'window' (default; the whole editor window), 'main', 'dock:<title|id>', 'dialog:<title>', 'path:<node path>'. A Control or embedded dialog is cropped out of the root viewport texture; a native OS sub-window is not in it (native_subwindow).
+    max_size:
+      type: integer
+      description: Longest edge in pixels after downscale (engine default 1024, clamped 16-4096). Smaller is cheaper to look at; the result reports scale.
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - screenshot

package/library/tools/ui-tree/resource.yaml

@@ -0,0 +1,69 @@
+id: tool/ui-tree
+kind: tool
+version: 1.0.0
+summary: Structured tree of the live editor UI (controls, paths, text, state) or every visible dialog with its blocking flag — the cheap alternative to a screenshot.
+use_when:
+  - '"is a dialog blocking the editor" / "what does the Inspector dock show" / "which main screen is active" — read editor UI state as structure instead of pixels'
+  - finding a control's path before summer_ui_activate, and reading its state back afterwards
+  - listing visible dialogs and popups (root dialogs) before dismissing one with summer_ui_activate action dismiss_dialog
+do_not_use_when:
+  - reading the scene — summer_get_scene_tree / summer_world_snapshot read the data the Scene dock merely displays
+  - a named action already covers the step — summer_ui_actions mode invoke needs no tree walk
+  - judging appearance (layout, colours, an unfamiliar panel) — summer_ui_screenshot, pixels last
+  - "requires an engine build with UiTree / UiDialogs (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - editor
+    - agent-workflow
+    - verification
+  modalities:
+    - project
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/ui-actions
+    - tool/ui-activate
+    - tool/ui-screenshot
+    - tool/get-scene-tree
+    - tool/world-snapshot
+  skills:
+    - skill/driving-the-editor-ui
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_ui_tree
+implementation:
+  module: src/mcp/tools/ui-tools.ts
+  export: registerUiTools
+surfaces:
+  mcp:
+    tool_name: summer_ui_tree
+    remote: false
+input_schema:
+  type: object
+  properties:
+    root:
+      type: string
+      description: "Where to start. 'main' (default) = the whole editor chrome; 'window' = the SceneTree root incl. every sub-window; 'dock:<title|id>' = one dock (ids file_system | scene_tree | inspector, or any dock title, case-insensitive); 'dialog:<title>' = one visible window; 'path:<node path>' = a path from an earlier result. 'dialogs' = list every visible dialog/popup with its blocking flag and buttons instead of a tree (UiDialogs)."
+    depth:
+      type: integer
+      minimum: 1
+      description: Tree depth (engine default 4, max 32). Plain Nodes between Controls do not consume depth.
+    limit:
+      type: integer
+      minimum: 1
+      description: Maximum Control nodes emitted (engine default 500, max 5000). The result carries truncated + child_count so a cut is visible.
+    visible_only:
+      type: boolean
+      description: Default true. false also emits hidden controls — readable, but summer_ui_activate refuses them with not_visible.
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false