summer-engine 2.8.2 → 3.0.0

package/library/templates/3d-fps-simple-animated-npc/resource.yaml

@@ -0,0 +1,21 @@
+id: template/3d-fps-simple-animated-npc
+kind: template
+version: 1.1.4
+summary: FPS starter with an animated NPC — first-person controller plus a rigged, animated character to build on.
+use_when:
+  - starting an FPS that needs animated NPCs from day one
+facets:
+  lifecycle: [build]
+  domains: [3d, fps, npc]
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - template-3d-fps-simple-animated-npc
+repo: https://github.com/SummerEngine/template-3d-fps-simple-animated-npc
+commit: b987a48aa7331a44189d9103040fc37a328b81ee
+tree_digest: 8b7c06dc42c441c47547c71d85c5cb64d5ce61c2373f88324e97b1c44c424927
+default_branch: main
+systems: [fps-controller, npc, animation]

package/library/templates/3d-lan-multiplayer-starter/resource.yaml

@@ -0,0 +1,22 @@
+id: template/3d-lan-multiplayer-starter
+kind: template
+version: 1.0.1
+summary: 3D LAN multiplayer starter built on GDQuest's open-source work — host/join flow and synced players.
+use_when:
+  - starting a LAN or local multiplayer 3D game
+  - needing a working host/join + player sync baseline
+facets:
+  lifecycle: [build]
+  domains: [3d, multiplayer]
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - template-3d-lan-multiplayer-starter
+repo: https://github.com/SummerEngine/template-3d-lan-multiplayer-starter
+commit: f4207b6462ad887c1d727078b67302179908012d
+tree_digest: e10b982b874759aee57b8feaafa6a753f3fd5dcebef2af396882ecfcbeda8abe
+default_branch: main
+systems: [multiplayer, lan, player-sync]

package/library/templates/3d-open-world-explore-tps/resource.yaml

@@ -0,0 +1,21 @@
+id: template/3d-open-world-explore-tps
+kind: template
+version: 1.0.2
+summary: Third-person open-world exploration starter — camera rig, traversal, and a large explorable space.
+use_when:
+  - starting a third-person open-world or exploration game
+facets:
+  lifecycle: [build]
+  domains: [3d, open-world, third-person]
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - template-3d-open-world-explore-tps
+repo: https://github.com/SummerEngine/template-3d-open-world-explore-tps
+commit: d832fa0b5574d154ac85020ab8b7646174915b11
+tree_digest: 5e3fd26e891820123ace7424f7f4cb91e996f34d3d2fa646cae838c2bca3e9ae
+default_branch: main
+systems: [third-person-controller, camera-rig, world]

package/library/templates/3d-procedural-road-world/resource.yaml

@@ -0,0 +1,21 @@
+id: template/3d-procedural-road-world
+kind: template
+version: 1.0.0
+summary: Playable procedural open-world starter — generated roads and world around a drivable/walkable space.
+use_when:
+  - starting a procedurally generated open-world game
+facets:
+  lifecycle: [build]
+  domains: [3d, procedural, open-world]
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - template-3d-procedural-road-world
+repo: https://github.com/SummerEngine/template-3d-procedural-road-world
+commit: 31494077cfad5a9c44685deb767d891ec68f2f05
+tree_digest: 38fb9438d0cb8711aff786ac452d457242a8a1bd757ddc19ac980611e85b54d8
+default_branch: codex/importable-template
+systems: [procedural-generation, roads, world]

package/library/templates/3d-racing-game/resource.yaml

@@ -0,0 +1,21 @@
+id: template/3d-racing-game
+kind: template
+version: 1.0.4
+summary: Racing starter — drivable vehicle, track, and lap structure to build a racing game on.
+use_when:
+  - starting a racing or driving game
+facets:
+  lifecycle: [build]
+  domains: [3d, racing]
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - template-3d-racing-game
+repo: https://github.com/SummerEngine/template-3d-racing-game
+commit: 8305f5e68a5888e0f6053ca8ef5d7a0bd041aa79
+tree_digest: a6d31140518b7253da5527eafdc8bf8abc7e4253298d262f84194632e48a733c
+default_branch: main
+systems: [vehicle, track, laps]

package/library/templates/3d-royale-clash-type/resource.yaml

@@ -0,0 +1,21 @@
+id: template/3d-royale-clash-type
+kind: template
+version: 1.0.3
+summary: "Card-deployment lane battle starter in the Clash Royale style: drag-and-drop units, buildings and spells, elixir economy, towers, an AI rival deck."
+use_when:
+  - starting an auto-battler or lane-pushing strategy game
+facets:
+  lifecycle: [build]
+  domains: [3d, auto-battler, strategy]
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - template-3d-royale-clash-type
+repo: https://github.com/SummerEngine/template-3d-royale-clash-type
+commit: 31f08ad07ac24f578b01c957e2219efbbfe655cf
+tree_digest: 3892bb0fb80b17187a9eca23c64c5a07d397a159c48a152411cbc3e12f8eec7e
+default_branch: main
+systems: [lanes, unit-spawning, auto-battle]

package/library/templates/3d-third-person-controller/resource.yaml

@@ -0,0 +1,21 @@
+id: template/3d-third-person-controller
+kind: template
+version: 1.0.4
+summary: 3D third-person character controller built on GDQuest's open-source work, inspired by Ratchet and Clank-style movement.
+use_when:
+  - starting a 3D game around a polished third-person character controller
+facets:
+  lifecycle: [build]
+  domains: [3d, third-person]
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - template-3d-third-person-controller
+repo: https://github.com/SummerEngine/template-3d-third-person-controller
+commit: 694b6ae5eb9f4fc4df1f60b20d57aab82e94216a
+tree_digest: 43a4a86c26bf7d4335d427190d38541a8684ffa45c3ef0b84f85b5a9fd0b90f2
+default_branch: master
+systems: [third-person-controller, camera-rig, animation]

package/library/templates/3d-voxel-sandbox/resource.yaml

@@ -0,0 +1,24 @@
+id: template/3d-voxel-sandbox
+kind: template
+version: 1.2.8
+summary: Voxel sandbox starter — chunked world, face culling, mining and building, seeded generation.
+use_when:
+  - starting a Minecraft-like voxel sandbox
+facets:
+  lifecycle: [ build ]
+  domains:
+    - 3d
+    - world-building
+    - open-world
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - template-3d-voxel-sandbox
+repo: https://github.com/SummerEngine/template-3d-voxel-sandbox
+commit: 2b31cf12761b2d00d5268c2056d0c0706f6ad54e
+tree_digest: 97a2288c64c89b6920dffd8f0ace1584833ae9cb0ddd51af6ff8b64b4484d351
+default_branch: main
+systems: [ chunked-world, face-culling, mining-building, seeded-generation ]

package/library/templates/README.md

@@ -0,0 +1,94 @@
+# library/templates/ — pin manifests
+
+Each `library/templates/<slug>/resource.yaml` is a **pin manifest** (CONTRACT.md §7).
+Template code lives in satellite repos under `github.com/SummerEngine`; this directory
+holds only descriptors. `npm run generate:registry` compiles them into
+`registry/generated/templates-registry.json`, which is the only thing the CLI reads at
+runtime (`src/core/templates.ts`).
+
+## Resolution (what `summer create <slug> [name]` does)
+
+1. **Resolve** `<slug>` against the generated registry: exact id (`template/<slug>`),
+   exact slug, exact alias (the legacy `template-<slug>` names), then an unambiguous
+   prefix of a slug or alias. Ambiguity or no match is an error that lists what exists.
+2. **Pinned template** (`repo` + `commit` + `tree_digest`):
+   1. `git init` in the new directory, `git remote add origin <repo>`,
+      `git fetch --depth 1 origin <commit>` — the exact 40-char SHA, never a branch.
+      `default_branch` is informational only and is never consulted.
+   2. Recompute `tree_digest` with the formula below and **refuse** on mismatch — the
+      directory is removed and nothing is written.
+   3. `git checkout <commit>` (detached). `.git` is removed unless `--keep-git`.
+3. **Built-in template** (`builtin: true`, no pin): generated in-process by
+   `BUILTIN_GENERATORS` in `src/cli/commands/create.ts` — no download.
+4. **Record** the pin into the project's `.summer/project.json`
+   (`src/project-memory/project-manifest.ts`, merged if the file exists):
+
+   ```json
+   { "template": { "id": "template/2d-platformer", "version": "1.0.0",
+                   "repo": "https://github.com/SummerEngine/template-2d-platformer",
+                   "commit": "<40 hex>", "tree_digest": "<64 hex>" },
+     "toolkit_version": "<summer-engine package version>",
+     "created_at": "<ISO 8601>" }
+   ```
+
+   Built-ins record `{ "id", "version", "builtin": true }` instead of a pin.
+
+`summer list templates` prints the same registry (status, systems, preview notes). There
+is no live GitHub-org listing anywhere in the CLI: a template that is not in this
+directory is not installable.
+
+## tree_digest formula
+
+The digest is the SHA-256 of the exact output of:
+
+```
+git ls-tree -r <commit> --format='%(objectname) %(path)'
+```
+
+piped through `shasum -a 256` (equivalently `sha256sum`). That output is one line per
+file — the git blob object ID, a space, and the path — in git's canonical path order
+with newline-terminated lines. It is deterministic across git versions (unlike
+`git archive`, whose bytes vary), and any change to any file's content or path changes
+the digest. `--format` needs git ≥ 2.36. `computeTreeDigest` in `src/core/templates.ts`
+runs exactly this command and hashes its stdout bytes; the unit test checks it against
+the shell pipeline on a fixture repo.
+
+To verify a pin locally:
+
+```
+git init t && cd t
+git remote add origin <repo>.git
+git fetch --depth 1 origin <commit>
+git ls-tree -r <commit> --format='%(objectname) %(path)' | shasum -a 256
+```
+
+## Schema: builtin XOR pin
+
+`registry/schemas/template.schema.json` accepts exactly one of two shapes:
+
+- **pinned**: `repo`, `commit` (40 hex), `tree_digest` (64 hex), optional
+  `default_branch`, `zip`;
+- **builtin**: `builtin: true` and none of the pin fields.
+
+Declaring both, or neither, fails `npm run validate:library`.
+
+## Built-in templates (`empty`, `3d-basic`)
+
+The two built-ins are not satellite repos: `summer create` generates them locally, so
+their manifests declare `builtin: true` and carry no pin. Their `facets.domains` include
+`builtin`. A test (`src/cli/commands/create.test.ts`) asserts that the set of
+`builtin: true` manifests equals the set of generators in the CLI.
+
+## Status and private repos
+
+A manifest whose repo the public CLI cannot fetch must not be `stable`. Mark it
+`status: preview` with a `do_not_use_when` note; `summer create` prints the note as a
+warning and the fetch fails fast (git never prompts for credentials).
+
+## Updating a template
+
+1. Land the change in the satellite repo.
+2. Open a PR here that bumps `commit` to the new SHA, recomputes `tree_digest` with the
+   formula above, and bumps `version` in the manifest.
+3. CI validates the manifest; the pin only moves when this PR merges. There is no other
+   update path — pushing to the satellite repo alone changes nothing for users.

package/library/templates/empty/resource.yaml

@@ -0,0 +1,16 @@
+id: template/empty
+kind: template
+version: 1.1.0
+summary: "Built-in: empty 3D project with just a root node — generated locally by summer create, no download."
+use_when:
+  - starting from a completely blank project
+facets:
+  lifecycle: [build]
+  domains: [3d, builtin]
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+builtin: true
+systems: [project-scaffold]

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

@@ -0,0 +1,60 @@
+id: tool/add-node
+kind: tool
+version: 1.0.2
+summary: Add a node of any Godot type to an exact scene, which does not need to be the active editor tab.
+use_when:
+  - building out scene structure node by node
+  - '"add a Camera3D / DirectionalLight3D / Area2D / Timer to this scene"'
+  - giving the player a child node for a hitbox, sprite, or audio player
+do_not_use_when:
+  - placing an existing .tscn prefab or imported model — summer_instantiate_scene
+  - 3+ related nodes or any computed placement — summer_run_script
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_add_node
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_add_node
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Target scene path, e.g. 'res://main.tscn'
+    parent:
+      type: string
+      description: Parent node path, e.g. './World' or './World/Enemies'
+    type:
+      type: string
+      description: Summer Engine node type, e.g. 'MeshInstance3D', 'CharacterBody3D'
+    name:
+      type: string
+      description: Name for the new node, e.g. 'Player', 'MainCamera'
+  required:
+    - scenePath
+    - parent
+    - type
+    - name
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/align-distribute-3d/resource.yaml

@@ -0,0 +1,87 @@
+id: tool/align-distribute-3d
+kind: tool
+version: 1.0.0
+summary: Align (min/center/max) or equal-space (centers/gaps) 2-16 ordered 3D subjects along one world axis from their visible AABBs, then save the scene.
+use_when:
+  - lining up props, stalls, pillars, or lights along one axis
+  - spacing a row of objects evenly by center or by visible edge gap
+do_not_use_when:
+  - seating objects on a surface — summer_snap_to_surface (alignment solves one axis only)
+  - the subjects have no visible GeometryInstance3D descendants (the tool fails instead of fabricating bounds)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/snap-to-surface
+    - tool/test-placement
+    - tool/world-snapshot
+  skills:
+    - skill/world-building-3d
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_align_distribute_3d
+implementation:
+  module: src/mcp/tools/spatial-tools.ts
+  export: registerSpatialTools
+surfaces:
+  mcp:
+    tool_name: summer_align_distribute_3d
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Exact target scene, e.g. 'res://levels/market.tscn'.
+    subjectPaths:
+      type: array
+      items:
+        type: string
+        minLength: 1
+        maxLength: 256
+      minItems: 2
+      maxItems: 16
+      description: Two to sixteen exact Node3D paths in the order to align or distribute.
+    axis:
+      type: array
+      items:
+        type: number
+      minItems: 3
+      maxItems: 3
+      description: Finite, non-zero world axis [x,y,z]; normalization is automatic.
+    mode:
+      type: string
+      enum:
+        - align_min
+        - align_center
+        - align_max
+        - distribute_centers
+        - distribute_gaps
+      description: Alignment anchor or equal-spacing policy.
+  required:
+    - scenePath
+    - subjectPaths
+    - axis
+    - mode
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/api-docs/resource.yaml

@@ -0,0 +1,57 @@
+id: tool/api-docs
+kind: tool
+version: 1.0.2
+summary: Offline engine class-reference lookup — verify a property, method, signal, or constant before writing script code instead of guessing names.
+use_when:
+  - checking an exact property/method/signal/constant name or default before summer_run_script or a .gd edit
+  - '"does Node3D have look_at?" / "what is the CharacterBody3D velocity property called?"'
+  - '"which signal fires when a body enters an Area3D?"'
+do_not_use_when:
+  - the bundled reference is missing from this install (the tool says api_docs_not_installed) — verify against the engine with summer_inspect_node instead
+  - you need the live value of a property on a node in the scene — summer_inspect_node
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scripting
+    - engine
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/run-script
+  skills:
+    - skill/scene-scripting
+    - skill/gdscript-patterns
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_api_docs
+implementation:
+  module: src/mcp/tools/script-tools.ts
+  export: registerScriptTools
+surfaces:
+  mcp:
+    tool_name: summer_api_docs
+    remote: true
+input_schema:
+  type: object
+  properties:
+    class_name:
+      type: string
+      description: Engine class name, e.g. 'BoxShape3D', 'CharacterBody3D', 'SurfaceTool'. Case-insensitive.
+    member:
+      type: string
+      description: Optional property/method/signal/constant name to fetch just that member, e.g. 'size' or 'move_and_slide'.
+  required:
+    - class_name
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/batch/resource.yaml

@@ -0,0 +1,52 @@
+id: tool/batch
+kind: tool
+version: 1.0.3
+summary: Run multiple engine ops in one call, forwarded verbatim; one undo step unless single-only ops force a split (then one per chunk). Also reaches raw ops.
+use_when:
+  - multi-node builds that should undo as one step (no single-only ops in the list)
+  - reaching engine ops that have no dedicated tool
+do_not_use_when:
+  - you need the whole list to be exactly one undo step but it contains a single-only op (the engine splits it; expect one undo step per chunk)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - editor
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_batch
+implementation:
+  module: src/mcp/tools/scene-tools.ts
+  export: registerSceneTools
+surfaces:
+  mcp:
+    tool_name: summer_batch
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Required when ops contains scene mutations; exact res:// target scene path
+    ops:
+      type: array
+      items:
+        type: object
+        additionalProperties: {}
+      description: Array of operation objects, each with 'op' plus its parameters
+  required:
+    - ops
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/camera-bookmark/resource.yaml

@@ -0,0 +1,73 @@
+id: tool/camera-bookmark
+kind: tool
+version: 1.0.0
+summary: Save, list, or delete named camera viewpoints stored in the project, so before/after screenshots are taken from exactly the same pose.
+use_when:
+  - '"save this camera angle" / "remember this viewpoint" so later screenshots line up with it'
+  - comparing a scene before and after a change from one fixed, repeatable camera pose
+  - listing or removing the saved viewpoints of a project
+do_not_use_when:
+  - taking the screenshot itself — summer_screenshot target "scene" with framing "bookmark" and bookmark_name reuses a saved pose
+  - a one-off pose you will not reuse — summer_screenshot framing "free" with camera_position/camera_look_at
+  - "requires an engine build with the camera bookmark ops (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - verification
+    - scenes
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/screenshot
+    - tool/world-snapshot
+    - tool/snapshot-diff
+  skills:
+    - skill/verifying-scenes
+    - skill/scene-scripting
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_camera_bookmark
+implementation:
+  module: src/mcp/tools/visual-tools.ts
+  export: registerVisualTools
+surfaces:
+  mcp:
+    tool_name: summer_camera_bookmark
+    remote: false
+input_schema:
+  type: object
+  properties:
+    action:
+      type: string
+      enum:
+        - save
+        - list
+        - delete
+      description: '"save" a viewpoint, "list" the saved ones, or "delete" one by name.'
+    name:
+      type: string
+      description: 'Bookmark name for save/delete: 1-64 characters from A-Z a-z 0-9 _ - (e.g. "hero_closeup").'
+    position:
+      type: string
+      description: 'save only. Camera position as a Godot literal, e.g. "Vector3(0, 5, 12)". Goes together with look_at; omit BOTH to capture the current editor 3D viewport camera.'
+    look_at:
+      type: string
+      description: 'save only. Point the camera looks at, e.g. "Vector3(0, 1, 0)". Must differ from position.'
+    fov:
+      type: number
+      description: save only. Vertical field of view in degrees (1..179, default 60). With a captured viewport pose the viewport camera's fov wins.
+  required:
+    - action
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/check-job/resource.yaml

@@ -0,0 +1,45 @@
+id: tool/check-job
+kind: tool
+version: 1.0.2
+summary: Check the status of an async generation job by id.
+use_when:
+  - a generation ran without waiting, or timed out, and needs re-checking
+  - '"is my 3D model / video done yet?"'
+  - a generate_* call returned a job id instead of a finished asset
+do_not_use_when:
+  - the generation returned the asset directly — there is nothing to poll
+facets:
+  lifecycle:
+    - build
+  domains:
+    - generate
+    - pipeline
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - summer_check_job
+implementation:
+  module: src/mcp/tools/generate-tools.ts
+  export: registerGenerateTools
+surfaces:
+  mcp:
+    tool_name: summer_check_job
+    remote: true
+input_schema:
+  type: object
+  properties:
+    jobId:
+      type: string
+      description: The job ID returned by an async generation tool
+  required:
+    - jobId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false