summer-engine 3.1.0 → 3.2.0

package/library/skills/summer-world-saves/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: summer-world-saves
+description: "Keep a persistent Summer World between restarts: checkpoint saves, restore before join, the final save."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: multiplayer-and-networking
+user-invocable: true
+allowed-tools: Read Grep Edit Write summer_get_script_errors summer_project_setting summer_play summer_stop summer_get_diagnostics
+paths: ["**/*.gd", "world.json", "summer.build.json"]
+---
+
+# /summer-world-saves — a World that is still there tomorrow
+
+> **Preview.**
+> - Verified in Local Play: restore of a new World, commit and receipt.
+> - **Not** verified: restoring after a real restart. Local Play keeps saves in memory only, so only hosted play proves it.
+> - Persistent Worlds need hosting support for your game. Check that it is available before you promise it to players.
+
+## Overview
+
+Most Summer Worlds are **match-scoped**: the match ends and its state is gone.
+A **persistent** World is a place players come back to, such as a shared
+base, a farm or a realm. Its authority can stop for maintenance, a crash or
+a move. A new authority then restores the World from its last save.
+
+| Keep | Use |
+|---|---|
+| What belongs to the place: built walls, chests, the coins left on the ground | **World save** (this skill) |
+| What belongs to a player: their coins, unlocks, level | **Player data** (`skill/summer-player-data`) |
+
+The engine never serializes nodes for you. The game decides what one save
+holds. It must be **one consistent cut**: if an item moves from a chest into
+an inventory, both sides go in the same save.
+
+This skill extends the Courtyard game from `skill/multiplayer-state`: its
+`match_doc` (the coins still on the ground, and the scoreboard) becomes the
+World's saved state.
+
+## Steps
+
+### 1. Declare a persistent World
+
+In `world.json`, change these fields and keep everything else:
+
+```json
+{
+  "lifetime": "persistent",
+  "settlement": { "mode": "none" },
+  "persistence": {
+    "mode": "checkpoint",
+    "recovery_point_seconds": 60,
+    "snapshot_schemas": ["courtyard.v1"],
+    "migration_ids": []
+  },
+  "lifecycle": {
+    "reconnect_seconds": 30,
+    "drain_seconds": 120,
+    "transfer": "disabled",
+    "completion_owner": "world"
+  }
+}
+```
+
+- `recovery_point_seconds` (1 to 3600) is the most play you accept losing in a crash. Commit at least that often.
+- `snapshot_schemas`: exactly one name for your save format in this release. There are no migrations.
+- `drain_seconds`: 60 to 300.
+- A save holds at most **16 MiB**.
+
+### 2. Restore before anyone joins
+
+Restore runs right after `Summer.initialize`, **before** waiting for
+`binding_ready`. Players are admitted only after `finish_restore` succeeds,
+so restore is part of becoming ready. Add to `authority/main.gd`:
+
+```gdscript
+const SAVE_SCHEMA := "courtyard.v1"      # the WorldDefinition's snapshot_schemas entry
+const CHECKPOINT_SECONDS := 30.0         # at most the WorldDefinition's recovery_point_seconds
+var saves: SummerAuthorityWorld          # Summer.authority.world: this World's save slot
+var save_revision := "0"
+var save_sequence := 0
+var save_op: SummerWorldSaveOperation    # the commit in flight, if any
+var restored := false
+var world_dirty := false
+var acknowledged: Array[String] = []
+```
+
+In `_ready()`, between `Summer.initialize` and the `binding_ready` wait:
+
+```gdscript
+	# Restore before waiting for binding_ready: players are admitted only
+	# after the World confirms its restore.
+	if not await _restore_world():
+		push_error("could not restore this World; not starting")
+		return
+	var checkpoints := Timer.new()
+	checkpoints.wait_time = CHECKPOINT_SECONDS
+	checkpoints.timeout.connect(_on_checkpoint_timer)
+	add_child(checkpoints)
+	checkpoints.start()
+	if not world.is_ready():
+		await world.binding_ready
+```
+
+Create the shared `match` State group **after** the restore, so it starts
+from the restored document.
+
+```gdscript
+## Loads the World's last checkpoint, or starts fresh when it has none.
+func _restore_world() -> bool:
+	saves = Summer.authority.world
+	saves.save_requested.connect(_on_save_requested)
+	# Local Play binds the World on the frame after initialize; let that
+	# frame pass before loading.
+	await get_tree().process_frame
+	var loading := saves.load_save()
+	var result: SummerResult = await loading.get_result_or_completed_signal()
+	if not result.ok:
+		return false   # never treat a failed load as an empty World
+	var saved := loading.get_save()
+	if saved.has_save():
+		var doc: Variant = JSON.parse_string(saved.get_data().get_string_from_utf8())
+		if not doc is Dictionary or not doc.has_all(["coins", "scores"]):
+			return false
+		match_doc = doc
+	save_revision = saved.get_revision()
+	save_sequence = int(saved.get_state_sequence())
+	result = await saves.finish_restore(saved).get_result_or_completed_signal()
+	if not result.ok:
+		return false
+	restored = true
+	# A save request may have arrived before this point.
+	var pending := saves.get_snapshot_request_id()
+	if not pending.is_empty():
+		_on_save_requested(pending, saves.get_snapshot_deadline_unix_msec())
+	return true
+```
+
+**A failed or corrupt load must stop the World.** Starting fresh instead
+would overwrite the players' place with an empty one on the next save.
+
+### 3. Checkpoint while playing
+
+Mark the World dirty wherever saved state changes. Here that is after
+`match_group.reset(...)` in `_collect`:
+
+```gdscript
+	world_dirty = true
+```
+
+```gdscript
+func _on_checkpoint_timer() -> void:
+	if world_dirty:
+		_checkpoint()
+
+
+## Commits one consistent copy of the World. One save at a time; a retry
+## resends exactly the same five arguments.
+func _checkpoint() -> SummerWorldSaveReceipt:
+	while save_op != null:
+		await save_op.get_result_or_completed_signal()
+	world_dirty = false
+	save_sequence += 1
+	var sequence := str(save_sequence)
+	var save_id := "cut-" + sequence
+	var bytes := JSON.stringify(match_doc).to_utf8_buffer()
+	var expected := save_revision
+	for attempt in 3:
+		save_op = saves.commit_save(expected, save_id, SAVE_SCHEMA, bytes, sequence)
+		var result: SummerResult = await save_op.get_result_or_completed_signal()
+		var receipt := save_op.get_receipt()
+		save_op = null
+		if result.ok:
+			save_revision = receipt.get_revision()
+			return receipt
+		if not result.retryable:
+			# Conflict, corrupt, incompatible or fenced: stop, never overwrite.
+			push_error("world save failed: %s" % result.code)
+			break
+	world_dirty = true
+	return null
+```
+
+The rules behind it:
+
+- **One save at a time.** `commit_save` takes the revision you expect to replace, so two overlapping saves would conflict.
+- **Capture once, retry exactly.**
+  - On retryable `world_save_unavailable`, resend the same expected revision, `save_id`, schema, bytes and sequence.
+  - A lost reply may hide a commit that already succeeded.
+- **The sequence only grows.** It continues from the restored save's `state_sequence`, so `save_id`s never repeat across restarts.
+- **Stop on non-retryable codes.** `world_save_conflict`, `world_save_corrupt`, `world_save_incompatible`, `world_restore_required` and `runtime_fenced` mean this authority must not keep writing.
+
+### 4. Answer the final save request
+
+Before Summer stops, restarts or moves the World, it emits `save_requested`
+with a deadline. Commit a fresh cut, then acknowledge it with that receipt:
+
+```gdscript
+## The platform asks for a final save before it stops or moves this World.
+## Commit a fresh cut, then acknowledge it. Never wait for timers or frames
+## here: gameplay is frozen while the final save runs.
+func _on_save_requested(request_id: String, _deadline_unix_msec: int) -> void:
+	if not restored or request_id in acknowledged:
+		return
+	acknowledged.append(request_id)
+	var receipt := await _checkpoint()
+	if receipt == null:
+		return   # never acknowledge a save that did not commit
+	await saves.finish_snapshot(request_id, receipt).get_result_or_completed_signal()
+	# This runtime may stop right here. Put nothing important after it.
+```
+
+- During the final save, scene processing and timers are frozen; only save operations complete. Never `await` a timer or a frame in this path.
+- A crash delivers no request, so periodic checkpoints are still required.
+- For a planned shutdown, `saves.shutdown_notice_changed` gives advance notice; a `null` notice means it was cancelled. Use it to warn players ("Server restarts in 5 minutes") and to finish events that are in progress.
+
+### 5. Bring players back to the same World
+
+A player returns to a persistent World by its id:
+
+```gdscript
+var join := Summer.client.join(SummerJoinTarget.world(world_id))
+var joined: SummerResult = await join.get_result_or_completed_signal()
+```
+
+Read the id with `Summer.get_world().world_id` after the first join, and keep
+it, for example in the player's public player data. A sleeping World wakes
+and restores before the player is admitted.
+
+Never call `saves.complete()` to "save and stop". It ends the World
+permanently.
+
+### 6. Test in Local Play
+
+Local Play runs a persistent World with an **in-memory** save store:
+
+- Every run starts with no save, so `has_save()` is false.
+- Commits succeed and return receipts.
+- Nothing survives the run.
+
+```
+summer_project_setting name="summer/local_play/players" value=2
+summer_play
+summer_get_diagnostics
+summer_stop
+```
+
+Add a marker after restore, such as `print("WORLD_RESTORED has_save=", saved.has_save())`,
+and one after each successful commit. Then check:
+
+- the restore marker appears before any player joins;
+- a checkpoint commits after state changes;
+- there are no `world_save_*` errors.
+
+Restoring after a real restart can only be proven hosted.
+
+## Checklist
+
+- [ ] `world.json` declares `lifetime: persistent` and a `checkpoint` persistence block with one schema.
+- [ ] The authority restores before awaiting `binding_ready`, and a failed load stops it.
+- [ ] Checkpoints run at least every `recovery_point_seconds` while the World changes.
+- [ ] Only one `commit_save` is in flight; retries reuse all five arguments.
+- [ ] `save_requested` commits a fresh cut, then calls `finish_snapshot` with that receipt, without awaiting timers.
+- [ ] Player progress lives in player data, not in the World save.
+
+## Common mistakes
+
+| Don't | Do | Why |
+|---|---|---|
+| Await `binding_ready` before restoring | Restore first, then await `binding_ready` | Readiness waits for the restore, so the World never becomes ready |
+| Call `load_save()` in the same frame as `initialize` | Await one `process_frame` first | Local Play binds the World a frame later; the load fails with `world_save_unavailable` ("no active SummerNetworkWorld binding") |
+| Start an empty World when the load fails | Stop and report | The next checkpoint would overwrite the real World |
+| Save only on shutdown | Checkpoint every `recovery_point_seconds` | Crashes deliver no save request |
+| Start a second save while one is pending | Serialize saves | Both expect the same revision; one conflicts |
+| Recapture or mint a new `save_id` after a lost reply | Retry the same five arguments | The first commit may have succeeded |
+| Await a timer inside the final save | Await only save operations | Timers are frozen during final saving |
+| Put player progress in the World save | Player data | It must follow the player to other Worlds |
+| Call `complete()` to sleep the World | Let the platform stop it after the final save | `complete()` ends the World forever |
+
+## See also
+
+- `skill/summer-player-data` — progress that follows a player
+- `skill/multiplayer-state` — the shared document this skill saves
+- `skill/multiplayer-project` — `world.json` and the authority scene
+- `skill/multiplayer-testing` — Local Play runs and markers

package/library/skills/summer-world-saves/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/summer-world-saves
+kind: skill
+version: 1.0.0
+summary: "Keep a persistent Summer World between restarts: checkpoint saves, restore before join, the final save."
+use_when:
+  - "building a persistent World, shared base, farm or realm in a Summer game that must survive server restarts"
+  - "saving and restoring World state with commit_save, load_save, finish_restore, save_requested or finish_snapshot"
+  - "deciding whether progress belongs in a World save or in player data"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - multiplayer
+    - scripting
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer
+    - skill/multiplayer-project
+    - skill/multiplayer-state
+    - skill/summer-player-data
+    - skill/summer-match-results
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/text-to-motion/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: text-to-motion
+description: "Custom 2-second animation clips from text prompts on any of the user's own rigged models — humanoids, animals, creatures, cartoon plants, props."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: animation
+user-invocable: false
+allowed-tools: Read summer_list_my_assets summer_generate_motion summer_check_job summer_get_asset summer_import_asset_by_id
+---
+
+# Text to Motion
+
+Summer-hosted text-to-motion turns a text prompt into a 2-second (60 frames) skeletal
+clip for the user's **own** rigged model. One model covers every skeleton with 5-70 bones:
+humanoids, animals, creatures, cartoon plants, turrets, props.
+
+The tool is `summer_generate_motion` with `backend: "text-to-motion"`. It returns a
+`jobId`; poll `summer_check_job`. The finished job's `result.assets` lists one `animation`
+asset per prompt x take (`id`, `fileUrl`, `animationName`, `prompt`, `take`); each is a GLB
+of the whole model carrying one animation named after its prompt.
+
+Trigger on: "make the flower nod", "animate my creature", "custom animation from text",
+"a bow / shrug / wave with the right arm", "animate this uploaded rig", "the library
+doesn't have that move", any animation request for a non-humanoid rig.
+
+## Choose the right route
+
+| Situation | Use |
+| --- | --- |
+| Summer-rigged humanoid needs idle / walk / run / jump / attack | `generate-motion` (`backend: "meshy-library"`) |
+| Custom action, specific arm or side, emotional gesture | this skill |
+| Non-humanoid rig: flower, animal, creature, turret, prop | this skill |
+| Uploaded or custom-rigged GLB/FBX | this skill |
+| Existing clips onto a second character | `retarget` |
+| Unrigged mesh | rig first (`rigging-for-text-motion.md`; humanoids via `character-model`), then this skill |
+
+## The order
+
+1. **Confirm the rig.** The asset must be the user's own `3d_model` GLB/FBX with one
+   skinned armature and 5-70 bones (`summer_list_my_assets` / `summer_get_asset`). If it
+   is unrigged or has odd bone names, read `rigging-for-text-motion.md` in this directory.
+2. **Agree the clip list and cost.** Each prompt x take is one billed clip. Show the list
+   and the estimated cost and wait for the user's OK before submitting.
+3. **Submit once.** Up to 8 prompts per call, `takes` 1-4. For rooted characters pass
+   `lockJoints` with the base bones:
+
+   ```
+   summer_generate_motion(
+     rigAssetId: "<id>",
+     backend: "text-to-motion",
+     prompts: ["nods happily", "waves hello with the right leaf"],
+     lockJoints: ["Hips", "Spine"],   // rooted flower; omit for characters that move
+     cfgScale: 5,                     // default 3; 5 for clearer gestures on stylized rigs
+     wait: false
+   )
+   ```
+
+   Pass a stable `idempotencyKey` if you might retry the same request. Prompt writing and
+   every control: `prompts-and-controls.md` in this directory.
+4. **Poll to completion.** `summer_check_job(jobId)`. A job takes about 1-2 minutes. Do not
+   resubmit while it runs. (With the default `wait: true` the tool polls for you.)
+5. **Review, then import.** Import the chosen clip assets with
+   `summer_import_asset_by_id(assetId, parent, scenePath)`. Offer to regenerate weak takes
+   with a rephrased prompt or a higher `cfgScale`; keep the good ones.
+
+## Hard rules
+
+- **Only the user's own rigged models.** Never animate assets owned by someone else.
+- **Clips are 2 seconds and not guaranteed to loop.** For longer actions chain several
+  prompts ("raises both arms", "holds the pose", "lowers the arms") or loop a good take.
+- **Locomotion moves the root.** Walk/run/jump clips may translate the character; gameplay
+  code owns movement, so strip or ignore root translation for in-place controllers.
+- **Never lock joints on characters that walk or jump**; the root would be pinned.
+- **Report failures with their code.** Job failures starting `text_motion:` (no skinned
+  armature, too many or too few joints, multiple armatures, unknown lock joint) are input
+  problems and the charge is refunded. Fix the rig or the request; do not retry unchanged.
+- **`backend_unavailable` means text-to-motion is not enabled on this server yet.** Fall
+  back to `generate-motion` (meshy-library) for humanoid clips and say so; do not retry.
+- **Do not promise facial animation, finger detail or lip sync.** The model animates the
+  skeleton only; blendshapes stay untouched (`facial-and-lipsync` covers faces).
+
+## Request errors
+
+| Code | Meaning | Do |
+| --- | --- | --- |
+| `backend_unavailable` | Server flag off | Use `generate-motion`; do not retry |
+| `prompt_required` | No prompt | Pass `prompt` or `prompts` (1-8, each 1-300 chars) |
+| `invalid_takes` | `takes` outside 1-4 | Fix and resubmit |
+| `invalid_cfg_scale` | `cfgScale` outside 1.5-8 | Fix and resubmit |
+| `invalid_lock_joints` | Bone names wrong | Use bone names that exist in the rig |
+| `rig_asset_not_found` | Not the caller's asset | Find the user's own asset id |
+| `rig_asset_invalid` | Not a rigged GLB/FBX `3d_model` | Rig it first |
+| `insufficient_credits` (402) | Not enough credits | Fewer prompts/takes, or the user tops up |
+
+## Do not stop early
+
+Done means the chosen clips are imported and playing on the model in the scene. For a
+playable character continue with `character-animation-wiring`; for state machines,
+`animation-tree`.

package/library/skills/text-to-motion/prompts-and-controls.md

@@ -0,0 +1,34 @@
+# Prompts and controls
+
+## Prompts
+
+- Describe one action as a verb phrase: "waves hello with the right arm", "nods happily",
+  "bows politely", "jumps up and down excitedly", "looks around curiously".
+  The service normalizes to its training style ("An object waves ...").
+- Name the side and body part for asymmetric actions ("with the right arm", "raises the
+  left leaf").
+- Keep it to one action per clip; 2 seconds fits one gesture, not a sequence.
+- Style words that map to motion work ("happily", "slowly", "tiredly"); story or
+  appearance words do not.
+
+## Controls (`summer_generate_motion`, `backend: "text-to-motion"`)
+
+| Field | Default | Use |
+| --- | --- | --- |
+| `prompt` / `prompts` | - | One action, or 1-8 actions (each 1-300 chars); one clip each. Pass one of the two, not both |
+| `takes` | 1 | 1-4; 2-3 when choosing a hero clip. Every take is billed |
+| `cfgScale` | 3 | 1.5-8; 5 for bigger, clearer gestures on stylized rigs; above 6 gets unstable |
+| `lockJoints` | none | Base bones of rooted characters (plants, turrets, statues), e.g. `["Hips","Spine"]` |
+| `idempotencyKey` | none | Stable key so a retried request is not billed twice |
+| `wait` | true | `false` returns the `jobId` at once; poll `summer_check_job` |
+
+Clip count = prompts x takes; each clip is billed. The queued response reports
+`clipCount` and `estimatedCost`.
+
+## Judging results
+
+- Good: the named body part does the action, the base stays put, no mesh tearing.
+- Tipping over or collapsing on rooted rigs: add or extend `lockJoints`.
+- Barely moving: rephrase with a clearer verb, raise `cfgScale` to 5, or rename bones to
+  human names (see `rigging-for-text-motion.md`).
+- Mesh warping at a joint: a weighting problem in the rig, not the motion; fix the rig.

package/library/skills/text-to-motion/resource.yaml

@@ -0,0 +1,41 @@
+id: skill/text-to-motion
+kind: skill
+version: 1.0.0
+summary: "Custom 2-second animation clips from text prompts on any of the user's own rigged models — humanoids, animals, creatures, cartoon plants, props."
+use_when:
+  - a custom action the curated motion library lacks — nod, bow, shrug, wave with a specific arm, an emotional gesture
+  - animating a non-humanoid rig — a talking flower, animal, creature, turret or prop
+  - adding clips to an uploaded or custom-rigged GLB/FBX model
+  - '"make the flower nod" / "animate my creature from a text description"'
+do_not_use_when:
+  - a Summer-rigged humanoid needs standard idle/walk/run/jump/attack clips — generate-motion (meshy-library)
+  - the model is not rigged yet — rig it first
+  - facial animation, finger detail or lip sync — facial-and-lipsync
+facets:
+  lifecycle:
+    - build
+  domains:
+    - animation
+    - generate
+    - 3d
+  modalities:
+    - animation
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/generate-motion
+    - tool/check-job
+    - tool/import-asset-by-id
+  skills:
+    - skill/generate-motion
+    - skill/character-model
+    - skill/retarget
+    - skill/asset-strategy
+source: official
+license: MIT
+status: preview
+recommended: false
+aliases:
+  - text-motion
+  - animate-from-text

package/library/skills/text-to-motion/rigging-for-text-motion.md

@@ -0,0 +1,54 @@
+# Rigging for text-to-motion
+
+The motion model reads the skeleton's rest pose, hierarchy **and bone names**. Names carry
+meaning: a bone called `LeftArm` borrows everything the model learned from human arms.
+Rigs named like a human skeleton therefore animate far better than freeform names, even
+on non-humans. Measured on cartoon flowers (2026-09-29): with plant names (`Stem1`,
+`LeafL1`) most prompts barely moved; the same rig with human names nodded, bowed,
+gestured and looked around on cue.
+
+## Limits the service enforces
+
+- One skinned armature driving the mesh; GLB or FBX; at most 100 MB.
+- 5-70 bones total (helper, twist and finger bones count). Remove extras before submitting.
+- Existing animations are ignored; the service adds its own reference clip.
+- Facing is detected from a left/right limb pair (`RightUpLeg`/`LeftUpLeg`, else arms).
+
+## Humanoids
+
+Meshy, Mixamo-style (`mixamorig:*`) and Summer auto-rig skeletons work as-is.
+Summer character packages (`character-model`) can use text-to-motion for extra custom
+clips; keep the package's canonical idle/walk/run/jump from `generate-motion`.
+
+## Non-humanoids: map the body plan to human bone names
+
+| Body part | Bone names |
+| --- | --- |
+| Base / pelvis / root of a plant | `Hips` |
+| Torso, stem, trunk, neck chain (bottom to top) | `Spine`, `Spine1`, `Spine2`, `Neck` |
+| Head, bloom, face | `Head`, then `HeadTop_End` |
+| Arms, leaves, fins, wings | `LeftShoulder` > `LeftArm` > `LeftForeArm` > `LeftHand` (and `Right*`) |
+| Legs, roots, lower fins | `LeftUpLeg` > `LeftLeg` > `LeftFoot` (and `Right*`) |
+| Petals, ears, antennae, tails | own names (`Petal0`, `Tail1`), parented to the nearest body bone |
+
+## Talking-flower recipe (validated)
+
+- Stem = `Hips` > `Spine` > `Spine1` > `Spine2` > `Neck` > `Head`; petals parented to `Head`.
+- Leaf-arms on the upper-middle stem, parented to `Spine1`/`Spine2`, pointing sideways.
+- **Keep the arms clear of the petals and face.** Hands that touch the lower petals get
+  their weights mixed and the mesh warps when the arm moves; arms lower on the stem
+  deform cleanly.
+- Submit with `lockJoints: ["Hips","Spine"]` so the flower stays planted, and
+  `cfgScale: 5` for readable gestures.
+
+## Rigging an unrigged mesh
+
+- Humanoid: the Summer auto-rig (`character-model`, `summer_generate_3d` with
+  `options.rig: true`).
+- Other body plans: rig in the user's own Blender (`fabricating-assets`) or offline
+  (`skintokens-auto-rigging`), using the human bone names above where the body plan allows
+  (stem as spine, leaves as arms).
+
+Check the weights around every joint that will move before animating. A rig with bad
+weights produces bad clips regardless of the motion; mesh warping at a joint is a rig
+problem, not a motion problem.

package/library/skills/tileable-texture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tileable-texture
-description: Use when generating a seamless tileable texture for walls, floors, terrain, ceilings — square tile that repeats cleanly on all four edges. Wires onto PlaneMesh / CSGBox3D / MeshInstance3D as a StandardMaterial3D albedo. Trigger on "tileable texture", "seamless texture", "wall texture", "floor texture", "ground texture", "terrain texture", "tiled material".
+description: "Generate a seamless tileable texture for walls, floors, or terrain — repeats cleanly on all four edges, wired as a StandardMaterial3D albedo."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

package/library/skills/trailer-shot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trailer-shot
-description: Use when generating marketing or trailer footage — slow-mo combat, dramatic establishing shots, hero beats, splash screens, pitch-deck B-roll. Optimizes for maximum visual punch in 5-10 seconds. Trigger on "trailer", "marketing footage", "Steam capsule video", "splash screen", "hero shot", "pitch deck clip", "promo clip", "money shot", "B-roll".
+description: "Generate marketing or trailer footage — slow-mo combat, establishing shots, hero beats, splash screens, pitch-deck B-roll — max punch in 5-10 seconds."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: video

package/library/skills/tune-performance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tune-performance
-description: Use when the user reports the game is slow, drops framerate, stutters, takes forever to start, or runs poorly on specific hardware. Profiles the running game via summer_get_diagnostics, identifies hotspots (rendering / physics / scripting), and proposes specific fixes with before/after metric expectations. Trigger on "slow", "lag", "fps drop", "stuttering", "performance", "optimize", "profile", "framerate".
+description: "Profile a slow game via summer_get_diagnostics, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: performance

package/library/skills/ui-basics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ui-basics
-description: "Use when building Summer Engine UI: HUDs, main menus, pause menus, health bars, progress bars, dialogue boxes, or any Control-node tree. Covers anchors, containers (VBox/HBox/Margin), responsive layout, and theme versus inline styling. Trigger on \"UI\", \"HUD\", \"menu\", \"health bar\", \"Control\", \"anchors\", \"VBoxContainer\", \"main menu\", \"pause menu\"."
+description: "Build Summer Engine UI — HUDs, menus, health bars, dialogue boxes, Control trees — anchors, containers, responsive layout, theme vs inline styling."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: ui-and-ux
@@ -130,6 +130,15 @@ For UI that scales with window size:
 
 For simple cases, CenterContainer + fixed-size children works. For complex layouts, a Theme resource or script may be needed.
 
+## Text, fonts and symbols
+
+The default font only has letters, digits and common punctuation. Anything else renders as an empty box with a hex code in it (for example a box reading `25 B2` for ▲, or `25 C0` for ◀), and on the web there is no system font to fall back to.
+
+- Never put emoji or Unicode symbols in Label, Button or RichTextLabel text: arrows (▲ ▼ ◀ ▶ ← →), stars, hearts, check marks, music notes, keycap symbols. Write the words instead ("Up", "Next"), or show an icon.
+- Draw icons as nodes: a TextureRect with a small texture, a Polygon2D triangle for arrows, or a `_draw()` shape. Key prompts are a rounded StyleBoxFlat panel with the key's letter in it.
+- If the game really needs symbols or another script (Japanese, Arabic, Cyrillic), add a font file that contains them: import a TTF/OTF that covers the characters, set it as the theme's default font, and add it to the fallbacks of any other font you use.
+- After adding text, take one screenshot and look for boxes with hex codes; fix any you find before moving on.
+
 ## Fallback (no MCP — edit `.tscn` directly)
 
 If Summer MCP isn't connected, write the menu hierarchy by hand:

package/library/skills/ui-graphics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ui-graphics
-description: Use when generating UI elements — icons, buttons, panels, frames, HUD widgets, badges. Flat-design, transparent-background, game-UI style. Wires the result via TextureRect / NinePatchRect / AtlasTexture. Trigger on "UI icon", "button graphic", "HUD element", "panel frame", "menu background", "inventory slot", "ability icon", "badge".
+description: "Generate game-UI elements — icons, buttons, panels, frames, HUD widgets, badges — flat design, transparent background, wired via TextureRect/NinePatchRect."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

package/library/skills/use-widget-asset/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: use-widget-asset
-description: Use when consuming a widget slice (panel, button, slider, progress bar, or toggle pair) from a `create-asset-sheet` pack in a Summer Engine scene. The pack's metadata.sliceMeta carries 9-slice margins, fill rects, and on/off pair links per slice. This skill explains how to wire those into NinePatchRect, TextureProgressBar, or TextureRect so the asset behaves like a real UI control instead of a static texture.
+description: "Wire a widget slice from a create-asset-sheet pack (panel, button, slider, bar, toggle) into NinePatchRect, TextureProgressBar, or TextureRect via sliceMeta."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

package/library/skills/using-summer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-summer
-description: Use when starting any conversation in a Summer Engine project — establishes how to find and use Summer skills and the summer-engine MCP, requiring Skill tool invocation before ANY response including clarifying questions.
+description: "Session bootstrap for Summer projects — establishes how to find and use Summer skills and the summer-engine MCP before any response."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
 category: _meta
@@ -111,7 +111,7 @@ When multiple Summer skills could apply, run them in this order:
 
 1. **Process skills first** — `brainstorm-game`, `debug`, `play`. These determine HOW to approach the task.
 2. **Discipline skills second** — `gdscript-patterns`, `scene-composition`, `art-direction`, `audio-direction`. These shape the content.
-3. **Build skills third** — `fps-controller`, `design-mechanic`, `design-level`, `setup-multiplayer`. These produce the artifacts.
+3. **Build skills third** — `fps-controller`, `design-mechanic`, `design-level`, `multiplayer`. These produce the artifacts.
 
 > "I want to make a game" → `brainstorm-game` first, then build skills.
 > "Fix this crash" → `debug` first, then domain skills.

package/library/skills/using-summer/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/using-summer
 kind: skill
-version: 1.0.4
+version: 1.0.5
 summary: Session bootstrap for Summer projects — establishes how to find and use Summer skills and the summer-engine MCP before any response.
 use_when:
   - starting any conversation in a Summer Engine project
@@ -25,7 +25,7 @@ related:
     - skill/debug
     - skill/design-mechanic
     - skill/design-level
-    - skill/setup-multiplayer
+    - skill/multiplayer
     - skill/art-direction
     - skill/brainstorm-game
     - skill/play

package/library/skills/vehicle-model/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vehicle-model
-description: Use when generating a hard-surface vehicle — car, motorcycle, spaceship, hover bike, boat, mech, tank, helicopter. Static mesh, optional secondary detail-texture pass, wired as Vehicle3D (player-driven) or MeshInstance3D (background). Trigger on "make a car", "spaceship model", "generate a mech", "I need a vehicle", "hover bike", "tank model", "racing car".
+description: "Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as Vehicle3D or MeshInstance3D."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets