summer-engine 2.8.2 → 3.0.0

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

@@ -0,0 +1,159 @@
+id: tool/game-input
+kind: tool
+version: 1.0.1
+summary: Drive the running game's input — script timed synthetic events, or record the real inputs and replay them deterministically on a seeded instance.
+use_when:
+  - scripting a timed input sequence against the running game (walk right for 500 ms, jump at frame 30, click a button)
+  - recording my inputs while the game runs and replaying them deterministically for a repro or an A/B
+  - '"record what I do and replay it" / "press jump 10 times in a row in the running game"'
+do_not_use_when:
+  - binding or renaming input actions — summer_input_map_bind
+  - a hidden disposable probe run — a RunVerification probe with press()/key()
+  - no game is running (failure_reason game_not_running) — summer_play first
+  - "requires an engine build with SimulateInputScript / InputRecordStart / InputRecordStop / InputReplay (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-control
+    - tool/play
+    - tool/input-map-bind
+  skills:
+    - skill/agent-playtesting
+    - skill/playtesting-a-feature
+    - skill/investigating-bugs
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_game_input
+implementation:
+  module: src/mcp/tools/runtime-tools.ts
+  export: registerRuntimeTools
+surfaces:
+  mcp:
+    tool_name: summer_game_input
+    remote: false
+input_schema:
+  type: object
+  properties:
+    action:
+      type: string
+      enum:
+        - script
+        - record_start
+        - record_stop
+        - replay
+      description: "'script' schedules a timed sequence of synthetic inputs (SimulateInputScript); 'record_start'/'record_stop' capture the game's real input into res://.summer/replays/<id>.json; 'replay' plays a recording (or inline events) back."
+    events:
+      type: array
+      description: action script (required) or replay (instead of recording) — up to 1000 timed events; last event within 36000 frames / 600 s.
+      items:
+        type: object
+        properties:
+          at_frame:
+            type: integer
+            description: When to fire, in frames after scheduling (clock frame). Default 0 = the next frame.
+          at_ms:
+            type: integer
+            description: When to fire, in milliseconds after scheduling (clock ms); exact only on an instance with fixed_fps.
+          type:
+            type: string
+            enum:
+              - action
+              - key
+              - mouse_click
+              - axis
+              - raw
+            description: "'action' = InputMap action press/release; 'key' = keycode; 'mouse_click' = click at a position; 'axis' = analog strength between two actions; 'raw' = a recorded InputEvent replayed as {class, props}."
+          action:
+            type: string
+            description: type action — InputMap action name (unknown_action if not bound).
+          pressed:
+            type: boolean
+            description: type action|key — press (default true) or release.
+          strength:
+            type: number
+            description: type action — press strength 0..1 (default 1). type axis — signed strength; negative selects action_negative.
+          hold_ms:
+            type: integer
+            description: type action|key — auto-release after this many ms (0 = stays pressed until a release event).
+          keycode:
+            type: integer
+            description: type key — Godot Key enum value (e.g. 32 = Space).
+          physical_keycode:
+            type: integer
+            description: type key — physical Key enum value (alternative to keycode).
+          position:
+            type: array
+            items:
+              type: number
+            minItems: 2
+            maxItems: 2
+            description: type mouse_click — [x, y] in window pixels.
+          button:
+            type: integer
+            description: type mouse_click — MouseButton (1 = left, 2 = right, 3 = middle).
+          action_negative:
+            type: string
+            description: type axis — action for negative strength (e.g. 'move_left').
+          action_positive:
+            type: string
+            description: type axis — action for positive strength (e.g. 'move_right').
+          duration_ms:
+            type: integer
+            description: type axis — auto-release after this many ms.
+          class:
+            type: string
+            description: type raw — InputEvent class to instantiate (e.g. 'InputEventKey').
+          props:
+            type: object
+            description: type raw — properties set on the instantiated event.
+        required:
+          - type
+        additionalProperties: false
+    clock:
+      type: string
+      enum:
+        - frame
+        - ms
+      description: action script — whether at_frame ('frame', default, exact) or at_ms ('ms') schedules the events.
+    wait:
+      type: boolean
+      description: action script|replay — wait for the last event to fire (default true; the engine caps a waited script at 20 s). Longer scripts use wait false and observe with summer_game_probe.
+    include_motion:
+      type: boolean
+      description: action record_start — also record mouse/joypad motion events (default false; large).
+    save_as:
+      type: string
+      description: action record_stop — res://.summer/replays/<name>.json to write instead of a generated id.
+    recording:
+      type: string
+      description: action replay — the res://.summer/replays/<id>.json path returned by record_stop.
+    seed:
+      type: integer
+      description: action replay — assert the replay is reproducible; only accepted on an instance started with summer_play mode offscreen + deterministic true (else nondeterministic_instance).
+    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: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - game-probe

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

@@ -0,0 +1,90 @@
+id: tool/game-probe
+kind: tool
+version: 1.0.0
+summary: State AND pixels of one frame of the RUNNING game, atomically — live tree, property reads, and a screenshot stamped with the same frame counters.
+use_when:
+  - proving what the running game is actually doing before and after an action — the evidence read of every playtest loop
+  - '"show me the game right now with the player position" / "screenshot the offscreen instance and read the HUD values"'
+  - a claim about motion, spawning, or a state change needs a frame-stamped before/after pair
+do_not_use_when:
+  - the EDITED scene, not the running game — summer_world_snapshot / summer_screenshot target viewport
+  - no game is running (failure_reason game_not_running) — summer_play first
+  - "requires an engine build with GameProbe (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op — fall back to summer_get_runtime_tree + summer_screenshot target game"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - runtime
+    - playtest
+    - verification
+  modalities:
+    - scenes
+    - images
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/game-control
+    - tool/game-input
+    - tool/runtime-set
+    - tool/runtime-call
+    - tool/get-runtime-tree
+    - tool/inspect-runtime-node
+    - tool/screenshot
+    - tool/play
+  skills:
+    - skill/agent-playtesting
+    - skill/playtesting-a-feature
+    - skill/verifying-scenes
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_game_probe
+implementation:
+  module: src/mcp/tools/runtime-tools.ts
+  export: registerRuntimeTools
+surfaces:
+  mcp:
+    tool_name: summer_game_probe
+    remote: false
+input_schema:
+  type: object
+  properties:
+    tree:
+      type: object
+      description: Include the live scene tree ({name, class, path, children}) built game-side on the SAME frame as the pixels. Omit for no tree.
+      properties:
+        path:
+          type: string
+          description: Subtree root, ABSOLUTE runtime path (default the scene tree root).
+        depth:
+          type: integer
+          description: Depth to walk, 1..8 (default 2).
+        limit:
+          type: integer
+          description: Node cap, 1..4000 (default 200); truncated is reported.
+      additionalProperties: false
+    props:
+      type: array
+      items:
+        type: string
+      description: Up to 64 '<absolute path>:<property>' keys read on the same frame, e.g. '/root/Main/Player:position'. Values come back as Godot literal strings; misses land in missing.
+    screenshot:
+      type: boolean
+      description: Capture the game viewport (default true). false = state only, cheaper and works when the window draws nothing.
+    max_dim:
+      type: integer
+      description: Longest image side in pixels, 16..4096 (default 1280); the frame is downscaled to fit.
+    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.
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - frame-captured

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

@@ -0,0 +1,112 @@
+id: tool/generate-3d
+kind: tool
+version: 1.0.2
+summary: Generate a 3D model from text or images via Summer Studio, with optional auto-rig and animation pipeline; waits or returns a job id.
+use_when:
+  - creating a 3D asset or character from a prompt or reference image
+  - '"make me a low-poly tree / a sci-fi crate / a goblin for my game"'
+  - turning a concept image into a 3D model
+do_not_use_when:
+  - a 2D sprite, icon, or texture — summer_generate_image
+  - the model file already exists at a URL — summer_import_from_url
+facets:
+  lifecycle:
+    - build
+  domains:
+    - generate
+    - 3d
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_generate_3d
+implementation:
+  module: src/mcp/tools/generate-tools.ts
+  export: registerGenerateTools
+surfaces:
+  mcp:
+    tool_name: summer_generate_3d
+    remote: true
+input_schema:
+  type: object
+  properties:
+    prompt:
+      type: string
+      description: Description of the 3D model, e.g. 'a low-poly treasure chest'
+    kind:
+      type: string
+      default: text-to-3d
+      description: "Generation type: text-to-3d, image-to-3d, texture"
+    model:
+      type: string
+      default: hunyuan
+      description: "Model: hunyuan (default), trellis, meshy, or any fal-ai model ID"
+    imageUrl:
+      type: string
+      description: Source image URL for image-to-3d or texture
+    imageUrls:
+      type: array
+      items:
+        type: string
+      maxItems: 4
+      description: Up to four views for multi-image-to-3d
+    title:
+      type: string
+      description: Asset or character title
+    idempotencyKey:
+      type: string
+      description: Stable retry key so the same logical request is not billed or queued twice
+    assetIntent:
+      type: string
+      enum:
+        - character
+        - object
+      description: Controls whether hidden reference preparation targets a rig-safe character pose or isolated object view
+    referencePreparation:
+      type: string
+      enum:
+        - auto
+        - always
+        - never
+      default: auto
+      description: Shared Studio reference-preparation policy; auto is recommended
+    rig:
+      type: boolean
+      default: false
+      description: Auto-rig the generated model
+    animationNames:
+      type: array
+      items:
+        type: string
+      description: Animation names for the shared animated-character pipeline, e.g. Idle, Walk, Run, Jump
+    actionIds:
+      type: array
+      items:
+        type: integer
+        minimum: 0
+        maximum: 696
+      description: Exact Meshy action ids for the shared animated-character pipeline
+    riggingHeightMeters:
+      type: number
+      exclusiveMinimum: 0
+      maximum: 10
+      description: Character height used by auto-rigging
+    wait:
+      type: boolean
+      default: true
+      description: Wait for completion (default true, up to 10 min). Set false to get jobId immediately.
+    options:
+      type: object
+      additionalProperties: {}
+      description: Provider-specific params (target_polycount, topology, art_style, etc.)
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - job-completed

package/library/tools/generate-audio/resource.yaml

@@ -0,0 +1,80 @@
+id: tool/generate-audio
+kind: tool
+version: 1.0.2
+summary: "Generate audio via Summer Studio: text-to-speech, sound effects, music, or multi-voice dialogue."
+use_when:
+  - creating sound effects, music beds, or spoken lines for the game
+  - '"I need a jump sound / a sword swing / a coin pickup"'
+  - '"read this dialogue line in a gruff voice" or "background music for the menu"'
+do_not_use_when:
+  - a .wav/.ogg already exists online — summer_import_from_url
+facets:
+  lifecycle:
+    - build
+  domains:
+    - generate
+    - audio
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_generate_audio
+implementation:
+  module: src/mcp/tools/generate-tools.ts
+  export: registerGenerateTools
+surfaces:
+  mcp:
+    tool_name: summer_generate_audio
+    remote: true
+input_schema:
+  type: object
+  properties:
+    capability:
+      type: string
+      description: "Type of audio: text_to_speech, sound_effects, music, text_to_dialogue"
+    text:
+      type: string
+      description: Text for TTS, or description for sound effects
+    prompt:
+      type: string
+      description: Music description (for 'music' capability)
+    voiceId:
+      type: string
+      description: ElevenLabs voice ID for TTS
+    modelId:
+      type: string
+      description: ElevenLabs model ID (e.g. 'eleven_multilingual_v2')
+    durationSeconds:
+      type: number
+      description: Duration in seconds for SFX or music
+    inputs:
+      type: array
+      items:
+        type: object
+        properties:
+          text:
+            type: string
+          voiceId:
+            type: string
+        required:
+          - text
+          - voiceId
+        additionalProperties: false
+      description: Dialogue lines for text_to_dialogue
+    options:
+      type: object
+      additionalProperties: {}
+      description: Provider params, spread at the SDK's top level. Voice tuning goes in options.voiceSettings with camelCase keys (stability, similarityBoost, style, speed, useSpeakerBoost); flat snake_case is silently ignored.
+  required:
+    - capability
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - asset-created

package/library/tools/generate-image/resource.yaml

@@ -0,0 +1,62 @@
+id: tool/generate-image
+kind: tool
+version: 1.0.3
+summary: Generate or edit an image with allowlisted AI models via Summer Studio; supports text-to-image, image-to-image, and optional background removal.
+use_when:
+  - creating concept art, textures, or sprites from a prompt
+  - transforming an existing image given a reference URL
+facets:
+  lifecycle:
+    - build
+  domains:
+    - generate
+    - 2d
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_generate_image
+implementation:
+  module: src/mcp/tools/generate-tools.ts
+  export: registerGenerateTools
+surfaces:
+  mcp:
+    tool_name: summer_generate_image
+    remote: true
+input_schema:
+  type: object
+  properties:
+    prompt:
+      type: string
+      description: Description of the image to generate
+    model:
+      type: string
+      default: nano-banana-2
+      description: Model name or full provider ID
+    style:
+      type: string
+      default: realistic
+      description: "Style preset: realistic, cartoon, anime, or 'none' to skip"
+    referenceImageUrl:
+      type: string
+      description: Source image URL for img2img / edit mode. The prompt describes how to transform this image.
+    removeBackground:
+      type: boolean
+      description: Remove the background server-side and return an alpha PNG for sprites, icons, or isolated objects.
+    options:
+      type: object
+      additionalProperties: {}
+      description: Provider-specific params (guidance_scale, seed, image_size, negative_prompt, etc.)
+  required:
+    - prompt
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - asset-created

package/library/tools/generate-motion/resource.yaml

@@ -0,0 +1,66 @@
+id: tool/generate-motion
+kind: tool
+version: 1.0.2
+summary: Generate a curated mocap animation clip for a Summer-rigged humanoid; costs credits, so confirm with the user first.
+use_when:
+  - adding idle, walk, run, or combat clips to a rigged character
+  - '"make my character walk / run / swing a sword"'
+  - '"I need an idle animation for the rigged NPC"'
+do_not_use_when:
+  - the target model was not rigged by the Summer pipeline
+  - the motion is not humanoid (doors, vehicles, cameras) — animate with a script or AnimationPlayer
+facets:
+  lifecycle:
+    - build
+  domains:
+    - generate
+    - animation
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_generate_motion
+implementation:
+  module: src/mcp/tools/generate-tools.ts
+  export: registerGenerateTools
+surfaces:
+  mcp:
+    tool_name: summer_generate_motion
+    remote: true
+input_schema:
+  type: object
+  properties:
+    rigAssetId:
+      type: string
+      description: Asset ID of a rigged character (from summer_generate_3d with options.rig=true)
+    backend:
+      type: string
+      enum:
+        - meshy-library
+      default: meshy-library
+      description: "Backend: meshy-library (only option today)"
+    motionName:
+      type: string
+      description: "Curated motion name: walk, run, attack_sword, idle, jump, etc."
+    wait:
+      type: boolean
+      default: true
+      description: Wait for completion (default true, up to 5 min). Set false to get jobId immediately.
+    options:
+      type: object
+      additionalProperties: {}
+      description: Backend-specific passthrough
+  required:
+    - rigAssetId
+    - motionName
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - job-completed

package/library/tools/generate-video/resource.yaml

@@ -0,0 +1,66 @@
+id: tool/generate-video
+kind: tool
+version: 1.0.2
+summary: Generate a video from text or an image with allowlisted models via Summer Studio.
+use_when:
+  - creating cutscene, trailer, or reference footage from a prompt
+  - '"make a short intro cinematic from this concept art"'
+  - '"a 5-second clip of the castle at sunset for the trailer"'
+do_not_use_when:
+  - a looping in-game animation or sprite frames — summer_generate_image / skill/sprite-sheet
+facets:
+  lifecycle:
+    - build
+  domains:
+    - generate
+    - video
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_generate_video
+implementation:
+  module: src/mcp/tools/generate-tools.ts
+  export: registerGenerateTools
+surfaces:
+  mcp:
+    tool_name: summer_generate_video
+    remote: true
+input_schema:
+  type: object
+  properties:
+    prompt:
+      type: string
+      description: Description of the video content
+    model:
+      type: string
+      default: ltx
+      description: "Model name: ltx, kling, kling-turbo, minimax, veo3 (or any new model)"
+    imageUrl:
+      type: string
+      description: Source image URL — if provided, uses image-to-video mode
+    duration:
+      type: number
+      default: 5
+      description: Duration in seconds (5 or 10)
+    aspectRatio:
+      type: string
+      default: 16:9
+      description: "Aspect ratio: 16:9, 9:16, 1:1, 4:3"
+    options:
+      type: object
+      additionalProperties: {}
+      description: Provider-specific params (negative_prompt, num_frames, guidance_scale, etc.)
+  required:
+    - prompt
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - asset-created

package/library/tools/get-agent-playbook/resource.yaml

@@ -0,0 +1,40 @@
+id: tool/get-agent-playbook
+kind: tool
+version: 1.0.2
+summary: "AI-first operating guide for Summer MCP: safe workflow, verification ladder, honesty rules, anti-patterns, and recovery steps."
+use_when:
+  - at the start of a fresh session, before touching scenes
+  - a new chat is about to touch a project it has never seen
+  - the agent is unsure of Summer's safety rules or verification ladder
+do_not_use_when:
+  - mid-task lookups of a specific tool's arguments — read that tool's description instead
+facets:
+  lifecycle:
+    - build
+  domains:
+    - project
+    - agent-workflow
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_agent_playbook
+implementation:
+  module: src/mcp/tools/project-tools.ts
+  export: registerProjectTools
+surfaces:
+  mcp:
+    tool_name: summer_get_agent_playbook
+    remote: true
+input_schema:
+  type: object
+  properties: {}
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false