summer-engine 3.1.0 → 3.2.0

package/library/skills/multiplayer-publish/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: multiplayer-publish
+description: "Ship a hosted Summer multiplayer game: the summer.games bundle, server preset, pre-upload checks, and a new Build."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: multiplayer-and-networking
+user-invocable: true
+allowed-tools: Read Grep Glob Edit Write summer_read_file summer_write_file summer_project_setting summer_open
+paths: ["export_presets.cfg", "summer.build.json", "world.json", "source-domains.json", "runtime-manifest.json", "project.godot"]
+---
+
+# /multiplayer-publish — from project to a Build players can join
+
+Step 5 of the multiplayer sequence. It assumes the layout from
+`multiplayer-project`: `summer.build.json`, `world.json`,
+`runtime-manifest.json`, `source-domains.json`, and the `client/`,
+`authority/` and `network/` folders.
+
+**Status:** the summer.games export is in Summer's editor. Bundle upload in
+Studio is rolling out: if the game's Builds page doesn't accept a `.zip`
+bundle yet, stop after step 4 and tell the user the bundle is ready to
+upload.
+
+## 1. What gets built
+
+**Project > Export**, preset **summer.games**, **Export Project** to a `.zip`
+gives one file, the bundle, which becomes one Build:
+
+| Entry | What it is |
+|---|---|
+| `client.pck` | What players run, without anything the source graph marks server-only |
+| `server.pck` | What the authority runs, exported with the server preset |
+| `config/` | `summer.build.json` and every file it names (WorldDefinitions, runtime descriptor, source graph) |
+| `summer-bundle.json` | The Summer version, both packs' main scenes, the composition, and every entry's SHA-256 |
+
+Players get `client.pck` on iOS, macOS or Windows (`targetPlatforms` in
+`summer.build.json`). Summer runs `server.pck` on Linux for every World.
+
+## 2. The two export presets
+
+Every project has a built-in **summer.games** preset. The server needs a
+second, Linux dedicated-server preset, named exactly as
+`server.exportPreset` in `summer.build.json`. `export_presets.cfg`:
+
+```ini
+[preset.0]
+
+name="summer.games"
+platform="summer.games"
+runnable=false
+dedicated_server=false
+custom_features="summer_client"
+export_filter="all_resources"
+include_filter=""
+exclude_filter=""
+export_path=""
+encrypt_pck=false
+encrypt_directory=false
+script_export_mode=2
+
+[preset.0.options]
+
+platforms/ios=true
+platforms/macos=true
+platforms/windows=false
+
+[preset.1]
+
+name="Courtyard Authority"
+platform="Linux"
+runnable=false
+dedicated_server=true
+custom_features="summer_authority"
+export_filter="all_resources"
+include_filter=""
+exclude_filter="client/*"
+export_path=""
+encrypt_pck=false
+encrypt_directory=false
+script_export_mode=2
+
+[preset.1.options]
+
+binary_format/architecture="x86_64"
+```
+
+To make the same in the Export dialog:
+
+- **summer.games:** tick the platforms the game supports; leave encryption
+  off. It needs no exclude filters, because the source graph decides what
+  stays out of `client.pck`.
+- **Server:** **Add... > Linux**, named exactly as `server.exportPreset`.
+  **Resources:** Export Mode **Export as dedicated server**, and exclude the
+  client folder (`client/*`). **Features:** Custom `summer_authority`.
+
+Both presets must include the composition; each must include its entry
+scene.
+
+Textures: iOS and macOS read ETC2/ASTC (`textures/vram_compression/import_etc2_astc=true`
+in `project.godot`), and Windows reads S3TC/BPTC (`import_s3tc_bptc=true`).
+Enable the ones for the platforms you tick. The exporter's **Fix Import**
+button does it.
+
+## 3. Export
+
+In the editor: **Project > Export**, select **summer.games**, **Export
+Project**, save as `build/<game>.summer.zip`. Or from a terminal (`<summer>`
+is the Summer editor executable):
+
+```sh
+<summer> --headless --path . --import
+<summer> --headless --path . --export-release "summer.games" build/courtyard.summer.zip
+```
+
+A good export ends like this:
+
+```text
+summer.games: Left 4 server-only files out of client.pck, as source-domains.json declares.
+summer.games: summer.games bundle for iOS, macOS with ETC2/ASTC textures: build/courtyard.summer.zip
+summer.games: Entries: summer-bundle.json, client.pck (...), config/runtime-manifest.json (...), config/source-domains.json (...), config/summer.build.json (...), config/world.json (...), server.pck (...)
+summer.games: Server: server.pck from preset "Courtyard Authority", mainScene res://authority/main.tscn
+summer.games: mainScene: res://client/main.tscn
+summer.games: compositionPath: res://network/composition.tres
+summer.games: Exported by Summer 0.6.0 (engine ...). Summer runs it on a template set with the same MAJOR.MINOR and a patch at least this one.
+summer.games: Publish uploads this one file as a new Build.
+```
+
+Check that `server.pck` and your `config/` files are listed, and that the
+"Left N server-only files" count covers your `authority/` files. Every
+result message and every export error, with its fix, is in
+[export-errors.md](export-errors.md).
+
+## 4. Check before uploading
+
+Do all three. Each catches problems the export doesn't.
+
+**a. Local Play passes** (`multiplayer-testing`): every process has
+`script_errors` 0, there's no `cannot attach`, and your ready lines appear.
+
+**b. The source graph is clean.** Save this script **outside** the project,
+for example as `~/check_graph.gd`:
+
+```gdscript
+extends SceneTree
+
+func _init() -> void:
+	var analyzer := SummerWorldCompositionAnalyzer.new()
+	for profile in [SummerWorldCompositionAnalyzer.PROFILE_CLIENT, SummerWorldCompositionAnalyzer.PROFILE_AUTHORITY_ENGINE]:
+		var analysis := analyzer.analyze_project(ProjectSettings.globalize_path("res://"), "world.json", profile)
+		print(analysis.profile, " ok=", analysis.ok)
+		for diagnostic in analysis.diagnostics:
+			print("  ", diagnostic.code, " ", diagnostic.path, ": ", diagnostic.message, " ", diagnostic.dependency_path)
+	quit()
+```
+
+```sh
+<summer> --headless --path . --script ~/check_graph.gd
+```
+
+Both lines must say `ok=true`. `SUMMER_COMPOSITION_DOMAIN_LEAK` means a
+client file loads a server file; move the shared part into `network/`.
+`SUMMER_COMPOSITION_DYNAMIC_PATH_UNDECLARED` flags any call whose name ends
+in `load(` without a string literal inside. That includes
+`request.get_payload()`: read `request.payload` instead. For a file that
+really loads a computed path, add a
+`{ "from": "<file>", "to": "<loaded file>" }` entry to `dependencies` in
+`source-domains.json`.
+
+**c. Both packs load the way Summer loads them.** In a scratch folder
+outside the project:
+
+```sh
+P="$HOME/summer-probe"
+mkdir -p "$P/probe" "$P/out"
+printf 'config_version=5\n\n[application]\nconfig/name="Summer Native Upload Probe"\n\n[rendering]\nrenderer/rendering_method="gl_compatibility"\n' > "$P/probe/project.godot"
+unzip -o build/courtyard.summer.zip client.pck server.pck -d "$P/out"
+<summer> --headless --path "$P/probe" --summer-native-upload-probe "$P/out/client.pck" \
+  --summer-native-probe-scene res://client/main.tscn \
+  --summer-native-probe-composition res://network/composition.tres \
+  --summer-native-probe-output "$P/out/client-report.json"
+<summer> --headless --path "$P/probe" --summer-native-upload-probe "$P/out/server.pck" \
+  --summer-native-probe-scene res://authority/main.tscn \
+  --summer-native-probe-composition res://network/composition.tres \
+  --summer-native-probe-output "$P/out/server-report.json"
+```
+
+Paths must be absolute. Pass: both reports say `"sceneLoaded": true`, and
+their `compositionManifest` objects are identical. On failure the probe
+writes `rejection.json`; its codes are in [export-errors.md](export-errors.md).
+
+## 5. Upload the Build
+
+1. The game must exist in Summer Studio, and `gameId` in
+   `summer.build.json` and `GAME_ID` in `network/game.gd` must both be its
+   id.
+2. Open the game's Builds page: `summer_open` with target `game`,
+   `gameId` and section `builds`, or summerengine.com → Studio → your game →
+   Builds.
+3. Upload the `.zip` as a new Build. Summer checks it again: unknown fields,
+   queue rules, both packs, and the composition match.
+4. Release the Build to an environment. Its queues go live there, and
+   clients join them with `Summer.client.join(SummerJoinTarget.queue(...))`.
+   The code is the same as in Local Play.
+
+For a client-only fix to an existing Build, export to a `.pck` path instead
+of `.zip`. That writes `client.pck` alone.
+
+## Checklist
+
+- [ ] `summer.build.json`: `gameId`, `targetPlatforms`, `server.exportPreset`, every WorldDefinition selected by a queue.
+- [ ] `world.json`: every field from `multiplayer-project`, including `network_compositions` and `source_graph`.
+- [ ] Two presets: summer.games (platforms ticked, no encryption) and the Linux dedicated server named in `server.exportPreset`.
+- [ ] The export ends with `Publish uploads this one file as a new Build.`
+- [ ] The analyzer prints `ok=true` twice.
+- [ ] Both probes load their scene, with identical composition manifests.
+- [ ] Local Play passed with the same project.
+
+## Common mistakes
+
+| Don't | Do | Why |
+|---|---|---|
+| Export the summer.games preset as a dedicated server | Dedicated server only on the Linux preset | The client pack would lose its visuals |
+| Name the server preset differently from `server.exportPreset` | Copy the exact name | The export can't find it |
+| Encrypt the client pack | Leave encryption off | Summer's client templates can't decrypt packs |
+| Ship C#, `.gdextension` or native libraries in the client | GDScript only | Summer Games runs GDScript client packs only |
+| Skip the source graph | Keep `source-domains.json` complete | Without it the server code ships to players (export warns) |
+| Load an `authority/` file from client code | Move shared code into `network/` | The export stops: the client would load a missing file |
+| Upload after only exporting | Run Local Play, the analyzer and both probes first | Each catches what the others miss |
+| Export a patch | Export Project, or Export PCK/ZIP without Export As Patch | summer.games takes complete bundles or packs |

package/library/skills/multiplayer-publish/export-errors.md

@@ -0,0 +1,89 @@
+# summer.games export: messages, probe codes and errors
+
+Reference for `multiplayer-publish`. The messages are the summer.games
+exporter's own, word for word; `%s` stands for the value it names. Headless,
+the checks that run before exporting follow `Cannot export project with
+preset "summer.games" due to configuration errors:`, and server pack messages
+start with `Server pack (<preset>):`.
+
+## Result messages
+
+| Message | Meaning |
+| --- | --- |
+| `summer.games bundle for iOS, macOS with ETC2/ASTC textures: <path>` | The file to publish, and the platforms and texture formats in `client.pck`. |
+| `bundleSha256: sha256:…, bundleSize: …` | The identity of the file you upload. |
+| `Entries: summer-bundle.json, client.pck (… bytes), config/…, server.pck (… bytes)` | What the bundle holds. Check that `server.pck` and your `config/` files are listed. |
+| `clientSha256: sha256:…, clientSize: …` | The identity of `client.pck` inside the bundle. |
+| `Server: server.pck from preset "…", mainScene …` | The server pack and the scene it starts. `Server: none, the game has no host` means there is no `summer.build.json`. |
+| `mainScene: …` and `compositionPath: …` | What `client.pck` starts, and the composition both packs are checked against. |
+| `Exported by Summer X.Y.Z (engine …). Summer runs it on a template set with the same MAJOR.MINOR and a patch at least this one.` | The Summer version recorded in the bundle. |
+| `The Build also accepts: …` | Other client scene + composition pairs your WorldDefinitions name. Only the first is checked here. |
+| `The Build also declares …, which no client pack serves.` | `targetPlatforms` lists a platform, such as `web`, that the summer.games client pack does not cover. |
+| `Left N server-only files out of client.pck, as <graph> declares.` | The authority and debug files the source graph names stayed out of the client. They ship only in `server.pck`. |
+| `Publish uploads this one file as a new Build.` | Done. |
+
+Two warnings also matter: `summer.build.json declares <platform>, but this pack
+is not for it. …` (tick that platform), and `The pack starts <scene>, but the
+Build's mainScene is <scene>. Set application/run/main_scene, or its
+summer_client override, to the Build's scene.`
+
+## Upload probe rejection codes
+
+On failure the probe writes `rejection.json` next to the report instead:
+
+| `code` | Fix |
+| --- | --- |
+| `invalid_paths` | Use absolute pack and output paths, and `res://` `.tscn` and `.tres` paths. |
+| `pack_load_failed` | The pack file is missing or is not a pack. |
+| `scene_load_failed` | The scene, or a resource it loads, is not in that pack. Fix that preset's filters. |
+| `composition_load_failed` | The composition is missing from that pack, is not a `SummerNetworkComposition`, or has a script. |
+| `composition_invalid` | The composition fails its own validation, for example a state stream without a schema or audience policy. |
+| `manifest_invalid` | The composition's manifest is not `summer.network.composition.v1`. Probe with the Summer version you exported with. |
+
+## Export errors and fixes
+
+| Message | Fix |
+| --- | --- |
+| `summer.build.json must list the Build's targetPlatforms, for example ["ios", "macos", "windows"].` | Add a `targetPlatforms` array. |
+| `summer.build.json's targetPlatforms [%s] name no platform a client pack runs on: ios, macos or windows.` | List at least one of `ios`, `macos`, `windows`. |
+| `summer.build.json's executionMode is '%s'; it must be hosted or standalone.` | Use `hosted` for a multiplayer game. |
+| `A game without a host (executionMode standalone) names its client.entryPoint in summer.build.json: it is the pack's mainScene.` | For multiplayer, set `executionMode` to `hosted`. For a single-player game, delete `summer.build.json`. |
+| `summer.build.json lists an invalid WorldDefinition path: %s.` | Use a project-relative path with no `..`, backslash or leading `/`. |
+| `Cannot read %s.` or `%s is not a JSON object: %s (line %d).` | Fix that file's location or its JSON. |
+| `A hosted Build's pack starts a WorldDefinition's client_entry_point with one of its network_compositions, and no WorldDefinition in summer.build.json's runtime.worldDefinitions names both.` | Give a WorldDefinition both `client_entry_point` and `network_compositions`. |
+| `Tick the platforms the game supports.` | Tick iOS, macOS or Windows on the summer.games preset. |
+| `The project has no main scene for the pack to start.` | Set `client_entry_point` (or, without `summer.build.json`, the project's main scene). |
+| `The pack's mainScene %s does not exist in this project.` | Create the scene, or fix `client_entry_point`. |
+| `The pack's compositionPath %s does not exist in this project.` | Create the composition, or fix `network_compositions`. |
+| `iOS and macOS read ETC2/ASTC textures. Enable Import ETC2 ASTC in Project Settings > Rendering > Textures > VRAM Compression (Fix Import does this).` | Do that, or set `textures/vram_compression/import_etc2_astc=true`. |
+| `Windows reads S3TC/BPTC textures. Enable Import S3TC BPTC in Project Settings > Rendering > Textures > VRAM Compression (Fix Import does this).` | Do that, or set `textures/vram_compression/import_s3tc_bptc=true`. |
+| `Summer's client templates cannot decrypt a pack. Turn off encryption in this preset.` | Turn off encryption on the summer.games preset. |
+| `A client pack cannot be exported as a dedicated server. Use Export Mode "Export all resources" or a selection.` | Dedicated-server mode belongs on the server preset only. |
+| `%s is a symbolic link or junction, and the bundle carries only files inside the project. Replace the link with the file itself.` | Replace the link with a real file. |
+| `%s resolves to %s, outside the project. The bundle carries only files inside the project.` | Move the file into the project. |
+| `%s names an invalid %s path: %s. Name a file inside the project, without .. or backslashes.` | Fix that path in `summer.build.json` or the WorldDefinition. |
+| `%s names %s %s, which does not exist in this project.` | Create the file, or fix the path. |
+| `%s names %s %s: %s` | The named WorldDefinition, runtime descriptor or source graph is a link, is outside the project, or is not a JSON object. |
+| `summer.build.json names no server.exportPreset. A hosted game's bundle carries server.pck, exported with that preset (normally a Linux dedicated server).` | Add `"server": { "exportPreset": "<name>" }`. |
+| `summer.build.json names server preset "%s", which this project doesn't have. Its export presets are: %s.` | Create the preset, or fix the name. Names must match exactly. |
+| `summer.build.json's server preset "%s" exports for %s. server.pck needs the game's dedicated-server preset, normally Linux.` | Point `server.exportPreset` at a Linux preset, not at summer.games. |
+| `The Build's WorldDefinition names no headless_engine component entry_point, the scene server.pck starts.` | Add a `headless_engine` component with an `entry_point`. |
+| `The server pack's mainScene %s does not exist in this project.` | Create the server scene, or fix `entry_point`. |
+| `No source graph: server code may ship in client.pck. Name one in the WorldDefinition (source_graph) or exclude server files in the preset.` | A warning. Add `source_graph` to the WorldDefinition and write `source-domains.json`. |
+| `%s names source graph %s, which is not a valid summer.source-domain-graph.v1 (%s at %s: %s), so the export cannot tell which files to leave out of the client pack.` | Fix the field the message names. The rules are under "source-domains.json" in section 3. |
+| `The client pack keeps %s, which depends on %s, but the source graph leaves %s out of the client pack. Move what the client needs under a shared or client root, or remove the reference.` | A client or shared file loads a server-only file. Move the part both sides need into a `shared` path, or remove the reference. |
+| `The pack's %s %s is in the source graph's %s domain, which the client pack leaves out. Put the scenes and resources the client starts under a shared or client root.` | The client entry scene or the composition sits under an authority or debug root. Move it to a `client` or `shared` path. |
+| `Server preset "%s" is not a dedicated server export, so server.pck keeps the game's visuals. Set its Export Mode to Dedicated Server.` | A warning. Set the server preset's Export Mode to **Export as dedicated server**. |
+| `Summer's client templates run GDScript only, so the Platform rejects a pack with native code, C# or a .gdextension. Exclude these from the preset's resources: %s.` | Exclude the listed `.gdextension`, `.dll`, `.dylib`, `.so`, `.a`, `.wasm`, `.cs` and `.csproj` files from the summer.games preset. |
+| `The Platform starts the pack's mainScene with its compositionPath, but the preset's resource filters leave out %s.` | The summer.games preset's filters drop the client scene or the composition. Stop excluding it. |
+| `The server pack starts %s with %s, but the server preset's resource filters leave out %s.` | The server preset's filters drop the server scene or the composition. Stop excluding it. |
+| `The server preset "%s" could not export server.pck.` | Read the `Server pack (<preset>): …` messages before it. |
+| `The summer.games bundle is one .zip file, not %s. Export a .pck with Export PCK/ZIP for a client-only update.` | Export Project to a `.zip`. |
+| `The client pack is one .pck file, not %s. Export a .zip for the summer.games bundle.` | Use a `.pck` path for a client-only pack, or a `.zip` for the bundle. |
+| `summer.games takes a complete bundle or pack, not a patch. Export it with Export Project, or with Export PCK/ZIP without Export As Patch.` | Untick Export As Patch. |
+
+The exporter uses the source graph only to keep server files out of
+`client.pck` and to stop when the client needs one of them. It does not run
+the full source graph analyzer (step 4b of `multiplayer-publish`), the queue
+rules, or the other `summer.build.json` rules (`multiplayer-project`). Summer
+checks those when you upload, so follow them exactly.

package/library/skills/multiplayer-publish/resource.yaml

@@ -0,0 +1,28 @@
+id: skill/multiplayer-publish
+kind: skill
+version: 1.0.0
+summary: "Ship a hosted Summer multiplayer game: the summer.games bundle, server preset, pre-upload checks, and a new Build."
+use_when:
+  - "publishing a hosted Summer multiplayer game online so other players can join it"
+  - "making the summer.games bundle of a hosted game: client.pck, server.pck and the Linux server preset"
+  - "a summer.games export error mentions summer.build.json, WorldDefinitions, the server preset, the composition or the source graph"
+facets:
+  lifecycle:
+    - launch
+  domains:
+    - multiplayer
+    - deployment
+  modalities:
+    - project
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer
+    - skill/multiplayer-project
+    - skill/multiplayer-testing
+source: official
+license: MIT
+status: preview
+recommended: false