From cde5390b9a71ffe93989ee12c6f1185a675ea9df Mon Sep 17 00:00:00 2001 From: "pre-shared-workflows-auth[bot]" <168739156+pre-shared-workflows-auth[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 18:17:08 +0000 Subject: [PATCH] chore: publish 1 skill (craft-game-floors) --- skills/craft-game-floors/SKILL.md | 23 ++++-- .../references/game-shell.md | 4 +- .../references/playable-loop.md | 72 +++++++++++++++++++ .../references/visual-scorecard.md | 12 +++- 4 files changed, 101 insertions(+), 10 deletions(-) create mode 100644 skills/craft-game-floors/references/playable-loop.md diff --git a/skills/craft-game-floors/SKILL.md b/skills/craft-game-floors/SKILL.md index d6d41aa..9e59164 100644 --- a/skills/craft-game-floors/SKILL.md +++ b/skills/craft-game-floors/SKILL.md @@ -1,6 +1,6 @@ --- name: craft-game-floors -description: "Makes a Unity game look and feel finished: art style, lighting, juice, sound, menus, saves and look scoring. Use when building a new game's first playable version, or when a game looks like programmer art, feels flat or silent, or needs polish." +description: "Makes a Unity game playable and finished: core loop, art style, lighting, juice, sound, menus, saves, look scoring. Use for a first playable version, or one with no goal or win state, programmer art, a flat or silent feel, or polish needs." allowed-tools: - Bash - Read @@ -65,13 +65,13 @@ developer has made, and ask before adding one mid-project. 4. [camera-rigs](references/camera-rigs.md) — first gameplay camera (has a 2D section) 5. [placeholder-assets](references/placeholder-assets.md) — first missing asset 6. [character-motion](references/character-motion.md) — first moving character (3D-leaning) -7. *(the playable loop lands here — loop before content, one system per pass)* +7. [playable-loop](references/playable-loop.md) — once the character moves: close the loop (one verb, one goal, one pressure, win/lose, restart) before any content; a default, so a stated shape without win or lose (a sandbox, a toy) wins 8. [game-feel](references/game-feel.md) — the feel pass, after the loop 9. [vfx](references/vfx.md) — with the feel pass (has a 2D section) 10. [game-audio](references/game-audio.md) — before done 11. [game-shell](references/game-shell.md) — before done (2D backdrop delta). Before the first TextMeshPro text, import TMP Essentials (see the reference's failure table). 12. [live-floor](references/live-floor.md) — with the shell (services before gameplay code) -13. [visual-scorecard](references/visual-scorecard.md) — **the done gate, always last; run it once a playable loop exists.** During project creation, stop at the lit-baseline capture and skip the gate. +13. [visual-scorecard](references/visual-scorecard.md) — **the done gate, always last; run it once a playable loop exists — or, on a stated shape without win or lose, once the parts of floor 7 that fit are in** — creation runs included, since floor 7 closes theirs. Mid-project asks enter at the matching number and pull earlier floors only as the mid-flow check requires (the bible, the pipeline, the identity probe). @@ -108,10 +108,19 @@ frames, not a green compile. In order: 2. **Fix pass** — anything below 3 gets its fix before done (assessment-only asks: scores and recommendations, no fixes). If a fix doesn't work, reread the relevant reference and its linked documentation before trying variations. -3. **Console** — confirm zero console errors. -4. **Play check** — enter Play mode and check the touched behavior with `Debug.Log` lines you - added for the purpose. If the fix pass or this check fails, reread the relevant reference and - its linked documentation before trying variations. +3. **Console** — confirm zero console errors with `unity command console status`, and go no + further with console checks unless the user asked for proof or a specific fault is in play. + Command names come from the project's Pipeline package and vary by version (older ones name + it `console_status`), so confirm the installed name with `unity command` first. +4. **Play check** — enter Play mode once and read the touched behavior's state through + `unity command script eval` (the `unity-cli` skill's play-mode verification reference has the + loop), adding no logging or screenshots for the purpose. Never leave verification code in the + user's script. Never build logging or detection they didn't ask for. If the fix pass or this + check fails, reread the relevant reference and its linked documentation before trying + variations. +5. **Build proof** — on a build session (a creation run, or any session whose claim is a finished + game), run the player build and confirm the artifact exists, per the scorecard's build-proof + section. A single-floor touch-up skips this step, the same way it scopes the board. ## Final report diff --git a/skills/craft-game-floors/references/game-shell.md b/skills/craft-game-floors/references/game-shell.md index e933c0e..9685fbc 100644 --- a/skills/craft-game-floors/references/game-shell.md +++ b/skills/craft-game-floors/references/game-shell.md @@ -8,7 +8,7 @@ A game that boots directly into gameplay reads as a demo. The shell is formulaic ## The minimum shell (four states, one state machine) -One `GameState` enum (`Title, Playing, Paused, Ended`) on one manager; every screen is a palette-styled panel (see [art-direction](art-direction.md) — default uGUI skin never ships; if no art bible or Palette source exists yet, run that reference first — it is the root dependency). On a fresh URP template, import TMP Essential Resources before the first text element ([TMP font assets](https://docs.unity3d.com/Packages/com.unity.ugui@/manual/TextMeshPro/index.html)); the exact failure and fix are in the table below. +One state machine on one manager, because two owners drift apart. When the playable-loop floor's run-state owner exists, extend it rather than adding a second enum: its `Ready` is Title, `Running` is Playing, `Won`/`Lost` are Ended, and the shell adds only `Paused`. Otherwise, one `GameState` enum (`Title, Playing, Paused, Ended`). Every screen is a palette-styled panel (see [art-direction](art-direction.md) — default uGUI skin never ships; if no art bible or Palette source exists yet, run that reference first — it is the root dependency). On a fresh URP template, import TMP Essential Resources before the first text element ([TMP font assets](https://docs.unity3d.com/Packages/com.unity.ugui@/manual/TextMeshPro/index.html)); the exact failure and fix are in the table below. - **Title** — the worked treatment below. **Backdrop is the live game scene**, gameplay HUD hidden. Free production value; no separate art, and the style uniformity is automatic. - **Pause** — `Time.timeScale = 0` + dimmed overlay; Resume / Restart / Quit. Audio ducks −6 dB (mixer snapshot, [game-audio](game-audio.md)). Feel/tween code must run on *unscaled* time while paused ([game-feel](game-feel.md)'s Tween has an unscaled path). @@ -38,7 +38,7 @@ Every state change crosses a 0.3 s fade (one fullscreen black-from-palette overl ## Verify -Drive the full loop headlessly via `unity-cli` (eval state changes + capture each screen): boot → Title frame, pause → Paused frame, end → Ended frame, restart → clean second run. "Clean" is asserted, not eyeballed: eval-read the `GameState` enum at each step to confirm the transition landed, re-read the run counters after restart (score/XP/level back at initial values), and read the Editor log for a zero console-error count. Caveat when driving via `eval`: a timed-out eval may still have executed — mutations are not idempotent-safe; long work goes through `run_script`. +Drive the full loop headlessly via `unity-cli` (eval state changes + capture each screen): boot → Title frame, pause → Paused frame, end → Ended frame, restart → clean second run. "Clean" is asserted, not eyeballed: eval-read the state enum (the run-state owner's, or `GameState`) at each step to confirm the transition landed, re-read the run counters after restart (score/XP/level back at initial values), and read the Editor log for a zero console-error count. Caveat when driving via `eval`: a timed-out eval may still have executed — mutations are not idempotent-safe; long work goes through `run_script`. ## Expansion scope diff --git a/skills/craft-game-floors/references/playable-loop.md b/skills/craft-game-floors/references/playable-loop.md new file mode 100644 index 0000000..5fcfcab --- /dev/null +++ b/skills/craft-game-floors/references/playable-loop.md @@ -0,0 +1,72 @@ +# Playable Loop + +> Craft reference for the `craft-game-floors` skill. Relative links in this file resolve to the skill directory. **Load:** once a character moves and before any content pass, and whenever a build "has nothing to do", has no way to win or lose, or can't be restarted without leaving Play mode. Confirm engine behavior against the linked documentation for the installed version before acting on it. + +## The floor rule (a default, not a mandate) + +**By default, a run can be started, played toward a visible goal, won or lost, and restarted — all without leaving Play mode.** A world you can only walk around in reads as a tech demo, however good it looks; closing the loop is what makes it a game, so when the ask is open on shape, close the loop before adding content: one verb, one goal, one pressure, then build outward. + +**The user's stated design beats the default.** This floor fills the engine's "nothing to do" default, never the user's choice (the same rule every floor follows, from the mid-flow check): when the ask names a shape without win or lose — a sandbox, a toy, an endless sim, a walking experience — build that shape. Apply only the parts of the loop that still fit (a visible way to engage, a reset or restart that works without leaving Play mode), skip the rest without arguing, and name in the report which parts were set aside because of the user's design. At most one line offering the full loop, never a second. + +## The anatomy (five parts of the default loop) + +- **Verb** — the one thing the player does (move and collect, aim and shoot, place, dodge). The first loop gets exactly one verb; second verbs and mechanics are content passes after the loop closes. +- **Goal** — a state the verb moves toward, stated on the HUD from the first frame ("Collect 10", "Reach the gate", "Survive 60s"). A goal the player must infer is a missing goal. [game-shell](game-shell.md) owns the HUD's styling; this floor owns that the goal is on it. +- **Pressure** — the thing that can end the run against the player: a timer, a hazard, lives. Without pressure the goal is a checklist, and the win means nothing. +- **End states** — win and lose both reachable in normal play, each a *moment* ([game-feel](game-feel.md)'s milestone template), each landing on the end screen ([game-shell](game-shell.md)). +- **Restart** — one input from either end state into a fresh run. Prefer reloading the scene with [`SceneManager.LoadScene`](https://docs.unity.com/en-us/engine//script-reference/unityengine/scenemanagement/scenemanager/loadscene.md) over hand-resetting fields — and name the trap either way: statics, `DontDestroyOnLoad` objects and singletons survive a scene reload, so any run state they hold (score, timers, spawned-object registries) must be reset explicitly or the second run inherits the first run's state. + +## The driver (one opinion, one example) + +The opinion: **run state has one owner**, and the other floors subscribe to it — the shell's screens, the feel pass's moments, the live floor's score submits and any telemetry hang off its transitions instead of reaching into gameplay code. Expose the goal and pressure numbers (target count, run seconds, lives) on that owner so the eval → capture → eval loop can tune them live. + +A project that already has a run-state owner — its own manager, a state machine, an ECS system — keeps it: wire the floors to what exists rather than restructuring, because a floor never replaces a developer's choice. Only when the project has none, the example below is one small shape that works: + +```csharp +public enum RunState { Ready, Running, Won, Lost } + +// One owner of run state, transitions through these methods, and an event per +// transition so shell/feel/live wire in without reaching into gameplay code. +public class GameLoop : MonoBehaviour +{ + public RunState State { get; private set; } = RunState.Ready; + public event System.Action StateChanged; + + public void StartRun() { Set(RunState.Running); } + public void Win() { if (State == RunState.Running) Set(RunState.Won); } + public void Lose() { if (State == RunState.Running) Set(RunState.Lost); } + + void Set(RunState s) { State = s; StateChanged?.Invoke(s); } +} +``` + +The shell floor later adds pause to this same owner rather than a second state machine, because two owners drift apart (a menu showing a live run the loop already ended): see [game-shell](game-shell.md). + +## Build discipline + +1. Close the loop with placeholder everything — primitive pickups, a cube gate, a number for the timer — before any content or second mechanic, because an open loop makes every later pass unverifiable ("is this fun?" has no answer without a run that ends). +2. One system per pass, and the game is playable at the end of every pass — a pass that leaves the loop broken overnight is two passes. +3. The feel pass ([game-feel](game-feel.md)) comes after this floor by design: its pickup, milestone and end-state recipes need real loop events to hang on. + +## Verify + +Via `unity command script eval` in Play mode, drive the loop end to end — a loop a script can't drive is also a loop no later floor can hook: + +1. Assert `Ready`, fire the start input (or `StartRun()`), assert `Running`. +2. Drive the verb once and assert the progress value changed (counter up, timer down, distance closed). +3. Capture one mid-run frame with the goal and progress visible on the HUD — [visual-scorecard](visual-scorecard.md)'s feedback-visibility axis grades this frame, so take it while the run is still live. +4. Force the win by eval (set the progress to the goal), assert `Won` and the end screen active. +5. Fire restart. A scene reload brings the owner back in `Ready`, so assert `Ready` and the progress value at its start, then `StartRun()`, assert `Running`, and drive the verb once to prove the second run is live — this is the pass that catches surviving statics. +6. Force the lose by eval (run the pressure out: timer to zero, lives to zero), assert `Lost` and the end screen active. + +On a user-chosen shape without win or lose, verify the parts that exist instead: drive the verb, assert the visible way to engage (the floor rule's term) responds — a placed object persisting, a counter or reaction updating — and prove the reset restores a fresh state. + +Caveat: a timed-out `eval` may still have executed — mutations are not idempotent-safe; put anything long through `run_script`. + +## The boundary (what this floor is not) + +The floor is the loop *closing*, never the game's mechanics. A second verb, a double jump, enemy AI, level design, difficulty curves and content are the user's game code — route those asks to the user's own direction (or the matching catalog skill), not this reference. Score submits and saves on the end states belong to [live-floor](live-floor.md); the screens to [game-shell](game-shell.md); the moments to [game-feel](game-feel.md). + +## Expansion scope + +Per-genre loop profiles (platformer, shooter, cozy), wave/level progression, difficulty ramps, meta loops (upgrades between runs), tutorialization of the first run. diff --git a/skills/craft-game-floors/references/visual-scorecard.md b/skills/craft-game-floors/references/visual-scorecard.md index 6919a65..6b50e8d 100644 --- a/skills/craft-game-floors/references/visual-scorecard.md +++ b/skills/craft-game-floors/references/visual-scorecard.md @@ -34,9 +34,19 @@ For a 2D build, grade the same six questions through their 2D equivalents: palet - **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. +## The build proof + +On a **build session** — a creation run, or any session whose claim is a finished game — the gate ends with a player build, because "it runs in Play mode" and "it ships" are different claims: player-only compile errors, stripped code and missing platform modules all pass Play mode and fail the build. After the fix pass (so the build is of the final state, not a draft): + +1. Run the CLI's player build for the project's primary target — the platform the project was created for, or the Editor's active build target when nothing states one. Desktop targets build with `--target` alone (`unity build --target --output-path `); every other target, WebGL included, needs a Unity 6+ build profile: `unity build --create-profile ` once (commit the created asset with the project), then `unity build --profile --output-path `. `unity build --help` has the full option set. +2. The proof is three facts: the command exited success, the console/log carries zero build errors, and the artifact exists at the reported output path with a nonzero size. Record all three; a green exit alone is not the proof. +3. On a failure, read the build log's first error before trying variations — build-only failures are usually a missing module or a player-incompatible API, not taste. + +A single-floor touch-up skips the build the same way it scopes the board; the build's minutes belong to sessions that claim a finished game. The artifact this step proves is what a later publish step uploads. + ## Report -Print the board in one fixed grammar — one line per axis, `axis: /5 — ` — 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. +Print the board in one fixed grammar — one line per axis, `axis: /5 — ` — so a later session can parse it, then what the fix pass changed, and attach the final captures; on a build session, add one line for the build proof (target, artifact path, size). The scored frames and, on a build session, the build artifact are the session's proof-of-done. ## Expansion scope