summer-engine 2.8.2 → 3.1.0

package/library/tools/clear-console/resource.yaml

@@ -0,0 +1,40 @@
+id: tool/clear-console
+kind: tool
+version: 1.0.2
+summary: Clear the editor's Output panel for a clean slate before running the game.
+use_when:
+  - before a play session whose console output you want isolated
+  - '"the Output panel is full of old noise, wipe it"'
+  - resetting before reproducing a bug so only the new messages show
+do_not_use_when:
+  - you still need to read the messages — summer_get_console first; clearing destroys them
+facets:
+  lifecycle:
+    - build
+  domains:
+    - debug
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_clear_console
+implementation:
+  module: src/mcp/tools/debug-tools.ts
+  export: registerDebugTools
+surfaces:
+  mcp:
+    tool_name: summer_clear_console
+    remote: false
+input_schema:
+  type: object
+  properties: {}
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false

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

@@ -0,0 +1,63 @@
+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.
+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
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_connect_signal
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_connect_signal
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Target scene path, e.g. 'res://main.tscn'
+    emitter:
+      type: string
+      description: Node that fires the signal, e.g. './Player/HitArea'
+    signal:
+      type: string
+      description: Signal name, e.g. 'body_entered'
+    receiver:
+      type: string
+      description: Node with the handler script, e.g. './Player'
+    method:
+      type: string
+      description: Method name in the receiver's script, e.g. '_on_hit_area_body_entered'
+  required:
+    - scenePath
+    - emitter
+    - signal
+    - receiver
+    - method
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/create-debug-report/resource.yaml

@@ -0,0 +1,67 @@
+id: tool/create-debug-report
+kind: tool
+version: 1.0.2
+summary: "Create a support-ready Markdown debug report: doctor checks, engine health, diagnostics, console, and debugger output."
+use_when:
+  - the user wants to send Summer a bug report
+  - handing a failing session to another agent as a portable artifact
+do_not_use_when:
+  - running against a hosted/remote MCP endpoint — it probes the local disk (~/.summer, MCP log, project files) and must run where the CLI is installed
+facets:
+  lifecycle:
+    - build
+  domains:
+    - debug
+    - feedback
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_create_debug_report
+implementation:
+  module: src/core/capabilities/debug-report.ts
+  export: createDebugReportArtifact
+surfaces:
+  mcp:
+    tool_name: summer_create_debug_report
+    remote: false
+  cli:
+    command: summer debug
+input_schema:
+  type: object
+  properties:
+    issue:
+      type: string
+      description: User-visible issue or repro summary.
+    output_path:
+      type: string
+      description: Where to write the Markdown report. Defaults to the open project root, or the current working directory if no project is open.
+    include_play_session:
+      type: boolean
+      default: false
+      description: Launch the game briefly and collect post-play diagnostics.
+    play_wait_ms:
+      type: number
+      default: 2500
+      description: Milliseconds to wait after launching the game when include_play_session is true.
+    max_console_lines:
+      type: number
+      default: 200
+      description: Console lines to include after filtering/deduping.
+    max_debugger_entries:
+      type: number
+      default: 100
+      description: Debugger error/warning entries to include after filtering/deduping.
+    include_doctor:
+      type: boolean
+      default: true
+      description: Include summer doctor checks in the report.
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: true
+  credentials: false
+  publish: false

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

@@ -0,0 +1,59 @@
+id: tool/create-scene
+kind: tool
+version: 1.0.2
+summary: Create a new minimal .tscn on disk with a create-only guard and read-back verification; never touches the open scene.
+use_when:
+  - starting a new level, prefab, or UI scene file
+  - '"make a new empty scene file for the enemy prefab"'
+  - starting Level2.tscn from scratch as its own file
+do_not_use_when:
+  - adding nodes into the currently open scene — summer_add_node
+  - the file already exists — the create-only guard refuses; summer_open_scene it instead
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - project
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_create_scene
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_create_scene
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      description: New scene path, e.g. 'res://scenes/empty_level.tscn'
+    rootName:
+      type: string
+      default: Main
+      description: Root node name for the new scene
+    rootType:
+      type: string
+      default: Node3D
+      description: "Root node type. Default 'Node3D' (3D scenes); common alternatives: 'Node2D' (2D scenes), 'Control' (UI scenes), 'Node' (logic-only)."
+    allow_temporary_scene_mutation:
+      type: boolean
+      description: DEPRECATED, ignored. Scene creation no longer mutates any open scene; kept only so older callers don't break.
+  required:
+    - path
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/creator-config/resource.yaml

@@ -0,0 +1,63 @@
+id: tool/creator-config
+kind: tool
+version: 1.0.2
+summary: Read or update the shared non-secret Summer configuration; mutations require confirm, and tokens are never returned or accepted.
+use_when:
+  - inspecting or changing shared CLI and MCP configuration values
+  - '"which creator project id / channel is this CLI pointed at?"'
+  - switching the default publish channel
+do_not_use_when:
+  - reading or setting auth tokens — they never pass through this tool; use summer login / logout
+facets:
+  lifecycle:
+    - launch
+  domains:
+    - creator
+    - deployment
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_creator_config
+implementation:
+  module: src/mcp/tools/creator-tools.ts
+  export: registerCreatorTools
+surfaces:
+  mcp:
+    tool_name: summer_creator_config
+    remote: false
+  cli:
+    command: summer config
+input_schema:
+  type: object
+  properties:
+    action:
+      type: string
+      enum:
+        - list
+        - get
+        - set
+        - unset
+    key:
+      type: string
+      enum:
+        - gateway.url
+        - creator.apiUrl
+        - creator.projectId
+        - creator.channel
+    value:
+      type: string
+    confirm:
+      type: boolean
+      default: false
+  required:
+    - action
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

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

@@ -0,0 +1,73 @@
+id: tool/creator-publish
+kind: tool
+version: 1.0.2
+summary: Publish an exported Summer .pck through the versioned Summercraft creator API, with an explicit confirm step before upload.
+use_when:
+  - releasing a user-approved build to a Summercraft channel
+  - '"ship this exported build to the live channel"'
+  - '"release version 1.2.0 of my game"'
+do_not_use_when:
+  - the user has not approved the exact version, digest, and channel
+  - the game is not exported yet — export the .pck first (skill/export-and-ship)
+facets:
+  lifecycle:
+    - launch
+  domains:
+    - creator
+    - deployment
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_creator_publish
+implementation:
+  module: src/core/capabilities/creator.ts
+  export: publishCreator
+surfaces:
+  mcp:
+    tool_name: summer_creator_publish
+    remote: false
+  cli:
+    command: summer publish
+input_schema:
+  type: object
+  properties:
+    project:
+      type: string
+      description: Project root. Defaults to the current working directory.
+    artifact:
+      type: string
+      description: Exact path to the exported Summer .pck artifact.
+    version:
+      type: string
+      description: Immutable release version.
+    manifest:
+      type: string
+      description: Optional path to a JSON release manifest.
+    projectId:
+      type: string
+      description: Creator project ID. Defaults to ~/.summer/config.json.
+    channel:
+      type: string
+      description: Release channel. Defaults to the configured channel or production.
+    notes:
+      type: string
+      description: Release notes shown during confirmation and recorded in the local audit.
+    confirm:
+      type: boolean
+      default: false
+      description: Set true only after the user approves the exact release target.
+  required:
+    - artifact
+    - version
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: true
+evidence_checks:
+  - release-recorded

package/library/tools/creator-releases/resource.yaml

@@ -0,0 +1,53 @@
+id: tool/creator-releases
+kind: tool
+version: 1.0.2
+summary: List creator-owned releases from the Summercraft creator API with server-verified scope and ownership.
+use_when:
+  - reviewing which versions of a project are live per channel
+  - '"what version is live right now?"'
+  - '"did the publish go through?" — confirming a release landed'
+do_not_use_when:
+  - publishing a new release — summer_creator_publish
+facets:
+  lifecycle:
+    - launch
+  domains:
+    - creator
+    - deployment
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_creator_releases
+implementation:
+  module: src/core/capabilities/creator.ts
+  export: listCreatorReleases
+surfaces:
+  mcp:
+    tool_name: summer_creator_releases
+    remote: true
+  cli:
+    command: summer releases
+input_schema:
+  type: object
+  properties:
+    projectId:
+      type: string
+      description: Creator project ID. Defaults to ~/.summer/config.json.
+    limit:
+      type: integer
+      minimum: 1
+      maximum: 100
+      default: 20
+    cursor:
+      type: string
+      description: Opaque nextCursor from the previous page.
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/fabricate-3d/resource.yaml

@@ -0,0 +1,108 @@
+id: tool/fabricate-3d
+kind: tool
+version: 1.0.0
+summary: Fabricate a mesh with a bpy script in the user's own Blender (headless, engine-supervised), import the .glb into res://, optionally instantiate it.
+use_when:
+  - a modular kit with exact dimensions and snapping — walls, pipes, fences, rails — where generation cannot hold size and style across many pieces
+  - VFX meshes — shatter pieces, curve sweeps, trails, LOD chains — that are one-liners in bpy and absent from the engine
+  - post-processing a generated model (decimate, UV unwrap, bake) before it goes into the scene
+  - '"write a Blender script that builds ..." / "fabricate a parametric ... with booleans and bevels"'
+do_not_use_when:
+  - a generic prop (barrel, crate, chair) — summer_search_assets / summer_import_asset first, then summer_generate_3d
+  - a character or any organic shape — summer_generate_3d (scripted organic modelling is the documented failure mode)
+  - a blockout or placeholder — summer_run_script primitives/CSG are instant and in-scene
+  - the user has no Blender install and does not want one — this tool never installs, downloads, or bundles Blender
+  - "requires an engine build with FabricateMesh (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - 3d
+    - assets
+    - scripting
+  modalities:
+    - 3d-models
+    - scripts
+    - assets
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/run-script
+    - tool/generate-3d
+    - tool/search-assets
+    - tool/import-asset
+    - tool/import-hdri
+    - tool/instantiate-scene
+    - tool/world-snapshot
+    - tool/snapshot-diff
+    - tool/screenshot
+  skills:
+    - skill/fabricating-assets
+    - skill/asset-strategy
+    - skill/environment-kit
+    - skill/scene-scripting
+    - skill/verifying-scenes
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_fabricate_3d
+implementation:
+  module: src/mcp/tools/fabricate-tools.ts
+  export: registerFabricateTools
+surfaces:
+  mcp:
+    tool_name: summer_fabricate_3d
+    remote: false
+input_schema:
+  type: object
+  properties:
+    source:
+      type: string
+      description: Blender Python (bpy) code that creates mesh objects and leaves them linked in the scene. No export call — the engine exports the .glb. Pre-bound names bpy, bmesh, mathutils, math, Vector, Matrix, Euler.
+    name:
+      type: string
+      description: Asset name — used for the default out_path (res://assets/fabricated/<name>.glb) and the instantiated node. Sanitized by the engine to [A-Za-z0-9_-].
+    out_path:
+      type: string
+      description: Destination res:// path ending in .glb (default res://assets/fabricated/<name>.glb). An existing file is overwritten; '..' and hidden directories are refused.
+    target_size:
+      type: number
+      exclusiveMinimum: 0
+      description: Largest world-AABB dimension after instantiation — uniform scale, same rule as summer_instantiate_scene target_size. Only used together with import_to_scene.
+    import_to_scene:
+      type: object
+      description: Instantiate the imported .glb into the currently open scene after import. Omit to only write and import the file.
+      properties:
+        parent:
+          type: string
+          description: Parent node path in the open scene, e.g. '/' (scene root) or './World'.
+        position:
+          type: string
+          description: Optional local position as the engine variant string 'Vector3(x, y, z)'.
+      required:
+        - parent
+      additionalProperties: false
+    max_seconds:
+      type: number
+      description: Child budget in seconds (default 120, clamped 15-600) — Blender boot + script + procedural-colour bakes + export. The client waits max_seconds + 60 s.
+    checkpoint:
+      type: boolean
+      description: Take a SummerGit checkpoint before the child runs (default false). The result confesses (no_rewind_point) when none could be taken.
+    blender_path:
+      type: string
+      description: Explicit Blender executable. Only when the user named one; otherwise the engine resolves SUMMER_BLENDER_BIN, the editor setting filesystem/import/blender/blender_path, then PATH and well-known install locations.
+  required:
+    - source
+    - name
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - snapshot-diff
+  - screenshot

package/library/tools/game-control/resource.yaml

@@ -0,0 +1,84 @@
+id: tool/game-control
+kind: tool
+version: 1.0.0
+summary: Pause the running game, resume it, step exactly N physics or process frames, set the time scale, or list the live game instances.
+use_when:
+  - pausing the running game and stepping one physics frame at a time to make exact frame-by-frame assertions
+  - '"pause the game and advance a single physics frame" / "run the game at quarter speed" / "which game instances are up?"'
+  - checking that an offscreen playtest instance has attached before addressing it
+do_not_use_when:
+  - starting or stopping the game — summer_play / summer_stop
+  - a probe-based check inside a hidden disposable instance — a RunVerification probe awaiting physics_frame
+  - "requires an engine build with GamePause / GameStep / GameSpeed / ListGameInstances (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - runtime
+    - playtest
+    - verification
+  modalities:
+    - project
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/game-probe
+    - tool/game-input
+    - tool/play
+    - tool/stop
+    - tool/is-running
+  skills:
+    - skill/agent-playtesting
+    - skill/playtesting-a-feature
+    - skill/debugging-game-feel
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_game_control
+implementation:
+  module: src/mcp/tools/runtime-tools.ts
+  export: registerRuntimeTools
+surfaces:
+  mcp:
+    tool_name: summer_game_control
+    remote: false
+input_schema:
+  type: object
+  properties:
+    action:
+      type: string
+      enum:
+        - pause
+        - resume
+        - step
+        - speed
+        - instances
+      description: "'pause' suspends the game (Engine time frozen, physics inactive); 'resume' lifts the suspension; 'step' advances exactly N frames and leaves the game suspended; 'speed' sets the user time scale; 'instances' lists the live game instances (main + offscreen)."
+    frames:
+      type: integer
+      description: action step — frames to advance, 1..600 (default 1).
+    kind:
+      type: string
+      enum:
+        - physics
+        - process
+      description: action step — 'physics' (default, exact physics ticks) or 'process' (rendered frames).
+    speed:
+      type: number
+      description: action speed — user time scale in (0, 100]. 0.25 = quarter speed, 2 = double.
+    instance:
+      type: string
+      description: Game instance to address (default 'main'). Offscreen instances are named by summer_play with instance + mode offscreen; ignored by action instances.
+  required:
+    - action
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - game-probe