summer-engine 2.8.1 → 3.0.0

package/library/tools/replace-text/resource.yaml

@@ -0,0 +1,61 @@
+id: tool/replace-text
+kind: tool
+version: 1.0.2
+summary: "Safely replace text in an existing project file: unique match required by default, then a sha256-guarded write."
+use_when:
+  - targeted edits to scripts, scenes, or config without resending the whole file
+  - '"change speed = 5 to speed = 8 in player.gd"'
+  - renaming one function call in a script without rewriting the file
+do_not_use_when:
+  - writing a new file or rewriting most of it — summer_write_file
+  - the same text appears more than once and you have not narrowed the match
+facets:
+  lifecycle:
+    - build
+  domains:
+    - file
+    - project
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_replace_text
+implementation:
+  module: src/mcp/tools/file-tools.ts
+  export: registerFileTools
+surfaces:
+  mcp:
+    tool_name: summer_replace_text
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      description: Project path, e.g. res://scripts/player.gd
+    old_text:
+      type: string
+      minLength: 1
+      description: Exact text to replace.
+    new_text:
+      type: string
+      description: Replacement text; may be empty.
+    replace_all:
+      type: boolean
+      default: false
+      description: Replace every exact occurrence instead of requiring one unique match.
+  required:
+    - path
+    - old_text
+    - new_text
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - sha256-receipt

package/library/tools/run-editor-script/resource.yaml

@@ -0,0 +1,61 @@
+id: tool/run-editor-script
+kind: tool
+version: 1.0.2
+summary: Run an EditorScript `func _run():` in a fresh headless child editor against the on-disk project — the cold path for batch and project-wide jobs.
+use_when:
+  - re-saving many scenes, sweeping resources, mass import fixes, generating .tres assets, long bakes that should not block the live editor
+  - '"re-save every scene after the engine upgrade"'
+  - '"fix the import settings on all 200 textures"'
+do_not_use_when:
+  - work on the currently OPEN scene or anything relying on unsaved live edits — summer_run_script
+  - anything needing pixels — the headless child has no renderer
+  - "you need checkpoint/rollback or the scene-scripting ctx helpers — that is summer_run_script (RunSceneScript, Summer Engine 0.5.66 or newer, preview); RunEditorScript itself ships in current engines"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - project
+    - scripting
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/run-script
+  skills:
+    - skill/scene-scripting
+    - skill/headless-scripting
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_run_editor_script
+implementation:
+  module: src/mcp/tools/script-tools.ts
+  export: registerScriptTools
+surfaces:
+  mcp:
+    tool_name: summer_run_editor_script
+    remote: false
+input_schema:
+  type: object
+  properties:
+    source:
+      type: string
+      description: EditorScript GDScript source with `func _run():`. '@tool' / 'extends EditorScript' are optional — missing lines are prepended and reported in normalizations.
+    max_seconds:
+      type: number
+      description: Time budget in seconds for the child editor (default 120, clamped 15-600). Include boot time — large projects can take 30s+ just to start.
+    checkpoint:
+      type: boolean
+      description: Take a SummerGit checkpoint before the child editor runs. The result confesses (no_rewind_point) when none could be taken.
+  required:
+    - source
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false

package/library/tools/run-script/resource.yaml

@@ -0,0 +1,73 @@
+id: tool/run-script
+kind: tool
+version: 1.0.1
+summary: Run a GDScript `func run(ctx):` inside the live editor against the open scene — one script instead of a chain of add-node/set-prop calls.
+use_when:
+  - a change needs 3+ related ops or any computed placement (scatter, grids, procedural meshes, bulk edits)
+  - the ctx helpers (add_node, add_mesh, grid, scatter, light rig, environment) fit the job
+do_not_use_when:
+  - a single property tweak — summer_set_prop is cheaper
+  - a cold project-wide batch job that should not block the live editor — summer_run_editor_script
+  - "requires an engine build with RunSceneScript (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - scripting
+  modalities:
+    - scripts
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/run-editor-script
+    - tool/api-docs
+    - tool/world-snapshot
+    - tool/snapshot-diff
+  skills:
+    - skill/scene-scripting
+    - skill/verifying-scenes
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_run_script
+implementation:
+  module: src/mcp/tools/script-tools.ts
+  export: registerScriptTools
+surfaces:
+  mcp:
+    tool_name: summer_run_script
+    remote: false
+input_schema:
+  type: object
+  properties:
+    source:
+      type: string
+      description: GDScript source containing `func run(ctx):`. No extends/@tool line — just the function (plus any helpers).
+    max_seconds:
+      type: number
+      description: Time budget in seconds (default 20, clamped 5-120). The script blocks the editor while it runs — keep it short.
+    checkpoint:
+      type: boolean
+      description: Take a SummerGit checkpoint before running (default true). The result confesses (no_rewind_point) when no checkpoint could be taken.
+    undo:
+      type: string
+      enum:
+        - action
+        - none
+      description: Transaction mode (newer engines). 'action' (engine default) makes the run one undo action and rolls back on a runtime error; 'none' is checkpoint only. Older engines ignore this.
+  required:
+    - source
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - snapshot-diff
+  - screenshot

package/library/tools/runtime-animate/resource.yaml

@@ -0,0 +1,140 @@
+id: tool/runtime-animate
+kind: tool
+version: 1.0.0
+summary: Drive and read animation in the RUNNING game — AnimationPlayer clips, AnimationTree state machines, and live Skeleton3D bone poses.
+use_when:
+  - checking which clip or state-machine state is actually playing in the running game, then driving it (play, seek, travel, set a blend parameter)
+  - '"which animation is the player in right now?" / "travel the state machine to Attack and see if it blends"'
+  - reading live bone poses to prove a rig moves or an IK target lands
+do_not_use_when:
+  - wiring or authoring animation in the scene — character-animation-wiring / animation-tree skills
+  - no game is running (failure_reason game_not_running) — summer_play first
+  - "requires an engine build with RuntimeAnimation / RuntimeAnimationTree / GetRuntimeBones (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - runtime
+    - playtest
+    - animation
+  modalities:
+    - scenes
+    - animation
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/game-probe
+    - tool/game-control
+    - tool/runtime-call
+    - tool/play
+  skills:
+    - skill/agent-playtesting
+    - skill/character-animation-wiring
+    - skill/animation-tree
+    - skill/procedural-animation
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_runtime_animate
+implementation:
+  module: src/mcp/tools/runtime-tools.ts
+  export: registerRuntimeTools
+surfaces:
+  mcp:
+    tool_name: summer_runtime_animate
+    remote: false
+input_schema:
+  type: object
+  properties:
+    target:
+      type: string
+      enum:
+        - player
+        - tree
+        - bones
+      description: "'player' = AnimationPlayer (RuntimeAnimation), 'tree' = AnimationTree state machine (RuntimeAnimationTree), 'bones' = Skeleton3D poses (GetRuntimeBones)."
+    path:
+      type: string
+      description: ABSOLUTE runtime path of the AnimationPlayer / AnimationTree / Skeleton3D.
+    cmd:
+      type: string
+      enum:
+        - state
+        - play
+        - pause
+        - stop
+        - seek
+        - speed
+        - travel
+        - start
+        - set_param
+        - get_param
+      description: "Default 'state' (read-only). target player: state|play|pause|stop|seek|speed. target tree: state|travel|start|stop|set_param|get_param. Ignored for target bones."
+    name:
+      type: string
+      description: target player play — clip name (unknown_animation lists the clips).
+    position:
+      type: number
+      description: target player seek — position in seconds.
+    speed:
+      type: number
+      description: target player speed — speed_scale (1.0 = normal, negative plays backwards).
+    from_end:
+      type: boolean
+      description: target player play — start from the end (backwards).
+    blend:
+      type: number
+      description: target player play — custom blend time in seconds.
+    update:
+      type: boolean
+      description: target player seek — apply the pose immediately (default true).
+    state:
+      type: string
+      description: target tree travel/start — state machine node name (unknown_state lists them).
+    reset:
+      type: boolean
+      description: target tree travel/start — reset the destination clip (default true).
+    param:
+      type: string
+      description: target tree set_param/get_param — parameter path, e.g. 'parameters/Blend/blend_amount'.
+    value:
+      type:
+        - string
+        - number
+        - boolean
+      description: target tree set_param — new value (JSON scalar or Godot literal string).
+    playback_path:
+      type: string
+      description: target tree — state machine playback parameter (default 'parameters/playback'; nested machines use 'parameters/<Node>/playback').
+    bones:
+      type: array
+      items:
+        type: string
+      description: target bones — bone names to read (omit for the first 256; page larger rigs with this filter).
+    space:
+      type: string
+      enum:
+        - global
+        - local
+        - both
+      description: target bones — 'global' (default, skeleton-space global_pose), 'local' (pose), or 'both'.
+    include_rest:
+      type: boolean
+      description: target bones — also return each bone's rest Transform3D.
+    instance:
+      type: string
+      description: Game instance to address (default 'main'). Offscreen instances are named by summer_play with instance + mode offscreen; summer_game_control action 'instances' lists them.
+  required:
+    - target
+    - path
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - game-probe

package/library/tools/runtime-call/resource.yaml

@@ -0,0 +1,74 @@
+id: tool/runtime-call
+kind: tool
+version: 1.0.0
+summary: Call one method on a node in the RUNNING game and get its return value — trigger gameplay code directly instead of waiting for input or timers.
+use_when:
+  - triggering gameplay code in the running game and reading its answer — take_damage, start_wave, get_velocity
+  - '"call take_damage(25) on the boss in the running game" / "what does get_velocity return right now?"'
+  - a method's result is the fact you need and no property exposes it
+do_not_use_when:
+  - a plain property read or write — summer_game_probe props / summer_runtime_set are cheaper
+  - no game is running (failure_reason game_not_running) — summer_play first
+  - "requires an engine build with CallRuntimeMethod (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - runtime
+    - playtest
+    - verification
+  modalities:
+    - scenes
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/game-probe
+    - tool/runtime-set
+    - tool/api-docs
+    - tool/play
+    - tool/inspect-runtime-node
+  skills:
+    - skill/agent-playtesting
+    - skill/playtesting-a-feature
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_runtime_call
+implementation:
+  module: src/mcp/tools/runtime-tools.ts
+  export: registerRuntimeTools
+surfaces:
+  mcp:
+    tool_name: summer_runtime_call
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      description: ABSOLUTE runtime node path, e.g. '/root/Main/Player'.
+    method:
+      type: string
+      description: Method name to call on the node, e.g. 'take_damage', 'get_velocity'.
+    args:
+      type: array
+      items: {}
+      description: Positional arguments. JSON scalars, arrays and objects pass as-is; math values as Godot literal strings ('Vector3(0, 1, 0)'). Object and RID arguments are refused (bad_args).
+    instance:
+      type: string
+      description: Game instance to address (default 'main'). Offscreen instances are named by summer_play with instance + mode offscreen; summer_game_control action 'instances' lists them.
+  required:
+    - path
+    - method
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - game-probe

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

@@ -0,0 +1,80 @@
+id: tool/runtime-set
+kind: tool
+version: 1.0.0
+summary: Set one property on a node in the RUNNING game — the live object, never the scene file — and read back whether it applied.
+use_when:
+  - putting the running game into a test state without playing there by hand — teleport the player, set health to 1, flip a flag, toggle visibility
+  - '"move the player to (0, 2, 0) in the running game" / "set the boss health to 1 while it is running"'
+  - a runtime experiment whose change should die with the run instead of landing in the scene file
+do_not_use_when:
+  - the change must persist — edit the scene with summer_set_prop and restart the game
+  - no game is running (failure_reason game_not_running) — summer_play first
+  - "requires an engine build with SetRuntimeProp (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - runtime
+    - playtest
+    - verification
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/game-probe
+    - tool/runtime-call
+    - tool/game-control
+    - tool/play
+    - tool/set-prop
+    - tool/inspect-runtime-node
+  skills:
+    - skill/agent-playtesting
+    - skill/playtesting-a-feature
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_runtime_set
+implementation:
+  module: src/mcp/tools/runtime-tools.ts
+  export: registerRuntimeTools
+surfaces:
+  mcp:
+    tool_name: summer_runtime_set
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      description: ABSOLUTE runtime node path, e.g. '/root/Main/Player' (from summer_game_probe tree).
+    property:
+      type: string
+      description: Property name, e.g. 'position', 'health', 'visible'. 'script' and 'owner' are refused.
+    value:
+      type:
+        - string
+        - number
+        - boolean
+      description: New value. JSON scalars for primitives; Godot literal strings for math types ('Vector3(1, 2, 3)', 'Color(1, 0, 0, 1)'). Compared with Variant equality, so 1 and 1.0 both count as applied.
+    field:
+      type: string
+      description: Optional sub-field to set instead of the whole value, e.g. 'x' on a Vector3 property.
+    instance:
+      type: string
+      description: Game instance to address (default 'main'). Offscreen instances are named by summer_play with instance + mode offscreen; summer_game_control action 'instances' lists them.
+  required:
+    - path
+    - property
+    - value
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - game-probe

package/library/tools/runtime-spawn/resource.yaml

@@ -0,0 +1,95 @@
+id: tool/runtime-spawn
+kind: tool
+version: 1.0.0
+summary: Spawn a PackedScene into the RUNNING game (action spawn) or free a live node (action free) — stage a test in seconds without touching the scene file.
+use_when:
+  - staging a runtime test — place three goblins under the spawner, add a pickup next to the player, remove the boss to test the empty-arena path
+  - '"spawn a goblin at (4, 0, -2) in the running game" / "delete that projectile while the game runs"'
+  - the spawned or freed node must exist only for this run
+do_not_use_when:
+  - the node should be part of the scene permanently — summer_instantiate_scene / summer_remove_node in the EDITED scene, then restart
+  - no game is running (failure_reason game_not_running) — summer_play first
+  - "requires an engine build with SpawnRuntimeScene / FreeRuntimeNode (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - runtime
+    - playtest
+    - scenes
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/game-probe
+    - tool/runtime-set
+    - tool/game-control
+    - tool/instantiate-scene
+    - tool/remove-node
+    - tool/play
+  skills:
+    - skill/agent-playtesting
+    - skill/playtesting-a-feature
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_runtime_spawn
+implementation:
+  module: src/mcp/tools/runtime-tools.ts
+  export: registerRuntimeTools
+surfaces:
+  mcp:
+    tool_name: summer_runtime_spawn
+    remote: false
+input_schema:
+  type: object
+  properties:
+    action:
+      type: string
+      enum:
+        - spawn
+        - free
+      description: "'spawn' instantiates a PackedScene under parent (SpawnRuntimeScene); 'free' removes a node (FreeRuntimeNode)."
+    parent:
+      type: string
+      description: action spawn — ABSOLUTE runtime path of the parent, e.g. '/root/Main/Enemies'.
+    scene:
+      type: string
+      description: action spawn — PackedScene to instantiate, e.g. 'res://enemies/goblin.tscn'.
+    name:
+      type: string
+      description: action spawn — node name; the engine renames on collision and reports renamed_to.
+    props:
+      type: object
+      additionalProperties:
+        type:
+          - string
+          - number
+          - boolean
+      description: action spawn — properties set on the new node before it enters the tree ({position 'Vector3(0, 1, 0)', health 50}). Unknown ones land in prop_warnings, never fail the spawn.
+    path:
+      type: string
+      description: action free — ABSOLUTE runtime path of the node to free.
+    mode:
+      type: string
+      enum:
+        - queue_free
+        - free
+      description: action free — 'queue_free' (default, frees at the end of the frame) or 'free' (immediate).
+    instance:
+      type: string
+      description: Game instance to address (default 'main'). Offscreen instances are named by summer_play with instance + mode offscreen; summer_game_control action 'instances' lists them.
+  required:
+    - action
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - game-probe

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

@@ -0,0 +1,50 @@
+id: tool/save-scene
+kind: tool
+version: 1.0.2
+summary: Save an explicit scene to disk, for standalone saves or save-as.
+use_when:
+  - a standalone save or save-as is needed
+  - '"save a copy of this scene as level1_backup.tscn"'
+  - the user explicitly asks to save
+do_not_use_when:
+  - after ordinary mutation tools, which already append one save
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_save_scene
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_save_scene
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Scene to save, e.g. 'res://main.tscn'
+    path:
+      type: string
+      description: Optional save-as path, e.g. 'res://levels/level2.tscn'
+  required:
+    - scenePath
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid