@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/craft-game-floors/references/scene-lighting.md

@@ -0,0 +1,52 @@
+# Scene Lighting
+
+> Craft reference for the `craft-game-floors` skill. **Load:** immediately after the first scene exists in any 3D build — or on first touching a 3D scene still lit by the template's defaults. Post-effect mechanics live in `urp-postprocessing` — this reference says *which* values; that skill says *how*. Sibling links resolve to the skill directory. Confirm engine behavior against the linked documentation for the installed version before acting on it.
+
+## The opinion
+
+Light tells the scene's story. The un-opinionated default — one white directional at noon over flat gray ambient — is why agent-built games look like documents. Every 3D scene built under these floors (the paved default — and any scene this skill touches) gets the baseline below before gameplay authoring continues. The values in this reference supersede the project baseline's and `urp-postprocessing`'s own starting points; that skill remains the mechanics and debugging reference for the Volume framework itself.
+
+## The key light
+
+- One directional, **warm-tinted from the palette** ([art-direction](art-direction.md); toward `#FFF2DC`, never pure white), intensity ~1.1–1.3.
+- Elevation 35–50°, azimuth angled across the play axis so faces get light/shadow variation (never straight down, never behind camera).
+- Soft shadows on; shadow distance sized to the playable space, not the pipeline default (URP ships 50 m; Built-in 150 m).
+
+## The ambient answer (the half everyone skips)
+
+Environment lighting → **Gradient**: sky = cool tint from the palette, equator = neutral mid, ground = dark warm. This is what keeps shadow sides alive instead of dead gray. For toon styles the ambient is doing the "bounce" the ramp can't.
+
+## The global Volume (via `urp-postprocessing`)
+
+One global [Volume](https://docs.unity.com/en-us/engine/<VERSION>/manual/post-processing-and-full-screen-effects/urp/volumes-landing-page.md) asset, always — and **first, check the camera**: a script-created camera's `UniversalAdditionalCameraData` defaults `renderPostProcessing` to false (template cameras ship with it on), and the whole Volume silently does nothing until it is enabled.
+
+**[Bloom](https://docs.unity.com/en-us/engine/<VERSION>/manual/post-processing-and-full-screen-effects/urp/effect-list/bloom.md) needs HDR here** — with SDR's 0–1 colors the threshold values below never fire (the skill's own trap note; the Bloom page doesn't state it). Confirm HDR on the active URP asset (and not overridden off on the camera); a build that must stay SDR runs Threshold 0.9 with Intensity halved.
+
+Baseline starting values:
+
+| Override | Start | Why |
+|---|---|---|
+| Tonemapping | ACES (Neutral for flat toon looks) | free depth and rolloff |
+| Bloom | intensity 0.25–0.4, threshold 1.1 (HDR on) | glow on accents/pickups only |
+| Vignette | 0.2–0.25 | frames the action |
+| Color Adjustments | saturation +8, contrast +5 | counters engine-default flatness |
+
+Interiors: consider palette-tinted fog for depth. Skip AO on toon styles (fights the bands); consider it on stylized-lit ones.
+
+## Per-mood variants (worked)
+
+Starting points keyed to the worked bibles in [art-direction](art-direction.md) — tune from the matching row, never from zero.
+
+| Mood | Key light | Tonemapping | Bloom | Vignette | Color Adjustments | Extras |
+|---|---|---|---|---|---|---|
+| Cozy interior | warm `#FFE8C8`, 1.15, elev 38° | ACES | 0.3 @ 1.1 | 0.25 | sat +8, contrast +5 | White Balance temp +10; faint palette-tinted fog |
+| Bright arcade | cool dim `#CFE6FF`, 0.6, elev 60° | Neutral | 0.8 @ 0.9 | 0.18 | sat +15, contrast +10 | emissive materials carry the light; ambient from the bounds color |
+| Moody sci-fi | cool hard `#BFD2E6`, 1.3, elev 55° | ACES | 0.35 @ 1.2 | 0.3 | sat −5, contrast +12 | White Balance temp −8; fog tinted from the shadow value |
+
+## Verify
+
+**This verify is URP-typed** — establish the pipeline first (`GraphicsSettings.currentRenderPipeline`; the router's mid-flow check does this). On Built-in or HDRP, apply this file's light-story opinions (key, ambient, mood) but skip the URP checks and name the pipeline gap in the report — `UniversalAdditionalCameraData` and the URP Volume types don't exist there, and `urp-postprocessing` stops by design when URP is inactive. Under URP, machine checks first (via `unity-cli` eval): the camera's `UniversalAdditionalCameraData.renderPostProcessing` reads true, and the global Volume's profile reports all four overrides present and active. Then capture with the Volume enabled and disabled and diff the two PNGs — a mean per-channel delta that rounds to zero means the settings are too timid; raise until the diff is unmistakable, then pull back one notch. Keep each tuning eval short: a timed-out `eval` may still have executed, so long sweeps go through `run_script` instead.
+
+## Expansion scope
+
+Baked GI / light-probe workflows, time-of-day rigs, per-scene Volume blending, mobile/web budget variants, HDRP parity.

package/skills/craft-game-floors/references/toon-shading.md

@@ -0,0 +1,34 @@
+# Toon Shading
+
+> Craft reference for the `craft-game-floors` skill. **Load:** when the art bible picks a cel/toon/anime style — and if no art bible exists yet, author one first via the look floor ([art-direction](art-direction.md)). Sibling links resolve to the skill directory. Confirm engine behavior against the linked documentation for the installed version before acting on it.
+
+## The opinion
+
+One toon shader family for the **whole frame**. Characters, walls, props, floor — all of it. A cel-shaded hero in a PBR room is the canonical broken look.
+
+## The ramp (URP, Unity 6)
+
+Two routes; pick by what's in the project:
+
+- **Shader Graph route** — the lighting lives in a [Custom Function node](https://docs.unity3d.com/Packages/com.unity.shadergraph@<VERSION>/manual/Custom-Function-Node.html), because Shader Graph exposes no main-light data as built-in nodes. Inside the function, call `GetMainLight()` and quantize `NdotL` into 2–3 hard bands via `smoothstep` with a narrow edge (0.02–0.05) so bands stay crisp but antialiased. Two requirements, mechanics on the linked pages:
+  - Give the function a preview-safe branch per the Custom Function node page above (previews have no light data).
+  - For cast shadows, pass `GetMainLight` a shadow coord and declare the three main-light shadow [keywords](https://docs.unity3d.com/Packages/com.unity.shadergraph@<VERSION>/manual/Keywords.html) (`_MAIN_LIGHT_SHADOWS`, `_MAIN_LIGHT_SHADOWS_CASCADE`, `_SHADOWS_SOFT` — Boolean, Global, Multi Compile), or `shadowAttenuation` reads 1 everywhere.
+  - `shader-graph-create-custom-node` turns finished HLSL into a reflected function node (it needs `com.unity.shadergraph` 17.5 or newer); the graph wiring above stays this reference's recipe.
+- **Hand-written HLSL route** — a single ~120-line URP shader covers it. Same quantized-NdotL core; add `_BaseColor`, `_ShadowTint`, `_Bands`.
+
+Either way: **shadow bands are palette-tinted, never black** — sample the art bible's shadow color (usually a cooler, darker sibling of the base) — and main-light shadow attenuation multiplies into the band input on both routes so cast shadows band too.
+
+## Outlines
+
+- **Inverted hull** (default): a second pass/material extruding vertices along normals in clip space, front-face culled. Width in screen space (~2 px equivalent) so it doesn't collapse with distance; outline color = palette's darkest value, not black.
+- **Renderer Feature** (whole-frame route): a fullscreen edge pass on depth+normals when you want environment edges too. Prefer this when the environment is mostly flat walls — hull outlines on giant planes look wrong. The feature is Render Graph code: run `validate-urp-render-graph-renderer-feature` over it before trusting it.
+
+## The supporting cast
+
+- **Skybox**: gradient from the palette (simple shader or tinted procedural) — the default blue procedural sky instantly breaks the style.
+- **Fog**: if used, tinted from the palette.
+- **Verify** (via `unity-cli`): machine scan first — eval over every renderer in frame asserting `sharedMaterial.shader.name` belongs to the toon family, with zero hits on `Universal Render Pipeline/Lit` (any hit names the object to convert) — then capture: bands visible on a curved surface, outlines uniform at two capture distances.
+
+## Expansion scope
+
+Ramp textures for painterly grades, rim/specular toon terms, face-shadow maps for characters, 2D-lit variant, VFX Graph toon integration, per-object outline masks.

package/skills/craft-game-floors/references/vfx.md

@@ -0,0 +1,40 @@
+# VFX
+
+> Craft reference for the `craft-game-floors` skill. Relative links in this file resolve to the skill directory. **Load:** during the feel pass and whenever an effect is needed — [game-feel](game-feel.md) says *when* effects fire; this reference says *what* they look like. Colors come from [art-direction](art-direction.md)'s palette; glow interplay from [scene-lighting](scene-lighting.md)'s bloom threshold. Confirm engine behavior against the linked documentation for the installed version before acting on it.
+
+## The rules (every effect, no exceptions)
+
+- **Palette only** — start/gradient colors sampled from the art bible; a white default particle breaks style as hard as a gray material.
+- **Short-lived** — 0.3–0.8 s lifetimes for event effects; size-over-lifetime shrinks to zero so nothing pops out of existence.
+- **Readable at gameplay distance** — size and count tuned against the real camera ([camera-rigs](camera-rigs.md)), verified by capture, not in the inspector.
+- **Pooled** — never Instantiate/Destroy per event. Reuse one ParticleSystem via `Stop`/`Clear`/`Play` (or one system with `Emit()`); when effects need real instances, pool them with [`UnityEngine.Pool.ObjectPool<T>`](https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/Pool.ObjectPool_1.html) — built into the engine, zero dependency. Construct it with a createFunc plus actionOnGet/actionOnRelease so reset-on-release is baked in; take with `Get()`, return with `Release(item)`.
+- **Nothing loops without a job** — a looping effect must be telling the player something (a shrine glows because it's interactive).
+
+## The recipes (URP, built-in ParticleSystem)
+
+- **Pickup burst** — 8–12 particles, sphere emission, radial start speed 2–3, slight gravity, palette accent → transparent gradient. Pair with the pop + blip ([game-feel](game-feel.md)).
+- **Trail** — for moving collectibles and guides (the butterfly case): a small emitter with rate-over-distance, 0.5 s lifetime, shrinking. Sells motion better than the mover itself.
+- **Ambient motes** — the interior seller: slow-drifting dust in the key light's direction, 10–20 alive, barely-visible palette-light color, large box emitter above the play space. This one effect makes a room feel inhabited.
+- **Milestone confetti** — 30–50 particles, cone up, gravity on, 2–3 palette colors, 1.2 s — reserved for the full-screen moments so they stay special.
+- **Movement puffs** — tiny 3–4 particle poofs on footfall/landing, ground-colored, 0.3 s.
+
+Material — the paved default: `Sprites/Default` (or URP particle-unlit explicitly set to Transparent) tinted from the palette; the failure table below has the two traps. Additive/glow sparingly and only above the bloom threshold on purpose — one glowing thing per frame is an accent; five is soup.
+
+## 2D delta
+
+In a 2D scene, particles sort through the renderer like every sprite: set Sorting Layer and Order in Layer on the [`ParticleSystemRenderer`](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/particlesystemrenderer.md) (both inherited from `Renderer`) so effects draw above the sprites they comment on and below UI. Sorting Layer beats camera distance — an effect on the wrong layer hides behind the background no matter its Z.
+
+## Failure modes
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| particles render fully opaque despite an alpha tint | URP particle-unlit ignores alpha while Surface Type is Opaque | use `Sprites/Default`, or set the material's Surface Type to Transparent (or enable Alpha Clipping) |
+| console floods with curve errors while animating velocity over lifetime | the x/y/z curves are in mixed modes (two set, one left default) | set **all three axes** in the same curve mode |
+
+## Verify
+
+Capture mid-effect at the gameplay camera (the done gate's "feedback visibility" axis needs the effect *in* the frame) — and time the capture by eval, not luck: assert the system's `particleCount > 0` at the capture moment. Pooling check: fire the effect ten times and assert the ParticleSystem instance count stayed constant before and after (a growing count means an Instantiate leaked in). Check the ambient motes read in a still — if they only register in motion, raise size slightly, never count.
+
+## Expansion scope
+
+VFX Graph for GPU-scale effects, shader-driven dissolves/impacts, decals, screen-space effects (speed lines, damage vignettes), effect LOD and budgets per platform.

package/skills/craft-game-floors/references/visual-scorecard.md

@@ -0,0 +1,43 @@
+# Visual Scorecard
+
+> Craft reference for the `craft-game-floors` skill. **Load:** at the end of every build session and after any visual change worth verifying. A single-floor touch-up owes only that floor's own Verify section; the full board below is the build session's done gate. Capture mechanics live in `unity-cli` (editor_play → capture_game_view → eval). Relative links in this file resolve to the skill directory. Confirm engine behavior against the linked documentation for the installed version before acting on it.
+
+## The rule
+
+**The first capture is a draft, never the deliverable.** A build session under these floors (any paved build) ends with scored frames, not a green compile. "It runs" and "it's done" are different claims; this gate is the difference.
+
+## Procedure
+
+1. **Record the Editor's starting state first** — whether Play mode is already running (a user-owned session is never restarted or stopped: score inside it or ask), and the current auto-tick and `runInBackground` values, so both can be restored after the gate. Then prove liveness with this four-call loop before trusting any capture: `editor set_auto_tick on` · script eval [`Application.runInBackground`](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/application/runinbackground.md) `= true` · `editor.playmode start` · a job wait on `Time.frameCount` with op `changed`. The command names here are the installed pipeline package's — confirm them with `unity command` before running. Run the loop every time: capture-on-demand renders frozen games as alive, and an unfocused Editor can freeze play at frame 1–2 while status still reports playing. **After the gate, restore the recorded auto-tick and `runInBackground` values and exit Play if the gate started it.**
+2. Render a warm-up frame and discard it before every scored capture — the first render after a rebuild comes back blank (async shader compile).
+3. Capture **three frames**: the standard gameplay angle · a character close-up · the busiest UI moment (mid-pickup or milestone, so feedback is *in* the frame). **UI in captures:** game-view capture can skip ScreenSpaceOverlay canvases entirely while the canvas is provably alive — for any frame that must show UI, either use a screen-level capture source where the installed pipeline package offers one (confirm its capture flags — names and `--view` options vary by version) or put the HUD on a ScreenSpaceCamera canvas, which renders in every capture path. Verify UI presence in the frame, not in the hierarchy. **Driving the game for captures:** simulated key events may not reach Input System polling in editor play mode — when a verification drive needs movement, compile a small debug-input hook into the controller rather than fighting the input simulator. **Where captures land:** `capture game_view` writes to `Assets/Captures/` — add `Assets/Captures/` to .gitignore before the first capture.
+4. Score each axis 1–5. The palette-discipline instant fail is machine-checkable first: eval-scan every renderer for `Default-Material`, TMP for the stock font **left at default settings** (a deliberately styled stock font passes — placeholder-assets prescribes exactly that), **every ParticleSystem's startColor and every HUD panel Image for untinted white/gray** (the two elements that most often slip the palette while passing the material scan; a white sprite tint that deliberately preserves the sprite's own colors also passes — the scan flags defaults, not choices), before scoring — so axis 1's fail never rests on eyesight alone. **If the request authorized changes**, anything below 3 gets a fix, and spend at least one fix pass even on a passing board; **on an assessment-only ask** ("score it"), report the board and the recommended fixes and change nothing until the user says go. When tuning live via `eval`: a timed-out eval may still have executed — mutations are not idempotent-safe; long work goes through `run_script`.
+
+## The six axes
+
+| Axis | The question | Instant fail |
+|---|---|---|
+| Palette discipline | Does every color trace to the art bible? | default-gray material, skybox, or UI anywhere |
+| Style uniformity | One style across character, environment, sky, UI? | style breaks at the character's edge |
+| Lighting depth | Warm/cool separation? Shadow sides alive? | flat white directional look |
+| Silhouette | Is the character identifiable filled black? Grade from the gameplay camera angle as well as a side view. | reads as "capsules" |
+| UI intentionality | HUD on the palette, aligned, styled text? | default uGUI skin visible |
+| Feedback visibility | Does the busy frame *show* the game answering the player? | a pickup frame with nothing happening |
+
+## The 2D anchor set
+
+For a 2D build, grade the same six questions through their 2D equivalents: palette discipline = every sprite tint traces to the bible (no default-white sprites); style uniformity = one consistent pixel density across all sprites, no mixed-resolution art; silhouette = the character reads at gameplay zoom, not just in the source asset; lighting depth = outline discipline instead — either every gameplay-critical sprite carries the outline treatment or none does; UI intentionality and feedback visibility grade unchanged. Where a 2D floor is missing, name the gap in the report rather than grading against a 3D axis the build cannot meet.
+
+## Calibration anchors
+
+- **5** — a promo still from a stylized indie (Monument Valley, A Short Hike): total palette and style discipline.
+- **3** — a polished jam entry: simple assets, but deliberate light, consistent style, styled UI. **The paved floor — the minimum any build under these floors ships at.**
+- **1** — untextured primitives under one white directional with default-gray UI: the documented starting point this gate exists to abolish.
+
+## Report
+
+Print the board in one fixed grammar — one line per axis, `axis: <score>/5 — <one-line evidence>` — so a later session can parse it, then what the fix pass changed, and attach the final captures. The scored frames are the session's proof-of-done artifact.
+
+## Expansion scope
+
+Baseline captures + visual regression across sessions, resolution/aspect sweeps, colorblind-safety check, bot-driven capture routes, per-genre anchor packs.

package/skills/create-2d-physics/SECURITY.md

@@ -0,0 +1,16 @@
+# Security notes: create-2d-physics
+
+This skill has the agent run C# inside the user's open Unity Editor through `unity command script eval`. Automated skill scanners flag that as a powerful capability. It is intentional, and it is limited by the safeguards below.
+
+## Accepted risks
+
+| Risk | Capability | Why it is accepted |
+|---|---|---|
+| `SEC_POWER_CAP` | Runs C# in the user's open Editor through `unity command script eval` | It only reaches the Editor the user already has open, on their own machine, as that user, so it grants nothing they couldn't do themselves. `script eval` sits behind the Pipeline capability gate. No code fetched from a remote source is run. Where a named `unity command` covers a step, the skill uses that instead of `script eval`. |
+
+## Mitigations
+
+- **Only the user's own Editor.** `unity command script eval` talks to the Editor open on this machine. It can't reach another machine or another user's Editor.
+- **Capability gate.** `script eval` is only available when the project's Pipeline package provides it.
+- **No remote code.** The agent runs C# it writes from this skill's own recipes. Nothing downloaded from outside is executed.
+- **Named commands first.** When a dedicated `unity command` covers a step, the skill uses it instead of `script eval`.

package/skills/create-2d-physics/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: create-2d-physics
+description: "Creates and fixes Unity 2D physics in both systems, 2D Physics Core and the legacy Rigidbody 2D system. Use when the user asks about any 2D physics task, even if neither system is named. Not for 3D physics."
+allowed-tools: WebFetch, WebSearch
+metadata:
+  version: 0.3.0
+  support: "https://unity.com/support-services"
+---
+
+# Create and fix Unity 2D physics
+
+Do not weigh 3D physics options. If evidence shows the user means 3D, say so and stop.
+
+## Important
+
+- Use the unity cli (`unity command --format json`) and the `unity-cli` and `unity-pipeline` skills for each step.
+- Before making changes, establish a baseline of the current behavior so you can tell whether a later result is actually caused by your change.
+- Create a restore point you can roll back to if your changes fail.
+- Do only what's asked. Don't change unrelated assets or files.
+- Avoid long explanations.
+- Verify runtime behaviour with temporary `Debug.Log` lines, then remove them, because the user didn't ask for logging and leftover lines clutter their script and console. Don't build settle-detection or permanent logging they didn't ask for. See [Final step](#final-step).
+- Never reflect over types to discover an API — fetch the member page instead. The system probe is the one exception.
+
+### Passing C# to `script eval`
+
+`script eval` compiles a statement block, not a file, so write the code without `using` directives and with fully qualified types. `return` what you want to read; it arrives at `data.result.result`. If the code doesn't compile, look up the error here:
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| `CS0210` | A `using` directive, which the compiler reads as a resource-disposal statement | Remove the directive and qualify the types |
+| `CS0246` / `CS0103` | An unqualified type, such as `Rigidbody2D` or `PhysicsWorld` | Use the full name, such as `UnityEngine.Rigidbody2D` or `Unity.U2D.Physics.PhysicsWorld` |
+| `CS0104` | A bare `Object`, which is ambiguous with `object` | Use `UnityEngine.Object` |
+
+## Step 0: Which physics system
+
+Unity has two 2D physics systems. They share no code and never interact. Identify which one before writing any physics code — an answer from the wrong system compiles, runs, and does nothing.
+
+Check the request, scene and existing scripts against the table below, in this order:
+
+1. Check the scene components and existing scripts first, because components are the reliable signal.
+2. Check the user's request wording: "add a collider" is component language, "spawn a thousand" is script language.
+3. If still unsure which systems are installed, run the probe below.
+4. If the route is still unknown, stop and ask — offer all three routes and never choose for the user.
+
+| Signal | System |
+| --- | --- |
+| Physics Pose, Area, Constraint or Simulation components | Core components, 6000.7+ with the package |
+| Rigidbody 2D, Collider 2D, Joint 2D, Effector 2D | Legacy |
+| `Unity.U2D.Physics` or `UnityEngine.LowLevelPhysics2D` types in script | Core in script |
+| `Rigidbody2D`, `Collider2D`, `Physics2D` types | Legacy |
+| Both present | Separate simulations. Say so, treat separately |
+| No signal | Stop and ask, offering the three routes above |
+
+Key:
+- Legacy = Rigidbody 2D and Collider 2D components.
+- Core components = Physics Pose and Physics Area, requiring `com.unity.2d.physics` and Unity 6000.7+.
+- Core in script = `Unity.U2D.Physics` API, no package needed.
+
+Probe:
+```
+unity command script eval --caller plugin --skill create-2d-physics --code 'var r = ""; foreach (var n in new[] { "UnityEngine.Rigidbody2D", "Unity.U2D.Physics.PhysicsWorld", "UnityEngine.LowLevelPhysics2D.PhysicsWorld", "Unity.U2D.Physics.PhysicsPose" }) { var f = false; foreach (var a in System.AppDomain.CurrentDomain.GetAssemblies()) if (a.GetType(n) != null) f = true; r += f + ","; } return r;'
+```
+The Probe returns: legacy present, Core as `Unity.U2D.Physics`, Core as `UnityEngine.LowLevelPhysics2D`, Core components present. Core exists if either Core value is true; the true one gives the namespace. `false` rules that route out.
+
+## Full topic map
+
+Before you go forward with a workflow or diagnosis:
+
+1. Open and read the [documentation page(s)](#full-topic-map) that cover the specific subject related to what you intend to do or fix and check if you've missed anything.
+2. Name the file(s) you read in your response.
+
+This is because your training knowledge about Unity might be out of date, incorrect, or for the wrong Unity version.
+
+Prefer `WebFetch` over `WebSearch` — faster and lands on the exact reference. Only fetch what you need. Replace `<VERSION>` with the following before fetching:
+
+- **Package on docs.unity3d.com**: The package version, eg `@6.6` or `@2.0`. Check the package version if unsure.
+- **docs.unity.com**: The product version, eg `7000.0`
+
+For docs.unity.com engine pages, use the Unity version, e.g. `6000.7`. Pages are markdown — URLs end in `.md`. Find the package version in `Packages/packages-lock.json`, because `manifest.json` can hold a range or a git URL instead of the resolved version.
+
+If the Editor install folder has a `Data/Documentation` folder (eg `...Unity/Hub/Editor/6000.6.0b2/Editor/Data/Documentation`), read the html files from the `en/Manual` folder. Otherwise use the online `.md` pages listed in the references below.
+
+Once you know the route, read the matching reference before acting:
+- [2D Physics Core reference](references/2d-physics-core.md) - components, configuring them, creating bodies in script, ownership, and the full Core topic map.
+- [Legacy 2D physics reference](references/legacy-2d-physics.md) - the legacy manual topic map.
+
+### API reference
+
+The Core and legacy APIs (`Unity.U2D.Physics` or `UnityEngine.LowLevelPhysics2D`, and `UnityEngine.Rigidbody2D`, `Collider2D`, `Physics2D`) are part of the Unity Engine. They are versioned by Unity version, so check the project's Unity version before relying on a specific class or method.
+
+1. Use the `unity-cli` skill to check the project's Unity version.
+2. If the Editor install folder has a `Data/Documentation` folder, grep the html files in the `en/ScriptReference` folder inside, and skip the remaining steps.
+3. Otherwise, fetch and cache `https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/xrefmap.yml` (replace `<VERSION>` with the project's Unity version in major.minor form). This file lists every public API member's fully qualified name as a `uid` (e.g. `uid: 'UnityEngine.Rigidbody2D.AddForce(UnityEngine.Vector2,UnityEngine.ForceMode2D)'`).
+4. Grep the yml file locally for a class or method instead of refetching per lookup. The file is large (about 6 MB), so don't read the whole file.
+5. Convert the `uid` to a markdown page: remove the parameters in brackets, lowercase it, replace `.` with `/`, and add `.md`. Then fetch `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/<converted uid>`. For example, `UnityEngine.Rigidbody2D.AddForce(UnityEngine.Vector2,UnityEngine.ForceMode2D)` => `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/rigidbody2d/addforce.md`. All overloads are on the same page.
+   - Constructors use `ctor` (e.g. `unityengine/vector2/ctor.md`), and indexers use `item` (e.g. `unityengine/vector2/item.md`).
+   - For operators, fetch the class page (e.g. `unityengine/vector2.md`) and follow its link.
+   - Links inside the pages start with `/engine/`. Add `https://docs.unity.com/en-us` before them.
+   - If the page doesn't exist for that Unity version, use the `href` in the `xrefmap.yml` entry instead (e.g. `href: 'Rigidbody2D.AddForce.html'` => `https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/Rigidbody2D.AddForce.html`).
+
+The Core **components** (Physics Pose, Area, Constraint, Simulation) are in the `Unity.U2D.Physics` namespace of the `com.unity.2d.physics` package. They are versioned by package version, not Unity version, so check the installed package version before relying on a specific class or method.
+
+1. Use the `unity-cli` skill to check the installed package version.
+2. Fetch and cache `https://docs.unity3d.com/Packages/com.unity.2d.physics@<version>/xrefmap.yml` (replace `<version>` with the installed package version in major.minor form). This file maps every public API member's fully qualified name to its docs page `href` (e.g. `href: api/Unity.U2D.Physics.PhysicsPose.html` => `https://docs.unity3d.com/Packages/com.unity.2d.physics@<version>/api/Unity.U2D.Physics.PhysicsPose.html`).
+3. Grep the yml file locally for a class or method instead of refetching per lookup. Don't read the whole file.
+
+Always use the docs matching the project's Unity version and installed package version rather than relying on training knowledge, because APIs are often marked obsolete between versions and a member you recall might be obsolete or removed in the project's version.
+
+## Worked examples
+
+Prefer in order: the C# example on the type or member page you are using; existing project scripts (match their style); the sample project at `https://github.com/Unity-Technologies/PhysicsExamples2D`. Check all three before inventing a pattern.
+
+## Final step
+
+Physics changes alter runtime behaviour, so a clean compile isn't enough. Run these checks in order. If any check fails, reread the [docs pages](#full-topic-map) to find out what you missed, fix it, and run the checks again.
+
+1. Use `console_status` to check the project has zero console errors.
+2. Read back what you changed, because a change can compile cleanly and still do nothing:
+   - For components you added or configured in the scene, use `script eval` to check each one exists on its GameObject and its properties hold the values you set, such as a Collider 2D's `isTrigger` or the members listed on a Core component's type page.
+   - For a script, read it back and check it uses the system and namespace from [Step 0](#step-0-which-physics-system), and sets each Core body's `type` explicitly.
+3. Add temporary `Debug.Log` lines that print the behaviour you changed, such as a body's position or velocity, or a contact or trigger callback firing.
+4. Enter Play mode and check the console shows the expected log lines and still has zero errors. You can also read the world through `script eval`. Take no screenshots, because they take too much time.
+5. Exit Play mode, remove the temporary `Debug.Log` lines, and check the console again has zero errors.
+
+## Final report
+
+Short checklist: what you changed and why, which physics system you used, anything left for the user to decide or do.
+

package/skills/create-2d-physics/references/2d-physics-core.md

@@ -0,0 +1,155 @@
+# 2D Physics Core
+
+## Contents
+
+- [Step 0](#step-0) — when to read before acting
+- [Configuring a component](#configuring-a-component)
+- [Creating in script](#creating-in-script)
+- [Ownership](#ownership)
+- [What you are likely to get wrong](#what-you-are-likely-to-get-wrong)
+- [Manual: 2D Physics Core](#manual-2d-physics-core)
+- [Scripting reference](#scripting-reference)
+- [Package documentation](#package-documentation)
+
+The engine API is a built-in module — no package needed. The Physics Pose, Area and Constraint **components** come from `com.unity.2d.physics`, requiring 6000.7+. Check `Packages/manifest.json` before suggesting a component; if absent, offer to add it using the `unity-package-management` skill.
+
+A component is not the physics object. It owns a body, shape or joint — operate on that owned object. Read/write it, apply forces, query it, handle contacts (from a worker thread if needed). See [Physics Pose and Physics Area components](https://docs.unity.com/en-us/engine/<VERSION>/manual/unity2d/2d-physics-api/create-objects/pose-and-area.md).
+
+The components use only the public API, by design, so nothing is component-only — a plain MonoBehaviour driving the engine API always works. Never say a case is unsupported. For many shapes or nested areas, Physics Area Composite already exists.
+
+Within Core: components for scene-authored objects, script for bulk runtime creation. The modules `com.unity.modules.physics2d` and `com.unity.modules.physicscore2d` are on by default; only matter if stripped. The Unity version sets the namespace, not which system exists. Read the [Unity 6.5 upgrade guide](https://docs.unity.com/en-us/engine/<VERSION>/manual/upgrade-guides/upgrade-guide-unity65.md) (local: `en/Manual/UpgradeGuideUnity65.html`) for the rename.
+
+## Step 0
+
+Before you go forward with a workflow or diagnosis:
+
+1. Open and read the documentation page(s) from the [Manual](#manual-2d-physics-core) or [Scripting reference](#scripting-reference) that cover the specific subject related to what you intend to do or fix and check if you've missed anything.
+2. Name the file(s) you read in your response.
+
+This is because your training knowledge about Unity might be out of date, incorrect, or for the wrong Unity version.
+
+Always use versioned URLs — unversioned links resolve to the current release, not the project's version.
+
+Core script type pages are an exception: the API only changed namespace, so the version only decides whether to write `Unity.U2D.Physics` or `UnityEngine.LowLevelPhysics2D`. Use the project's version when known, otherwise 6000.7.
+
+Most tasks (apply force or impulse, move a body, read velocity, add a component) need no reading — just do it.
+
+Exceptions that always require reading first:
+- **Setting component values**: fetch the type page per [Configuring a component](#configuring-a-component).
+- **Creating a body in script**: read the two pages in [Creating in script](#creating-in-script).
+- **Any member you cannot name with confidence**: read one page. Never read more than two pages for a single task.
+
+## Configuring a component
+
+Follow these rules for configuring a component:
+
+- Never write serialized fields — the serialized names differ from public names. Drive everything through public properties and methods via `script eval`.
+- Definition and geometry are separate: a pose's body settings live in its definition; an area's shape is its geometry. Configure them independently. A change to either needs its apply call before it takes effect — the type page states which one.
+- Before configuring any component, fetch its API page and use only members it lists. Read the installed version from `Packages/packages-lock.json` (major.minor, e.g. `1.1`), then fetch:
+`https://docs.unity3d.com/Packages/com.unity.2d.physics@<version>/api/Unity.U2D.Physics.<Type>.html`
+
+One page per type covers all members. If a member is missing, treat it as undocumented, not absent.
+
+## Creating in script
+
+Before creating a Core body in script, read these two pages and follow their examples. Set `type` on the definition explicitly.
+
+- `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unity/u2d/physics/physicsbodydefinition.md`
+- `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unity/u2d/physics/physicsbody.md`
+
+Use the project's version, or 6000.7 if unknown. On 6000.3–6000.4 the namespace is `UnityEngine.LowLevelPhysics2D`, e.g. `.../script-reference/unityengine/lowlevelphysics2d/physicsbody.md`.
+
+Script types — joints, geometry, queries, and everything else — are engine types in the main scripting reference only. Never look for them in the `com.unity.2d.physics` package docs.
+
+## Ownership
+
+Core only. Before you destroy or change a world, body, shape, chain or joint you didn't create in this task, read the owner rules on these pages and on the member page you're calling, such as [PhysicsBody.Destroy](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unity/u2d/physics/physicsbody/destroy.md):
+
+- [PhysicsBody.SetOwner](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unity/u2d/physics/physicsbody/setowner.md)
+- [PhysicsWorld.CreateOwnerKey](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unity/u2d/physics/physicsworld/createownerkey.md)
+
+Follow these rules:
+
+- Create an owner key and own what you create, so later calls can tell your objects from the user's.
+- Never destroy an object you only found through a query, because it belongs to the user's code or a component.
+- To remove a component-created object, remove its component instead.
+- After an owner-gated call, check the console for warnings, because a refused call doesn't throw.
+
+## What you are likely to get wrong
+
+Core's API is young and was renamed, so your recall is unreliable. Nothing carries over between systems unverified. Where a row links a page, read it instead of relying on recall.
+
+| Your likely assumption | What to do instead |
+| --- | --- |
+| Legacy manual pages are flat, like `class-Rigidbody2D.html` | Build URLs from the folder paths in the Legacy 2D physics reference |
+| Your recalled Core namespace is right for the project | Check the project's Unity version, then read the [Unity 6.5 upgrade guide](https://docs.unity.com/en-us/engine/<VERSION>/manual/upgrade-guides/upgrade-guide-unity65.md) |
+| Box2D v2 naming and semantics apply to Core | Ignore older forum answers. Read the Core type page |
+| A property uses the unit Box2D or the other system uses | Read the property page for its unit and range |
+| Core layer masks are the same width as a `LayerMask` | Read [PhysicsMask](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unity/u2d/physics/physicsmask.md) |
+| Some behaviour is component-only | None is. Drive the engine API from a MonoBehaviour |
+| A user's own component needs wiring to work with Unity's | None. All interaction is engine-side |
+| Any handle can be destroyed | Only what you own. Follow [Ownership](#ownership) |
+| You must create a world first | Read [PhysicsWorld.defaultWorld](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unity/u2d/physics/physicsworld/defaultworld.md) |
+| Debug visuals need gizmos or `Debug.DrawLine` | Use the Core physics renderer from [Scripting reference](#scripting-reference). Never hand-roll it |
+| A method exists because the other system has one like it | Confirm on its own page |
+| A recalled member such as `bodyType` still sets body type | Read [PhysicsBody.type](https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unity/u2d/physics/physicsbody/type.md) |
+| A newly created body has a known default type | Don't assume. Set `.type` explicitly: falls, thrown or bounces → Dynamic. Ground, wall or anchor → Static |
+| "add a circle/capsule/polygon/segment area" means the dedicated component | Could be that or Primitive with `shapeType` — same shape, two routes. Prefer dedicated when fixed at authoring time; Primitive only if it must switch at runtime. Chain Segment has no dedicated component |
+
+## Manual: 2D Physics Core
+
+If the Editor install folder has a `Data/Documentation` folder (eg `...Unity/Hub/Editor/6000.6.0b2/Editor/Data/Documentation`), read the html files from the `en/Manual/2d-physics-api/` folder. Local file names are flat: `2d-physics-api-<last path segment>.html` (e.g. `create-objects/reference-body.md` => `2d-physics-api-reference-body.html`), and section pages end `-landing` (e.g. `connect-objects.md` => `2d-physics-api-connect-objects-landing.html`). Start at `2d-physics-api-landing.html` and follow its links if a name doesn't match.
+
+Otherwise use the online pages.
+
+Base: `https://docs.unity.com/en-us/engine/<VERSION>/manual/unity2d/2d-physics-api/`. Pages are `.md`. The landing page is `https://docs.unity.com/en-us/engine/<VERSION>/manual/unity2d/2d-physics-api.md` — contents.
+
+Paths below are relative to the base:
+- `introduction.md` — what it is, component-to-object mapping
+- `get-started.md` — first scene with components
+- `create-objects.md` — Physics Pose and Physics Area components. Children in `create-objects/`: `pose-and-area.md`, `physics-object.md`, `add-sprite.md`, `debug-drawing.md` (Scene view editing, rendering modes)
+- `connect-objects.md` — joints. Children in `connect-objects/`: `joints.md`, `create-constraint.md`, `constraint-events.md`
+- `properties.md` — definitions, pinned properties, custom data, global settings. Children in `properties/`: `definitions.md`, `pin-properties.md`, `custom-data.md`, `class-physics-core-settings2d.md`, `preferences-window-reference.md`
+- `interactions.md` — collisions, contacts, triggers, filtering (queries are `PhysicsWorld` cast/overlap methods in the scripting reference). Children in `interactions/`: `introduction.md`, `collisions-enable.md`, `collision-handle.md`
+
+Read in full before acting (outside this skill's scope): `worlds.md`, `3d-planes.md`, `multithreading.md`.
+
+Component reference pages follow a pattern — build them:
+- Body: `create-objects/reference-body.md`
+- Area: `create-objects/reference-area-<kind>.md` (capsule, circle, composite, contour, path, polygon, primitive, segment, sprite)
+- Joint: `connect-objects/reference-joint-<kind>.md` (distance, fixed, hinge, relative, slider, wheel)
+- Constraint: `connect-objects/reference-constraint-ignore.md`
+- Simulation: `worlds/reference-simulation-component.md`
+- Assets: `worlds/reference-world.md` (Physics Simulation Definition), `worlds/reference-simulation-asset.md` (Physics Simulation World)
+
+This manual covers components. For joint structs, definitions, geometry, queries, math, events and destruction — use the scripting reference.
+
+## Scripting reference
+
+Build the URL — do not search for member pages. Names are lowercase.
+
+Base: `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/`
+
+| You want | Pattern | Example |
+| --- | --- | --- |
+| Legacy type in `UnityEngine` | `unityengine/<type>.md` | `unityengine/rigidbody2d.md` |
+| Core namespace (lists types) | `unity/u2d/physics.md` | |
+| Core type | `unity/u2d/physics/<type>.md` | `unity/u2d/physics/physicsbody.md` |
+| Core type, 6000.3–6000.4 | `unityengine/lowlevelphysics2d/<type>.md` | `unityengine/lowlevelphysics2d/physicsbody.md` |
+| Method, property, field or nested type | `<type page without .md>/<member>.md` | `unity/u2d/physics/physicsbody/createshape.md`, `unity/u2d/physics/physicsbody/linearvelocity.md` |
+| A joint in script | Start at `unity/u2d/physics/physicsjoint.md`, then `physics<kind>joint` and `physics<kind>jointdefinition` | `unity/u2d/physics/physicshingejoint.md` |
+
+A type page lists members; a method page lists every overload. Units, ranges and defaults are on property pages. A 404 means the name is wrong, or that version's docs aren't published — fetch the type page and read its members, or try an adjacent version.
+
+For the Core renderer: start at `unity/u2d/physics/physicsworld/renderingmode.md`, `unity/u2d/physics/physicscoresettings2d.md`, and `physicsworld` draw methods: `drawgeometry`, `drawshapeproxy`, `drawqueryresult`, `drawlinestrip`, `drawshapes`.
+
+## Package documentation
+
+Package API pages are live only — not local files. Fetch using the version from `Packages/packages-lock.json`:
+`https://docs.unity3d.com/Packages/com.unity.2d.physics@<major.minor>/api/Unity.U2D.Physics.<Type>.html`
+
+The package manual pages are local markdown conversions of the Unity Manual, stored at `<project-folder>/Library/PackageCache/com.unity.2d.physics@*/`. Read only the .md files in that specific `PackageCache` subfolder. You must not look at non-.md files, or look outside at other Library or PackageCache folders, otherwise it takes too much time. Start with `Documentation~/TableOfContents.md`, or list the `Documentation~/` `.md` files if there is none, to find the page you need.
+
+If that folder has no `.md` files, use the online pages at `https://docs.unity3d.com/Packages/com.unity.2d.physics@<VERSION>/manual/`, because some package versions don't ship their docs.
+
+The `api/index.html` listing fetches as nothing — go straight to a named type page.

package/skills/create-2d-physics/references/legacy-2d-physics.md

@@ -0,0 +1,45 @@
+# Legacy 2D physics
+
+Relative paths in this file resolve to the skill directory.
+
+## Step 0
+
+Before you go forward with a workflow or diagnosis:
+
+1. Open and read the [documentation page(s)](#manual-legacy-2d-physics) that cover the specific subject related to what you intend to do or fix and check if you've missed anything.
+2. Name the file(s) you read in your response.
+
+This is because your training knowledge about Unity might be out of date, incorrect, or for the wrong Unity version.
+
+## Manual: legacy 2D physics
+
+If the Editor install folder has a `Data/Documentation` folder (eg `...Unity/Hub/Editor/6000.6.0b2/Editor/Data/Documentation`), read the html files from the `en/Manual` folder. Start at `en/Manual/2d-physics/2d-physics.html` and follow its links, because local file names differ from the online paths (e.g. `2d-physics/rigidbody/rigidbody-2d-landing.html`).
+
+Otherwise use the online pages.
+
+Base: `https://docs.unity.com/en-us/engine/<VERSION>/manual/unity2d/`. Pages are `.md`.
+
+Pages, relative to the base:
+
+- `2d-physics.md` — contents page for legacy 2D physics
+- `2d-physics/rigidbody-2d.md` — Rigidbody 2D: body types, simulation and movement
+- `2d-physics/collider-2d.md` — Collider 2D types and their shared properties
+- `2d-physics/effectors-2d.md` — Effector 2D components, such as area, buoyancy and platform effectors
+- `2d-physics/2d-joints.md` — Joint 2D components that connect bodies
+- `2d-physics/physics-2d-profiler.md` — profiling the 2D physics simulation
+- `2d-physics/constant-force-2d-reference.md` — Constant Force 2D component (single page, no children)
+- `2d-physics/physics-material-2d-reference.md` — Physics Material 2D asset (single page, no children)
+
+Each landing page has a folder of the same name listing its children — follow those rather than guessing leaf names.
+
+## Scripting reference
+
+Legacy types live in the main scripting reference as `unityengine/<type>.md`, e.g. `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/rigidbody2d.md`. See the Scripting reference table in `references/2d-physics-core.md` for the full URL pattern, including how it differs from Core types.
+
+## What you are likely to get wrong
+
+| Your likely assumption | Actually |
+| --- | --- |
+| Your recall of legacy manual URLs is current | Build URLs from the [Manual](#manual-legacy-2d-physics) list, because the pages moved |
+| Legacy manual pages are flat, like `class-Rigidbody2D.html` | Use the family folders, such as `2d-physics/rigidbody-2d/` and `2d-physics/collider-2d/` |
+| A Core type or member has a legacy equivalent | Confirm on the legacy type's own page |