summer-engine 3.1.0 → 3.2.0

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

@@ -1,14 +1,16 @@
 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.
+version: 1.1.0
+summary: Generate animation clips for a rigged model — curated humanoid mocap by name, or text-to-motion on any of your own rigs; costs credits, so confirm 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"'
+  - a custom action the curated library lacks — nod, bow, shrug, wave with the right arm
+  - animating a non-humanoid rig — a talking flower, animal, creature, turret or prop
 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
+  - the target model is not rigged — rig it first
+  - the motion is mechanical (doors, vehicles, cameras) — animate with a script or AnimationPlayer
 facets:
   lifecycle:
     - build
@@ -34,27 +36,60 @@ input_schema:
   properties:
     rigAssetId:
       type: string
-      description: Asset ID of a rigged character (from summer_generate_3d with options.rig=true)
+      description: "Asset ID of the rigged 3d_model. meshy-library: a Summer-rigged humanoid (summer_generate_3d with options.rig=true). text-to-motion: any of your own rigged GLB/FBX models"
     backend:
       type: string
       enum:
         - meshy-library
+        - text-to-motion
       default: meshy-library
-      description: "Backend: meshy-library (only option today)"
+      description: "meshy-library (default): curated humanoid mocap clip by motionName. text-to-motion: custom clips from text prompts on any of your own rigs (humanoid, animal, creature, plant, prop)"
     motionName:
       type: string
-      description: "Curated motion name: walk, run, attack_sword, idle, jump, etc."
+      description: "meshy-library only (required there): curated motion name — idle, walk, run, jump, attack, or an exact library name"
+    prompt:
+      type: string
+      minLength: 1
+      maxLength: 300
+      description: "text-to-motion: one action as a verb phrase, e.g. 'waves hello with the right arm' (1-300 chars). Shorthand for prompts: [prompt]"
+    prompts:
+      type: array
+      items:
+        type: string
+        minLength: 1
+        maxLength: 300
+      minItems: 1
+      maxItems: 8
+      description: "text-to-motion: 1-8 actions, one clip each (each 1-300 chars)"
+    takes:
+      type: integer
+      minimum: 1
+      maximum: 4
+      description: "text-to-motion: variations per prompt, 1-4 (default 1). Every take is a billed clip"
+    lockJoints:
+      type: array
+      items:
+        type: string
+        minLength: 1
+      description: "text-to-motion: bone names held still, e.g. ['Hips','Spine'] for a rooted plant. Never on characters that walk or jump"
+    cfgScale:
+      type: number
+      minimum: 1.5
+      maximum: 8
+      description: "text-to-motion: prompt adherence 1.5-8 (default 3); 5 for bigger, clearer gestures on stylized rigs"
+    idempotencyKey:
+      type: string
+      description: Stable retry key so the same logical request is not billed or queued twice
     wait:
       type: boolean
       default: true
-      description: Wait for completion (default true, up to 5 min). Set false to get jobId immediately.
+      description: Wait for completion (default true, up to 10 min). Set false to get jobId immediately.
     options:
       type: object
       additionalProperties: {}
       description: Backend-specific passthrough
   required:
     - rigAssetId
-    - motionName
   additionalProperties: false
 authority:
   filesystem: false

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

@@ -0,0 +1,50 @@
+id: tool/get-board
+kind: tool
+version: 1.0.0
+summary: Read the person's approved planning board (look, characters, place, storyboard, picks) with the look and picked cards as images to compare screenshots against.
+use_when:
+  - starting a build step for a game made from a planning board
+  - '"does the game look like the board?"'
+  - comparing a screenshot with the chosen look and picked cards
+do_not_use_when:
+  - the game was not made from a planning board (no project id in the brief)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - game-design
+    - verification
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_get_board
+implementation:
+  module: src/mcp/tools/generate-tools.ts
+  export: registerGenerateTools
+surfaces:
+  mcp:
+    tool_name: summer_get_board
+    remote: true
+input_schema:
+  type: object
+  properties:
+    project:
+      type: string
+      description: The game's project id (given in your build brief)
+    pictures:
+      type: boolean
+      description: Also return the look and the picked cards as images (default true)
+  required:
+    - project
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false
+evidence_checks:
+  - none

package/library/tools/get-project-context/resource.yaml

@@ -1,10 +1,11 @@
 id: tool/get-project-context
 kind: tool
-version: 1.1.0
-summary: Bind to the open project and return engine health, project name and path, current and main scene, trimmed settings, the template pin, and memory summary.
+version: 2.0.0
+summary: "Bind to the open project and return a compact context (project, current and main scene, health summary, template pin, memory, warnings); tree on request."
 use_when:
   - first call in every fresh session, to avoid guessing scene filenames
   - deliberately rebinding after the engine switched projects
+  - reading the open scene's tree, the engine's op list or project settings (include)
 facets:
   lifecycle:
     - build
@@ -28,6 +29,16 @@ surfaces:
 input_schema:
   type: object
   properties:
+    include:
+      type: array
+      items:
+        type: string
+        enum:
+          - scene_tree
+          - capabilities
+          - settings
+      maxItems: 3
+      description: "Heavy blocks to add to the compact default: 'scene_tree' (the open scene's node tree, up to 200 nodes), 'capabilities' (the engine's full op/capability lists), 'settings' (project settings, curated groups). settingsPrefix/settingsPrefixes imply 'settings'."
     settingsPrefix:
       type: string
       description: Only return project settings whose key starts with this prefix, e.g. 'audio/' or 'application/config/'. Omit for the curated default set.

package/library/tools/grep/resource.yaml

@@ -0,0 +1,77 @@
+id: tool/grep
+kind: tool
+version: 1.0.0
+summary: Search project files with a regex (ripgrep through the engine) and get file, line and text per match, with optional context lines and a result cap.
+use_when:
+  - finding where something is in big project files without reading them whole
+  - '"which entries of a big JSON file list fits_into?" / "every mount_side entry"'
+  - '"where is _on_door_body_entered defined?" / "which scenes use this material?"'
+do_not_use_when:
+  - you already know the file and want its content — summer_read_file (offset/limit, json_path)
+  - searching the Summer library — summer_search_library
+facets:
+  lifecycle:
+    - build
+  domains:
+    - file
+    - project
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/read-file
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_grep
+implementation:
+  module: src/mcp/tools/file-tools.ts
+  export: registerFileTools
+surfaces:
+  mcp:
+    tool_name: summer_grep
+    remote: false
+input_schema:
+  type: object
+  properties:
+    pattern:
+      type: string
+      minLength: 1
+      description: Ripgrep regular expression, e.g. '"fits_into"' or 'func _on_.*_pressed'
+    path:
+      type: string
+      description: "Search scope: a res:// directory or file, e.g. 'res://kit/' or 'res://kit/kit_manifest.json'. Default: the whole project."
+    glob:
+      type: string
+      description: File filter passed to ripgrep --glob, e.g. '*.gd', '**/*.json', '!addons/**'. A glob also reaches files .gitignore would skip.
+    case_sensitive:
+      type: boolean
+      description: "Match case exactly (default false: case-insensitive)."
+    context_lines:
+      type: integer
+      minimum: 0
+      maximum: 10
+      description: Lines of context before and after each match (0-10, default 0).
+    max_results:
+      type: integer
+      exclusiveMinimum: 0
+      maximum: 500
+      description: Most matches to return (default 50, max 500). truncated:true means there were more.
+    max_line_chars:
+      type: integer
+      minimum: 40
+      maximum: 2000
+      description: Clip every returned line to this many characters (default 240).
+    multiline:
+      type: boolean
+      description: Let the pattern span lines (ripgrep -U --multiline-dotall).
+  required:
+    - pattern
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/inspect-asset/resource.yaml

@@ -0,0 +1,71 @@
+id: tool/inspect-asset
+kind: tool
+version: 1.0.0
+summary: Measure a 3D asset file without adding it to a scene — AABB, origin, meshes, largest planar faces, open pipe ends, Marker3D anchors, collision shapes.
+use_when:
+  - learning a kit piece's real size, origin and which way it faces before placing it
+  - finding a piece's front and back planes (largest planar faces with their normals) or its pipe and duct ends (open boundary loops)
+  - reading the Marker3D anchors or collision shapes a kit piece ships with
+do_not_use_when:
+  - the piece is already in the scene and you need what surrounds it — summer_starcast
+  - you need the measurement between two placed nodes — summer_measure
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+    - assets
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/instantiate-scene
+    - tool/attach-to-surface
+    - tool/connect-ports
+    - tool/starcast
+  skills:
+    - skill/spatial-placement
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_inspect_asset
+implementation:
+  module: src/mcp/tools/placement-tools.ts
+  export: registerPlacementTools
+surfaces:
+  mcp:
+    tool_name: summer_inspect_asset
+    remote: false
+input_schema:
+  type: object
+  properties:
+    path:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Asset to measure, e.g. 'res://kit/facade/wall_single_01.tscn' (.tscn, .scn, .glb, .gltf, .res, .tres, .mesh or .obj). Loaded and instanced off-scene, never added to an open scene.
+    maxTriangles:
+      type: integer
+      minimum: 100
+      maximum: 300000
+      default: 60000
+      description: Triangle budget (100-300000) for the face and open-loop analysis (AABBs and counts are always complete). summary.warnings says when the budget cut the analysis and which budget covers the whole mesh.
+    detail:
+      type: string
+      enum: [summary, full]
+      default: summary
+      description: "summary: open_loops lists only port-like loops (radius over 2 cm with a partner loop facing another way, or the one opening of an end piece on its bounding-box face), or none. full: every open loop, including the outline of flat sheets. Every loop has a stable id ('+Y', '+Y#2') that summer_connect_ports accepts. Both start with the summary block (AABB, origin, the two largest opposite plane pairs with one_sided flags, port-like loop ids)."
+  required:
+    - path
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/inspect-node/resource.yaml

@@ -1,11 +1,12 @@
 id: tool/inspect-node
 kind: tool
-version: 1.0.3
-summary: Get every editable property of a node with current values, Variant types (raw int plus type_name), and resource info.
+version: 1.1.0
+summary: A node's editable properties with values, Variant types and resources, or only named fields plus derived transform, global_transform, scene_file_path.
 use_when:
   - before modifying a node, to understand its current state
   - "\"what is the player's speed / position / collision layer?\""
   - '"which material and mesh does this MeshInstance3D use?"'
+  - '"where is this piece, locally and in the world, and which scene is it?" — fields:[transform, global_transform, scene_file_path]'
 do_not_use_when:
   - sub-properties of the material, mesh, or shape itself — summer_inspect_resource
   - live values while the game runs — summer_inspect_runtime_node
@@ -35,6 +36,12 @@ input_schema:
     path:
       type: string
       description: Node path from scene tree, e.g. 'Player', 'World/Enemies/Boss', 'DirectionalLight3D'
+    fields:
+      type: array
+      items:
+        type: string
+      maxItems: 48
+      description: "Only these fields: property names or globs (e.g. 'position', 'surface_material_override/*') and the derived fields transform, global_transform, scene_file_path, aabb, warnings. Omit for every property."
   required:
     - path
   additionalProperties: false

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

@@ -1,9 +1,10 @@
 id: tool/inspect-resource
 kind: tool
-version: 1.0.2
-summary: Get all properties of a resource such as a material, mesh, shape, or environment.
+version: 1.1.0
+summary: Read a resource file (a mesh's AABB, surfaces and materials; a scene's nodes; any resource's non-default properties) or a resource a node holds.
 use_when:
   - reading sub-properties that the node inspector only names
+  - '"how many surfaces, triangles and which materials does this mesh .res have?"'
   - '"what colour is this material?" / "how big is this collision shape?"'
   - '"what settings does the WorldEnvironment resource have?"'
 do_not_use_when:
@@ -33,9 +34,19 @@ input_schema:
   properties:
     path:
       type: string
-      description: Resource path, e.g. 'res://materials/ground.tres' or 'res://models/player.glb'
-  required:
-    - path
+      minLength: 1
+      maxLength: 512
+      description: A resource FILE, e.g. 'res://materials/ground.tres', a mesh 'res://kit/meshes/wall_01.res', or a scene/model 'res://models/player.glb'. Loaded read-only in the editor. Do not combine with nodePath.
+    nodePath:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: With property, a node of the ACTIVE scene tab whose resource to read, e.g. 'Floor'.
+    property:
+      type: string
+      minLength: 1
+      maxLength: 128
+      description: With nodePath, the node property holding the resource, e.g. 'mesh', 'material_override', 'shape', 'environment'.
   additionalProperties: false
 authority:
   filesystem: false

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

@@ -1,11 +1,12 @@
 id: tool/instantiate-scene
 kind: tool
-version: 1.0.3
-summary: Add an existing scene or 3D model file as a child node, composing scenes from prefabs.
+version: 1.1.0
+summary: Add an existing scene or 3D model file as a child node, optionally placed in the same call (position, rotation_degrees, scale or transform).
 use_when:
   - placing a .tscn prefab or imported 3D model into a scene
   - '"put three copies of the enemy prefab in the level"'
   - '"add the imported car.glb to the scene"'
+  - placing a kit piece at an exact position and rotation in one call per piece
 do_not_use_when:
   - a bare built-in node type like Camera3D or Timer — summer_add_node
 facets:
@@ -47,6 +48,30 @@ input_schema:
       type: number
       exclusiveMinimum: 0
       description: Normalize the instance's physical size - uniformly scale it so its largest world-AABB dimension equals this many units (chair 1.0, car 4.5, person 1.7). Strongly recommended for imported .glb/.gltf models. Older engine builds ignore it; the result then lacks scale_applied and carries a target_size_note.
+    position:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items:
+        type: number
+      description: Parent-local position [x, y, z], set right after the instance is created (on the node path its receipt reports).
+    rotation_degrees:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items:
+        type: number
+      description: Parent-local rotation in degrees [x, y, z].
+    scale:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items:
+        type: number
+      description: Local scale [x, y, z]. Not with target_size.
+    transform:
+      type: string
+      description: Full local transform as "Transform3D(xx, xy, xz, yx, yy, yz, zx, zy, zz, ox, oy, oz)". Not with position, rotation_degrees, scale or target_size.
   required:
     - scenePath
     - parent

package/library/tools/measure/resource.yaml

@@ -0,0 +1,96 @@
+id: tool/measure
+kind: tool
+version: 1.0.0
+summary: Gap or overlap per axis between two placed nodes, or whether one face of many nodes is coplanar — catches facade gaps and modules standing proud. Read-only.
+use_when:
+  - checking that two facade modules meet edge to edge, or how far apart or overlapping two pieces are on each axis
+  - checking that every module of a facade line has its front on one plane (plane mode) and which ones stand proud or sit recessed
+  - verifying a placement numerically before the screenshot
+do_not_use_when:
+  - you want clearance around one node in every direction — summer_starcast
+  - you want to test a pose before moving anything — summer_test_placement
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+    - verification
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/starcast
+    - tool/place-adjacent
+    - tool/screenshot
+  skills:
+    - skill/spatial-placement
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_measure
+implementation:
+  module: src/mcp/tools/placement-tools.ts
+  export: registerPlacementTools
+surfaces:
+  mcp:
+    tool_name: summer_measure
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Exact scene, e.g. 'res://levels/street.tscn'. It must be open in the editor (any tab).
+    mode:
+      type: string
+      enum: [pair, plane]
+      default: pair
+      description: "pair: gap or overlap per axis between nodes a and b. plane: whether one face of every node in nodes lies on one plane."
+    a:
+      type: string
+      description: pair mode, first node (exact path from the scene root).
+    b:
+      type: string
+      description: pair mode, second node.
+    axis:
+      type: string
+      enum: [x, y, z]
+      description: pair mode, report only this axis.
+    nodes:
+      type: array
+      minItems: 2
+      maxItems: 32
+      items:
+        type: string
+      description: plane mode, 2-32 nodes whose face is checked.
+    face:
+      type: string
+      enum: ["+x", "-x", "+y", "-y", "+z", "-z"]
+      description: plane mode, which face, e.g. '+z' for the face pointing along +z.
+    space:
+      type: string
+      enum: [world, local]
+      default: world
+      description: "world axes, or the axes of a (pair) / nodes[0] (plane) for rotated facades."
+    tolerance:
+      type: number
+      minimum: 0
+      maximum: 1
+      default: 0.005
+      description: Distance treated as touching (pair) or coplanar (plane). Default 5 mm.
+  required:
+    - scenePath
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/place-adjacent/resource.yaml

@@ -0,0 +1,113 @@
+id: tool/place-adjacent
+kind: tool
+version: 1.0.0
+summary: Move one node so its bounds face sits against another's along an axis, lining up the other axes — facade modules edge to edge, storeys stacked. Saves the scene.
+use_when:
+  - laying facade or wall modules edge to edge along a street line
+  - stacking a storey, cornice or crown on the piece below
+  - putting a piece flush beside another with the same base height and front plane
+do_not_use_when:
+  - aligning or spacing a whole group along one axis — summer_align_distribute_3d
+  - seating a piece on a floor or a wall surface — summer_snap_to_surface or summer_attach_to_surface
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+    - level-design
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/measure
+    - tool/align-distribute-3d
+    - tool/repeat-along
+    - tool/inspect-asset
+  skills:
+    - skill/spatial-placement
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_place_adjacent
+implementation:
+  module: src/mcp/tools/placement-tools.ts
+  export: registerPlacementTools
+surfaces:
+  mcp:
+    tool_name: summer_place_adjacent
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Exact scene, e.g. 'res://levels/street.tscn'. It must be open in the editor (any tab).
+    subject:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Node to move (exact path from the scene root).
+    reference:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Node that stays put.
+    axis:
+      type: string
+      enum: [x, y, z]
+      description: Axis along which the two pieces meet.
+    side:
+      type: string
+      enum: [min, max]
+      description: "max: subject on the reference's +axis side (its min face against the reference's max face). min: the -axis side."
+    gap:
+      type: number
+      minimum: -100
+      maximum: 1000
+      default: 0
+      description: Distance between the two faces along axis. 0 = flush; negative = overlap.
+    alignOtherAxes:
+      oneOf:
+        - type: string
+          enum: [min, center, max, none]
+        - type: object
+          properties:
+            x:
+              type: string
+              enum: [min, center, max, none]
+            y:
+              type: string
+              enum: [min, center, max, none]
+            z:
+              type: string
+              enum: [min, center, max, none]
+          additionalProperties: false
+      default: none
+      description: "How to line up the other two axes: one mode for both, or per axis, e.g. {y: min, z: max} for same base height and one front plane."
+    space:
+      type: string
+      enum: [world, local]
+      default: world
+      description: world axes, or the reference's own axes for a rotated facade.
+  required:
+    - scenePath
+    - subject
+    - reference
+    - axis
+    - side
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/play/resource.yaml

@@ -1,13 +1,14 @@
 id: tool/play
 kind: tool
-version: 1.2.0
-summary: Start the game quietly by default (editor keeps tab and focus; focus true for a toolbar-style launch) — main or a given scene, embedded or offscreen, with pins.
+version: 1.3.0
+summary: Start the game quietly (editor keeps tab and focus) — main or a given scene, embedded or offscreen, with pins, or a local multiplayer session (players).
 use_when:
   - runtime verification after edits
   - the user wants to try the game or one level after a change
   - reproducing a bug that only shows at runtime
   - a deterministic, repeatable playtest run — pin the global RNG with seed and the timestep with fixed_fps
   - launching a deterministic or parallel offscreen playtest instance (seed, fixed frame rate, named offscreen instance) for the runtime tools to drive
+  - testing a Summer multiplayer game on this machine — players:2 (Local Play) runs its authority headless and two clients that join through the game's own Summer.client.join; no account, Docker or extra tools
   - launching while the user works on the same machine — the default (focus omitted or false) sends PlayGame agent:true, so the editor does not switch to the Game tab or grab focus; the game still runs embedded and is visible to the runtime tools
 do_not_use_when:
   - the game is already running and needs a restart — summer_stop first (seed/fixed_fps cannot reach a game that is already up)
@@ -80,6 +81,18 @@ input_schema:
     focus:
       type: boolean
       description: "Default false = QUIET play (PlayGame agent:true): the editor does not switch to the Game tab or grab focus for the embedded game, so the user keeps working. Pass true to launch the way the toolbar Play button does (Game tab + focus) — only when the user is watching and asked to see it. The result echoes agent_quiet:true when honoured; a launch result without it (posture_note) means the engine predates quiet play and most likely took focus."
+    players:
+      type: integer
+      minimum: 0
+      maximum: 64
+      description: "Local Play for a Summer multiplayer game (engine with Local Play): start the game's authority headless plus this many clients on this machine, each joining through the game's own Summer.client.join. The scenes and queue come from the project's summer.build.json WorldDefinition; no account, Docker or game flags are needed. Omit it and pass queue to start the queue's minPlayers from summer.build.json; 0 forces one ordinary run. The result's local_play block lists every process and persona, plus warnings when the roster is outside the queue's minPlayers..maxPlayers."
+    spectators:
+      type: integer
+      minimum: 0
+      description: "Local Play: also start this many spectator clients (only with players)."
+    queue:
+      type: string
+      description: "Local Play: the summer.build.json queue the local World stands in for (default: the first declared queue)."
   additionalProperties: false
 authority:
   filesystem: false