coentrify 0.0.2 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (262) hide show
  1. package/LICENSE +18 -0
  2. package/README.md +2 -1
  3. package/bin/coentrify.js +83 -12
  4. package/package.json +3 -2
  5. package/src/changelog/0.0.1.md +259 -0
  6. package/src/changelog/0.0.2.md +219 -0
  7. package/src/changelog/0.0.3.md +81 -0
  8. package/src/changelog/0.0.4.md +198 -0
  9. package/src/changelog/0.0.5.md +160 -0
  10. package/src/changelog/0.0.6.md +282 -0
  11. package/src/changelog/0.0.7.md +113 -0
  12. package/src/changelog/0.0.8.md +212 -0
  13. package/src/changelog/0.1.0.md +9 -0
  14. package/src/changelog/0.1.1.md +27 -0
  15. package/src/changelog/overview.md +14 -0
  16. package/src/coentrify-json.md +74 -0
  17. package/src/commands.md +50 -0
  18. package/src/glossary.md +132 -0
  19. package/src/how-it-works.md +51 -0
  20. package/src/onboarding.md +141 -0
  21. package/src/origin.md +19 -0
  22. package/src/philosophy.md +99 -0
  23. package/src/proof.md +596 -0
  24. package/src/readme.md +76 -0
  25. package/src/recommendations.md +107 -0
  26. package/src/standards/ai/match-known-commands-deterministically-classify-the-rest.md +22 -0
  27. package/src/standards/ai/overview.md +6 -0
  28. package/src/standards/ai/prompt-small-models-differently.md +21 -0
  29. package/src/standards/angular/canmatch-wildcard-for-route-access.md +22 -0
  30. package/src/standards/angular/interface-not-abstract-class-for-mock-swap.md +37 -0
  31. package/src/standards/angular/no-any-in-templates.md +25 -0
  32. package/src/standards/angular/no-inline-templates.md +14 -0
  33. package/src/standards/angular/one-component-per-folder-flat.md +12 -0
  34. package/src/standards/angular/one-projected-node-per-control-flow-block.md +19 -0
  35. package/src/standards/angular/overview.md +16 -0
  36. package/src/standards/angular/prefer-content-projection-over-props-angular.md +17 -0
  37. package/src/standards/angular/projected-content-is-never-styled-by-the-host.md +23 -0
  38. package/src/standards/angular/static-attribute-not-literal-binding.md +23 -0
  39. package/src/standards/angular/track-timed-items-by-an-id.md +17 -0
  40. package/src/standards/angular/ui-copy-in-template.md +26 -0
  41. package/src/standards/angular/use-modern-angular-template-apis.md +20 -0
  42. package/src/standards/architecture/adopt-configure-override.md +25 -0
  43. package/src/standards/architecture/app-shield.md +57 -0
  44. package/src/standards/architecture/converge-only-once-proven.md +22 -0
  45. package/src/standards/architecture/folder-concerns.md +28 -0
  46. package/src/standards/architecture/overview.md +11 -0
  47. package/src/standards/architecture/per-application-split-over-shared-branching.md +25 -0
  48. package/src/standards/architecture/separation-before-layer-standards.md +17 -0
  49. package/src/standards/architecture/unique-where-it-counts.md +19 -0
  50. package/src/standards/behavior/a-go-before-work-elsewhere.md +17 -0
  51. package/src/standards/behavior/a-maybe-is-a-trigger-to-investigate.md +20 -0
  52. package/src/standards/behavior/a-name-describes-its-unit.md +19 -0
  53. package/src/standards/behavior/a-quiet-tree-while-a-suite-runs.md +19 -0
  54. package/src/standards/behavior/always-make-no-mistakes.md +45 -0
  55. package/src/standards/behavior/always-verify-before-reporting-done.md +18 -0
  56. package/src/standards/behavior/always-work-from-a-plan.md +29 -0
  57. package/src/standards/behavior/anchor-edits-after-formatting.md +17 -0
  58. package/src/standards/behavior/backward-trace-missing-prerequisites.md +20 -0
  59. package/src/standards/behavior/code-review-compounds-into-patterns-and-sweeps.md +21 -0
  60. package/src/standards/behavior/communication-boundary.md +18 -0
  61. package/src/standards/behavior/dev-tiers.md +25 -0
  62. package/src/standards/behavior/docs-hold-only-what-the-director-decided.md +23 -0
  63. package/src/standards/behavior/dont-filter-data-without-a-spec.md +20 -0
  64. package/src/standards/behavior/dont-introduce-tech-debt.md +25 -0
  65. package/src/standards/behavior/feature-workflow.md +31 -0
  66. package/src/standards/behavior/file-a-change-with-coentrify.md +25 -0
  67. package/src/standards/behavior/flag-every-addition-of-your-own.md +22 -0
  68. package/src/standards/behavior/free-text-replies-no-buttons.md +20 -0
  69. package/src/standards/behavior/general-working-rules.md +37 -0
  70. package/src/standards/behavior/non-destructive-documenting-and-test-automation.md +20 -0
  71. package/src/standards/behavior/normal-dashes.md +15 -0
  72. package/src/standards/behavior/note-issues.md +26 -0
  73. package/src/standards/behavior/overview.md +46 -0
  74. package/src/standards/behavior/own-ports-own-processes.md +37 -0
  75. package/src/standards/behavior/project-lifecycle.md +21 -0
  76. package/src/standards/behavior/propagate-renames-and-convention-changes-everywhere.md +16 -0
  77. package/src/standards/behavior/prose-style.md +24 -0
  78. package/src/standards/behavior/prototype-mode-is-speed-first.md +20 -0
  79. package/src/standards/behavior/regular-layered-gap-analysis.md +20 -0
  80. package/src/standards/behavior/reload-the-standards-after-compacting.md +16 -0
  81. package/src/standards/behavior/review-changes-before-reporting-done.md +17 -0
  82. package/src/standards/behavior/review-every-capture-before-reporting.md +21 -0
  83. package/src/standards/behavior/standards-maintenance.md +65 -0
  84. package/src/standards/behavior/standards-over-skills.md +17 -0
  85. package/src/standards/behavior/sweeps-enumerate-into-tech-debt-first.md +20 -0
  86. package/src/standards/behavior/sync-the-docs-after-every-change.md +20 -0
  87. package/src/standards/behavior/the-quality-of-the-question.md +17 -0
  88. package/src/standards/behavior/things-of-one-kind-are-consistent.md +20 -0
  89. package/src/standards/behavior/understand-the-need.md +69 -0
  90. package/src/standards/behavior/use-us-english-everywhere.md +17 -0
  91. package/src/standards/behavior/verify-apis-against-docs-and-the-installed-artifact.md +17 -0
  92. package/src/standards/behavior/verify-control-before-rename.md +11 -0
  93. package/src/standards/code/code-principles.md +32 -0
  94. package/src/standards/code/escape-hatch-comments.md +20 -0
  95. package/src/standards/code/name-by-concept-not-copy.md +20 -0
  96. package/src/standards/code/no-abbreviated-names.md +20 -0
  97. package/src/standards/code/no-describe-what-comments.md +26 -0
  98. package/src/standards/code/overview.md +10 -0
  99. package/src/standards/code/pre-empt-recurring-code-review-nits.md +31 -0
  100. package/src/standards/commits/commits.md +44 -0
  101. package/src/standards/commits/gate-commits-on-exit-codes.md +22 -0
  102. package/src/standards/commits/main-stays-green-work-stays-clean.md +23 -0
  103. package/src/standards/commits/overview.md +8 -0
  104. package/src/standards/commits/verify-staging-before-committing.md +29 -0
  105. package/src/standards/docs/application-template.md +89 -0
  106. package/src/standards/docs/docs-are-hierarchical-explicit-and-short.md +48 -0
  107. package/src/standards/docs/docs-describe-behavior-not-wiring.md +24 -0
  108. package/src/standards/docs/docs-folder-structure.md +38 -0
  109. package/src/standards/docs/docs-state-knowledge.md +23 -0
  110. package/src/standards/docs/documentation-philosophy.md +62 -0
  111. package/src/standards/docs/feature-spec-template.md +89 -0
  112. package/src/standards/docs/feature-template.md +62 -0
  113. package/src/standards/docs/file-names.md +20 -0
  114. package/src/standards/docs/glossary.md +18 -0
  115. package/src/standards/docs/library-feedback.md +20 -0
  116. package/src/standards/docs/no-faux-headers-in-lists.md +18 -0
  117. package/src/standards/docs/overview.md +20 -0
  118. package/src/standards/docs/ui-vocabulary.md +31 -0
  119. package/src/standards/docs/workspace-levels.md +24 -0
  120. package/src/standards/docs/workspace-suite.md +24 -0
  121. package/src/standards/docs/workspace-template.md +41 -0
  122. package/src/standards/e2e/e2e-assert-before-interacting.md +21 -0
  123. package/src/standards/e2e/e2e-mock-contract.md +20 -0
  124. package/src/standards/e2e/e2e-runs-on-the-development-build.md +18 -0
  125. package/src/standards/e2e/e2e-test-conventions.md +61 -0
  126. package/src/standards/e2e/e2e-tests-must-demonstrate-behavior.md +28 -0
  127. package/src/standards/e2e/one-check-for-many-canvas-clicks.md +17 -0
  128. package/src/standards/e2e/overview.md +14 -0
  129. package/src/standards/e2e/per-feature-overview-test.md +30 -0
  130. package/src/standards/e2e/real-input-for-frame-races.md +25 -0
  131. package/src/standards/e2e/substring-locator-collisions.md +23 -0
  132. package/src/standards/e2e/use-the-e2e-pipeline-for-browser-probing.md +18 -0
  133. package/src/standards/electron/electron-packaging-and-suite.md +22 -0
  134. package/src/standards/electron/electron-shell-shape.md +21 -0
  135. package/src/standards/electron/overview.md +6 -0
  136. package/src/standards/gamedev/2d-visual-design.md +22 -0
  137. package/src/standards/gamedev/budget-exceptions.json +6 -0
  138. package/src/standards/gamedev/captures-and-reels.md +39 -0
  139. package/src/standards/gamedev/devbox.md +21 -0
  140. package/src/standards/gamedev/game-design-laws-experience.md +68 -0
  141. package/src/standards/gamedev/game-design-laws-guidance.md +43 -0
  142. package/src/standards/gamedev/game-design-laws-own-style.md +33 -0
  143. package/src/standards/gamedev/game-design-laws-progress.md +64 -0
  144. package/src/standards/gamedev/game-design-laws-quality.md +30 -0
  145. package/src/standards/gamedev/game-design-laws-story.md +45 -0
  146. package/src/standards/gamedev/game-design-laws-ui.md +52 -0
  147. package/src/standards/gamedev/game-design-laws-world.md +38 -0
  148. package/src/standards/gamedev/game-design-laws.md +114 -0
  149. package/src/standards/gamedev/game-phases-concept.md +29 -0
  150. package/src/standards/gamedev/game-phases-design.md +39 -0
  151. package/src/standards/gamedev/game-phases-development.md +30 -0
  152. package/src/standards/gamedev/game-phases-live.md +19 -0
  153. package/src/standards/gamedev/game-phases.md +52 -0
  154. package/src/standards/gamedev/game-work-workflow.md +47 -0
  155. package/src/standards/gamedev/gamedev-working-cadence.md +52 -0
  156. package/src/standards/gamedev/incremental-pacing.md +22 -0
  157. package/src/standards/gamedev/launch-strategy.md +50 -0
  158. package/src/standards/gamedev/measure-sound-never-guess.md +24 -0
  159. package/src/standards/gamedev/overview.md +29 -0
  160. package/src/standards/gamedev/own-icons.md +19 -0
  161. package/src/standards/gamedev/silent-runs.md +26 -0
  162. package/src/standards/gamedev/sprite-sheet-frames.md +23 -0
  163. package/src/standards/overview.md +43 -0
  164. package/src/standards/records/activity-log.md +33 -0
  165. package/src/standards/records/changelog-per-version.md +43 -0
  166. package/src/standards/records/healing-log.md +23 -0
  167. package/src/standards/records/overview.md +10 -0
  168. package/src/standards/records/playtest-files.md +38 -0
  169. package/src/standards/records/request-log.md +30 -0
  170. package/src/standards/records/user-test-files.md +21 -0
  171. package/src/standards/reporting/change-report.md +43 -0
  172. package/src/standards/reporting/overview.md +6 -0
  173. package/src/standards/reporting/reels-and-video-proof.md +32 -0
  174. package/src/standards/scripts/no-npx-in-scripts.md +20 -0
  175. package/src/standards/scripts/npm-script-naming.md +43 -0
  176. package/src/standards/scripts/overview.md +7 -0
  177. package/src/standards/scripts/thin-wrappers-in-ci-and-hooks.md +25 -0
  178. package/src/standards/security/keep-personal-data-out-of-requests.md +16 -0
  179. package/src/standards/security/keep-secrets-away-from-agents.md +21 -0
  180. package/src/standards/security/never-access-the-keychain.md +16 -0
  181. package/src/standards/security/overview.md +7 -0
  182. package/src/standards/simple-workflow/bugs-template.md +38 -0
  183. package/src/standards/simple-workflow/overview.md +12 -0
  184. package/src/standards/simple-workflow/plan-template.md +50 -0
  185. package/src/standards/simple-workflow/plans-vs-persistent-files.md +31 -0
  186. package/src/standards/simple-workflow/remove-completed-items-from-docs.md +19 -0
  187. package/src/standards/simple-workflow/roadmap-template.md +41 -0
  188. package/src/standards/simple-workflow/technical-debt-template.md +44 -0
  189. package/src/standards/simple-workflow/the-simple-workflow.md +48 -0
  190. package/src/standards/simple-workflow/todo-template.md +31 -0
  191. package/src/standards/tests/a-bugs-test-reproduces-with-real-input.md +18 -0
  192. package/src/standards/tests/bracket-state-changes-with-contrast-assertions.md +37 -0
  193. package/src/standards/tests/gestures-in-tests.md +35 -0
  194. package/src/standards/tests/implementation-agnostic-assertions.md +20 -0
  195. package/src/standards/tests/implementation-agnostic-locators.md +18 -0
  196. package/src/standards/tests/overview.md +13 -0
  197. package/src/standards/tests/realistic-test-data-variance.md +24 -0
  198. package/src/standards/tests/seed-surfaces-every-state-on-page-1.md +17 -0
  199. package/src/standards/tests/test-design.md +47 -0
  200. package/src/standards/tests/test-the-system-behind-a-mock.md +21 -0
  201. package/src/standards/tickets-workflow/agent-roles.md +54 -0
  202. package/src/standards/tickets-workflow/budget-exceptions.json +6 -0
  203. package/src/standards/tickets-workflow/building-a-ticket.md +47 -0
  204. package/src/standards/tickets-workflow/overview.md +15 -0
  205. package/src/standards/tickets-workflow/stabilize-before-adding.md +18 -0
  206. package/src/standards/tickets-workflow/the-builder.md +28 -0
  207. package/src/standards/tickets-workflow/the-conductor.md +44 -0
  208. package/src/standards/tickets-workflow/the-done-part.md +23 -0
  209. package/src/standards/tickets-workflow/ticket-template.md +96 -0
  210. package/src/standards/tickets-workflow/work-item-names.md +30 -0
  211. package/src/standards/tickets-workflow/work-tracking.md +177 -0
  212. package/src/standards/tickets-workflow/work-workflow.md +123 -0
  213. package/src/standards/tickets-workflow/writing-a-ticket.md +50 -0
  214. package/src/standards/tooling/browser-captures-go-to-disk.md +20 -0
  215. package/src/standards/tooling/check-where-a-pane-click-landed.md +19 -0
  216. package/src/standards/tooling/defer-tooling-until-the-cost-shows-up.md +19 -0
  217. package/src/standards/tooling/develop-against-mocks.md +19 -0
  218. package/src/standards/tooling/hygiene-tests-run-on-their-own-runner.md +18 -0
  219. package/src/standards/tooling/lightweight-test-reporting-only.md +16 -0
  220. package/src/standards/tooling/node-versions.md +24 -0
  221. package/src/standards/tooling/overview.md +17 -0
  222. package/src/standards/tooling/parallel-agents.md +45 -0
  223. package/src/standards/tooling/playwright-parallel-runs.md +30 -0
  224. package/src/standards/tooling/playwright-video-recording.md +32 -0
  225. package/src/standards/tooling/read-before-you-truncate.md +19 -0
  226. package/src/standards/tooling/start-playwright-on-a-clean-port.md +22 -0
  227. package/src/standards/tooling/vitepress-wiki.md +38 -0
  228. package/src/standards/typescript/always-add-explicit-types.md +32 -0
  229. package/src/standards/typescript/barrel-imports.md +21 -0
  230. package/src/standards/typescript/no-magic-values.md +52 -0
  231. package/src/standards/typescript/one-artifact-per-file.md +19 -0
  232. package/src/standards/typescript/overview.md +8 -0
  233. package/src/standards/ui/communicate-state.md +21 -0
  234. package/src/standards/ui/never-obscure-information-the-user-needs.md +26 -0
  235. package/src/standards/ui/overview.md +16 -0
  236. package/src/standards/ui/pixel-perfect-design-check.md +22 -0
  237. package/src/standards/ui/ui-component-design.md +34 -0
  238. package/src/standards/ui/ui-components-first.md +25 -0
  239. package/src/standards/ui/ui-layout-via-slot-composition.md +33 -0
  240. package/src/standards/ui/ui-library-is-domain-agnostic.md +20 -0
  241. package/src/standards/ui/ui-refactor-preserve-dont-redesign.md +25 -0
  242. package/src/standards/ui/ui-styleguide.md +30 -0
  243. package/src/standards/ui/ui-variants-by-function-not-by-color.md +23 -0
  244. package/src/standards/ui/validation-errors-fire-on-submit.md +20 -0
  245. package/src/standards/ui/walk-the-users-journey.md +29 -0
  246. package/src/standards/web/always-use-design-tokens-for-colors.md +24 -0
  247. package/src/standards/web/dark-mode-through-tokens.md +19 -0
  248. package/src/standards/web/hidden-attribute-loses-to-display.md +22 -0
  249. package/src/standards/web/overview.md +9 -0
  250. package/src/standards/web/scss-shared-partial-imports.md +16 -0
  251. package/src/standards/web/transitions-only-on-user-toggle.md +19 -0
  252. package/src/standards.md +66 -0
  253. package/src/tools/overview.md +22 -0
  254. package/src/tools/scripts/coentrify-update.py +242 -0
  255. package/src/tools/scripts/unlink-missing-standards.py +138 -0
  256. package/src/tools/specs/changelog-append.md +15 -0
  257. package/src/tools/specs/coentrify-json-check.md +21 -0
  258. package/src/tools/specs/commit-gate.md +32 -0
  259. package/src/tools/specs/healing-append.md +15 -0
  260. package/src/tools/specs/landing.md +29 -0
  261. package/src/tools/specs/refuse-wrap-up-questions.md +22 -0
  262. package/src/tools/specs/reload-core-rules.md +20 -0
@@ -0,0 +1,6 @@
1
+ # Overview
2
+
3
+ The Electron standards: the Electron shell.
4
+
5
+ - [Electron Packaging And Suite](electron-packaging-and-suite.md) - unsigned per-platform builds on request, a packaged suite
6
+ - [Electron Shell Shape](electron-shell-shape.md) - a website in a thin Electron shell on a privileged app scheme
@@ -0,0 +1,22 @@
1
+ # 2D Visual Design
2
+
3
+ The visual rules a drawn scene gets wrong on the first try. A project's visual checklist points here, so a ticket's Visual Quality only adds what is its own ([Ticket Template](../tickets-workflow/ticket-template.md)).
4
+
5
+ ## Why
6
+
7
+ A scene lands right the first time, without a round of feedback.
8
+
9
+ ## Perspective
10
+
11
+ - One horizon and its vanishing points per scene. Every object is drawn in them.
12
+ - Verticals stay vertical, and the top and bottom edges of a standing object run to the vanishing point, never tilted on their own.
13
+ - A space seen inside another, such as a room through a doorway, takes the outer room's vanishing point.
14
+ - Repeated elements in depth (lights, tiles, a ceiling grid) shrink and converge together, their lines meeting in one point.
15
+ - A pattern on a floor or a ceiling is foreshortened with its surface.
16
+ - The check before landing: the scene's perspective lines drawn over a capture, every edge tested against them.
17
+
18
+ ## Related
19
+
20
+ - [Work Tracking](../tickets-workflow/work-tracking.md)
21
+ - [Review Every Capture Before Reporting](../behavior/review-every-capture-before-reporting.md)
22
+ - [Pixel-Perfect Design Check](../ui/pixel-perfect-design-check.md)
@@ -0,0 +1,6 @@
1
+ {
2
+ "game-design-laws-experience.md": {
3
+ "words": 682,
4
+ "reason": "twelve laws of one theme in one part"
5
+ }
6
+ }
@@ -0,0 +1,39 @@
1
+ # Captures And Reels
2
+
3
+ The day-to-day proof of a game change is a capture or a reel from the seeded scenarios, never a hand recording. One capture script per level labels its stills by the ticket's id and writes them into the wiki's image folder, linked from the ticket's Done part. One reel script per level records highlights as segments and joins them into one video with the game's own sound.
4
+
5
+ ## Why
6
+
7
+ The director can reproduce every state a capture shows.
8
+
9
+ ## Captures
10
+
11
+ - A capture belongs to one ticket and is taken while that ticket is in progress, to see that what was just made looks good. It goes in the ticket's Done part ([The Done Part](../tickets-workflow/the-done-part.md)). There is no capture batch of every level at the close.
12
+ - A later ticket that changes what an earlier capture shows takes a new capture under a new file name. A capture is never retaken under its old name, which would erase the step before.
13
+ - A report that hands a visible change made outside a ticket to the director carries its picture. A ticket's picture stands in its Done part.
14
+ - Wait for the intro to settle before a still. Capture only what changed, plus a sanity check.
15
+ - Every capture is read before it goes on the page ([Review Every Capture Before Reporting](../behavior/review-every-capture-before-reporting.md)).
16
+
17
+ ## Reels
18
+
19
+ - Reels are recorded on demand only, never at a version's close: with a playtest on every version the director sees the motion and sound first hand. The reels' flows still run quickly as tests, without recording.
20
+ - A segment starts from a scenario, marks its cut when the scene is on screen, records the sound, and saves both. The joiner orders the segments by recording time, since a shortened folder name loses its number.
21
+ - A level's reel runs on into the next level's opening. The changelog keeps a copy of a reel, when one is made, under the version's name.
22
+ - An edge flow worked on in the iteration goes into the level's reel or a small video of its own, so the director sees the flow that changed.
23
+
24
+ ## In A Browser
25
+
26
+ - Park the mouse in a corner and hide any app frame the game draws, such as a custom title bar, before a still.
27
+ - A segment records the sound by tapping the audio graph in the page.
28
+
29
+ ## How To Apply
30
+
31
+ - Suites and capture runs are muted ([Silent Runs](silent-runs.md)).
32
+ - Only the reel records sound.
33
+ - The videos stay untracked in git, the reels and the changelog's copies alike, since they are heavy and a reel, when one is made, is made for one version. Only chosen ones, such as a store page's, get tracked later. Ignore the video folders on day one.
34
+
35
+ ## Related
36
+
37
+ - [Reels And Video Proof](../reporting/reels-and-video-proof.md)
38
+ - [Work Tracking](../tickets-workflow/work-tracking.md)
39
+ - [Devbox](devbox.md)
@@ -0,0 +1,21 @@
1
+ # Devbox
2
+
3
+ Every game has a devbox: a small panel toggled by one key, open on every scene and staying open across them, whose options follow the scene. It hands out currency, rehearses an achievement or a toast, drops any rare event on the spot, loads any seeded scenario into the running save and switches levels. It ships in the playtest builds and is stripped for a release. Webdev has the same thing as mock toggles.
4
+
5
+ ## Why
6
+
7
+ The agent and the director reach any state of the game quickly.
8
+
9
+ ## How To Apply
10
+
11
+ - It sits in a corner out of the interface's way. Its one key follows [Same Trigger Both Ways](game-design-laws-ui.md#same-trigger-both-ways).
12
+ - The seeded scenarios live in one configuration and are the shared contract. The game itself never shortens for a test.
13
+ - The same scenarios drive the e2e cases, the captures, the reels and the devbox, so what the agent verified is what the director plays.
14
+ - A rare event gets a devbox trigger the first time it exists, and every scene's rare or slow state gets a scenario as it is built: fresh, mid-way, at the gate, at the boss.
15
+ - A release build strips it, and a check fails one that still holds it.
16
+
17
+ ## Related
18
+
19
+ - [E2E Mock Contract](../e2e/e2e-mock-contract.md)
20
+ - [Develop Against Mocks](../tooling/develop-against-mocks.md)
21
+ - [Game Design Laws](game-design-laws.md)
@@ -0,0 +1,68 @@
1
+ # Game Design Laws: Experience
2
+
3
+ Laws about what the player lives through from moment to moment. The index and the way a game uses them are in [Game Design Laws](game-design-laws.md).
4
+
5
+ ## Never Wait
6
+
7
+ The player never has to wait, unless it is technically impossible to continue right away. When waiting is unavoidable, entertain the player.
8
+
9
+ ## Always Something To Do
10
+
11
+ The player always has something to do. Short term, the pull to expand and explore. Mid term, the next objective and the one after it: the goals form a queue, so reaching one never leaves the player in the void that follows the last episode of a series. The queue brings no pressure, only something to want next. Long term, a dot on the horizon. When closing in on it, the outline of the next dot is already visible. The ultimate goal is not revealed too soon, but is visible from early mid-game. That holds at every skill level: a skilled player who goes fast never runs out of things to do. Nothing new to pursue for a moment is not nothing to do: there is the state to check and the next choice to think about, such as the balance when there is nothing to buy yet. Leave space for thinking, just not too much when the player already knows what to do. The better the player plays, the less time there is to think.
12
+
13
+ ## Exploration Is Rewarded
14
+
15
+ A player who looks around, opens something or goes somewhere unasked always finds something there: a thing to build, a clue, a secret. Curiosity pays, so the explorer keeps exploring.
16
+
17
+ ## Full Control
18
+
19
+ The player feels in full control. Nothing is decided and nothing happens without the player taking action. A surprise of the world answers the player ([Fair Surprise](game-design-laws-world.md#fair-surprise)).
20
+
21
+ ## Respect
22
+
23
+ The player feels respected. No dumb tutorials. Feeling the need for a tutorial is a sign that something is not obvious.
24
+
25
+ ## Speedrun Ready
26
+
27
+ A returning player speedrunning the game has just as good an experience as a player starting for the first time.
28
+
29
+ ## Once Per Save
30
+
31
+ A story cutscene plays once per save, the first time its moment comes. Every later run of that save goes past it without stopping. A replayed run or a prestige never replays it, and a new save plays it again. A progression minigame plays once per save too: a later run passes a won minigame at once, its outcome given.
32
+
33
+ ## AFK Safe
34
+
35
+ The player can always be away, planned, unplanned or urgent, without negative effects from the game state. This goes two ways: nothing dies, nothing is lost and no events are missed while away, and nothing progresses beyond what the player set running. No blocking pop-ups that stop the game until OK is clicked.
36
+
37
+ - What the player set running keeps running until the player pauses it: a factory produces, perhaps until its materials run out, and currency grows.
38
+ - Nothing upgrades on its own, and no raid or heavy debuff lands while the player is away.
39
+
40
+ ## Easy Pause
41
+
42
+ Pausing is always easy.
43
+
44
+ ## Soft Sound
45
+
46
+ The mix is soft. A repeated sound varies a bit in pitch and length. A layer belongs to its scene: it starts with the scene and stops when the scene leaves. Playtest feedback on sound asks for softer, lower and more varied, never for louder.
47
+
48
+ ## Fun First
49
+
50
+ Player experience is priority number one. The game is fun, and so is the main gameplay loop.
51
+
52
+ - A test of the design: a good game clips well. Plain footage of the game being played holds a viewer.
53
+ - Footage that does not hold up points at a change in the design, never at more steering.
54
+ - Nothing is designed for the clip. A good game produces those moments by itself.
55
+
56
+ ## Loop First
57
+
58
+ The core loop is fun in a greybox, before anything is built on it. Looks, content and story do not rescue a loop that is no fun bare. The law is also the gate of the Prototype phase ([Game Phases: Concept](game-phases-concept.md#prototype)).
59
+
60
+ ## Related
61
+
62
+ - [Game Design Laws: Progress](game-design-laws-progress.md)
63
+ - [Game Design Laws: UI](game-design-laws-ui.md)
64
+ - [Game Design Laws: Story](game-design-laws-story.md)
65
+ - [Game Design Laws: Guidance](game-design-laws-guidance.md)
66
+ - [Game Design Laws: World](game-design-laws-world.md)
67
+ - [Game Design Laws: Own Style](game-design-laws-own-style.md)
68
+ - [Game Design Laws: Quality](game-design-laws-quality.md)
@@ -0,0 +1,43 @@
1
+ # Game Design Laws: Guidance
2
+
3
+ Laws about what the game hints and teaches. The index and the way a game uses them are in [Game Design Laws](game-design-laws.md).
4
+
5
+ ## No Yellow Paint
6
+
7
+ Yellow paint is steering applied too much, the exemplary case being the painted ledge: an arrow, a hint, a helper or a quest log that does the player's thinking. Steering that is needed is not yellow paint. Where it seems needed, the design gets another look first. One thing on screen with a clear hover and interactable state needs no word to click it. Rich context clues drive the narration without deciding or thinking for the player. Two questions test it at any moment: what am I looking at, and what am I expected to do here.
8
+
9
+ - A hint is a context clue: it encloses what is already on screen in a narrative and gives it meaning, ambiguous and indirect, innocent without the context. It never motivates.
10
+ - Lines that cheer the player on, almost through, keep going, nearly there, do the opposite of a clue: they say nothing about the world and treat the player as someone who needs encouragement, which nobody does.
11
+ - Telling the player what to do belongs to a concept the player has not met before, and then once. A mechanic that has been introduced is never hinted again, and the line goes as soon as the concept has landed.
12
+
13
+ ## Answer The Player's Next Question
14
+
15
+ What the game shows is support for the player's decisions: it answers the question the player would ask at that moment, guiding their thoughts without steering them ([Walk The User's Journey](../ui/walk-the-users-journey.md)). So every word and number is weighed by what it means to the player there, never by what the system holds.
16
+
17
+ - A value means something only against a reference: 0 means nothing, Free says this is a purchase, things here cost something, and this one costs nothing.
18
+ - A purchase says what it gets the player, so they know where to look next.
19
+ - A tiered value shows where the player stands, where it goes and the difference, and makes plain whether a step adds to the last or multiplies it, and what it comes to in the game.
20
+ - Nothing is told in terms the player has not met yet: a currency is introduced as something to get, the wallet at 0, before a price is told in it. No buff on something that does not exist yet.
21
+ - It serves both ways of thinking: the explorer asking what can be done here, and the follower asking what the game wants done.
22
+
23
+ ## Adopt, Repeat, Confirm (ARC)
24
+
25
+ Every new thing is introduced in five steps, shaped to fit the thing, one new thing per link.
26
+
27
+ - Awareness: the feature is seen, no action yet
28
+ - Trigger: the conditions for the action are met
29
+ - Adopt: the player does it once
30
+ - Repeat: the player does it again
31
+ - Confirm: the third time confirms the action as a skill. It is a test that can be failed, an invitation, and the game just moves on
32
+
33
+ Confirm overlaps the next link's Awareness, so the pattern widens the horizon as it chains.
34
+
35
+ ## Related
36
+
37
+ - [Game Design Laws: Experience](game-design-laws-experience.md)
38
+ - [Game Design Laws: Progress](game-design-laws-progress.md)
39
+ - [Game Design Laws: UI](game-design-laws-ui.md)
40
+ - [Game Design Laws: Story](game-design-laws-story.md)
41
+ - [Game Design Laws: World](game-design-laws-world.md)
42
+ - [Game Design Laws: Own Style](game-design-laws-own-style.md)
43
+ - [Game Design Laws: Quality](game-design-laws-quality.md)
@@ -0,0 +1,33 @@
1
+ # Game Design Laws: Own Style
2
+
3
+ Laws about what makes the game its own: its assets and its inventions. The index and the way a game uses them are in [Game Design Laws](game-design-laws.md).
4
+
5
+ ## No Asset Flips
6
+
7
+ Every asset is the game's own, and nothing looks generic. The style gives the game its identity.
8
+
9
+ ## Blueprint First
10
+
11
+ Things of one kind come from one blueprint: its style, its guidelines and its artistic choices, cartoony or realistic say. Ten buildings from one blueprint cohere.
12
+
13
+ ## Shown Together
14
+
15
+ Everything of one kind is shown in one place: a styleguide, a dev level, a page with every icon. Together, a style can be judged.
16
+
17
+ ## Generate, Never Reuse
18
+
19
+ Making an asset is a commodity now. Generate your own, and never reuse a pack. Music is the exception: a track may come from a library, licensed for the game, unless the music is where the game is unique ([Unique Where It Counts](#unique-where-it-counts)).
20
+
21
+ ## Unique Where It Counts
22
+
23
+ The game is unique in what makes it that game, and the rest follows best practice ([Unique Where It Counts](../architecture/unique-where-it-counts.md)). A narrative game never reinvents the inventory, unless the inventory is a core element.
24
+
25
+ ## Related
26
+
27
+ - [Game Design Laws: Experience](game-design-laws-experience.md)
28
+ - [Game Design Laws: Progress](game-design-laws-progress.md)
29
+ - [Game Design Laws: UI](game-design-laws-ui.md)
30
+ - [Game Design Laws: Story](game-design-laws-story.md)
31
+ - [Game Design Laws: Guidance](game-design-laws-guidance.md)
32
+ - [Game Design Laws: World](game-design-laws-world.md)
33
+ - [Game Design Laws: Quality](game-design-laws-quality.md)
@@ -0,0 +1,64 @@
1
+ # Game Design Laws: Progress
2
+
3
+ Laws about the shape of the whole game: its length, its completion and the progress the player makes. The index and the way a game uses them are in [Game Design Laws](game-design-laws.md).
4
+
5
+ ## Start And End
6
+
7
+ The game has a start and an end. That also counts for prestige and new game plus.
8
+
9
+ ## As Long As It Is Interesting
10
+
11
+ The game is as long as it is interesting, not the other way around.
12
+
13
+ - No level, scene or story beat has a target length. Everything is there as it should be
14
+ - Nothing is stretched to fill a playtime, and nothing is cut to meet one
15
+ - A fast player goes fast
16
+ - The game ends while the player still wants more
17
+
18
+ ## Doable 100%
19
+
20
+ Completing the game 100% is reasonably doable. No orthogonal gameplay, like a parkour section in an automation game, that demands a different skill for completion. Pride in 100% comes from playing the entire game and doing all the side quests. A player grinding, bored, because of one missing side quest means the side challenges were designed wrong.
21
+
22
+ ## No Try Hard
23
+
24
+ Beating the game normally never requires playing try hard. The game supports every type of player, the completionist and the casual alike, by staying flexible and never forcing a play style. Optimizing is there for the player who wants it.
25
+
26
+ ## Bands, Not Bullseyes
27
+
28
+ Relevant for: skill checks, timing and crafting.
29
+
30
+ Success is a band, never a bullseye. A hit lands in a hitbox, never on a point, and a short grace period absorbs lag and thinking time. A beginner scrapes through, an expert optimizes, and any method that lands in the band counts ([No Try Hard](#no-try-hard)).
31
+
32
+ ## Desire Before Reward
33
+
34
+ The player wants a thing before they can have it. A wreck on the horizon is seen long before it can be reached ([Always Something To Do](game-design-laws-experience.md#always-something-to-do)). The wanting makes the way there worth playing, a dull task included. A reward that comes before the wanting is worth nothing.
35
+
36
+ ## Earned Progress
37
+
38
+ The player feels the progress made, so the gap between where the player starts and ends is as big as it can be: the player starts with as little as possible and earns the rest. Nothing that can be earned is handed over. What comes for free is worth nothing. A free first step that starts a climb is no gift but the climb's first rung.
39
+
40
+ - Quality of life is earned too. A task is done by hand first and automated later, so losing friction is progress.
41
+ - Upgrades come in small, regular steps that are felt in play.
42
+ - Relevant for an economy: every step up brings a new risk beside the new unlock.
43
+
44
+ ## Lasting Impact
45
+
46
+ What the player does and decides has a lasting effect on the game's progress.
47
+
48
+ ## Emergent Gameplay
49
+
50
+ Systems whose mere existence opens possibilities for the player, play styles among them, rather than features that each do one thing.
51
+
52
+ ## Know What Is Coming
53
+
54
+ The player always knows what is coming in the short future: the next upgrade, the next unlock, the distance to the next goal, and when it is the end. There is always something coming, so the next upgrade or level is always looming. Knowing needs no overview or progress bar: the world can show it, by a billboard, a glimpse or a line of dialog. Nothing unlocks before it is introduced ([Adopt, Repeat, Confirm](game-design-laws-guidance.md#adopt-repeat-confirm-arc)). The world still keeps its secrets ([Fair Surprise](game-design-laws-world.md#fair-surprise)).
55
+
56
+ ## Related
57
+
58
+ - [Game Design Laws: Experience](game-design-laws-experience.md)
59
+ - [Game Design Laws: UI](game-design-laws-ui.md)
60
+ - [Game Design Laws: Story](game-design-laws-story.md)
61
+ - [Game Design Laws: Guidance](game-design-laws-guidance.md)
62
+ - [Game Design Laws: World](game-design-laws-world.md)
63
+ - [Game Design Laws: Own Style](game-design-laws-own-style.md)
64
+ - [Game Design Laws: Quality](game-design-laws-quality.md)
@@ -0,0 +1,30 @@
1
+ # Game Design Laws: Quality
2
+
3
+ Laws about the bar everything in the game meets. The index and the way a game uses them are in [Game Design Laws](game-design-laws.md).
4
+
5
+ ## Always Polished
6
+
7
+ The game that goes out is polished and fully done: once it is live, every version a player sees is. An unfinished game goes to controlled playtests only, and an early access sells polished parts and gates the rest ([Launch Strategy](launch-strategy.md)). Everything is of the same or similar quality.
8
+
9
+ - Whatever gets made is good at what it does, from the first version on. Player movement built in Pre-Alpha feels right, while the body that moves may still be a placeholder.
10
+ - The look and the finish wait for Alpha ([Game Phases: Development](game-phases-development.md)).
11
+ - The work follows the spirit of the task, never only its words ([Understand The Need](../behavior/understand-the-need.md)).
12
+
13
+ ## Every Mechanic Matters
14
+
15
+ Everything added, mechanics, content and systems alike, adds value to the experience, or it lowers the quality of the game by design. None is added for the sake of having one more. A mechanic gone irrelevant makes the player stop caring.
16
+
17
+ - A thing that fits no purpose is considered for cutting.
18
+ - That look ends one of two ways: a purpose nobody had named is found, or the thing was distracting from the main game.
19
+ - An example: a player who can enter every house gets an endless loop of exploring without reward. The houses stay when the game is about feeling free and needing places to hide, or when a house has something to do.
20
+
21
+ ## Related
22
+
23
+ - [Game Design Laws: Experience](game-design-laws-experience.md)
24
+ - [Game Design Laws: Progress](game-design-laws-progress.md)
25
+ - [Game Design Laws: UI](game-design-laws-ui.md)
26
+ - [Game Design Laws: Story](game-design-laws-story.md)
27
+ - [Game Design Laws: Guidance](game-design-laws-guidance.md)
28
+ - [Game Design Laws: World](game-design-laws-world.md)
29
+ - [Game Design Laws: Own Style](game-design-laws-own-style.md)
30
+ - [Game Phases: Development](game-phases-development.md)
@@ -0,0 +1,45 @@
1
+ # Game Design Laws: Story
2
+
3
+ Laws about what the game says. The index and the way a game uses them are in [Game Design Laws](game-design-laws.md).
4
+
5
+ ## Show, Don't Tell
6
+
7
+ Never tell the player what happened, what to feel or what to experience. Let the player experience it. A bad guy is discovered by doing a bad thing to the player, so the frustration is felt rather than announced. A good thing arrives as emotionless stats that do something, not as lore or explanation. The player attaches their own judgment. When words are needed, they are short and easy to understand, preferably voiced, subtitled and animated, without being too spot on.
8
+
9
+ ## Worth Reading
10
+
11
+ Relevant for: dialog.
12
+
13
+ Part of what makes a game good is that the player can miss something, which gives them a reason to read.
14
+
15
+ - No dialog has arrows to walk its lines again
16
+ - A line missed stays missed
17
+
18
+ ## Dialog Gives Context
19
+
20
+ Relevant for: dialog.
21
+
22
+ Dialog accompanies what is on screen as its narrative: it gives the player the context the picture alone leaves out, what is going on, who is there and what is at stake.
23
+
24
+ - The context comes from characters speaking about what they see and want: "Who is that?" "I don't know, he looks scary. Let's get out of here before he sees us."
25
+ - A guide checks in, explains and asks whether the player is ready.
26
+ - Dialog gives context, never instructions: what to do stays with [No Yellow Paint](game-design-laws-guidance.md#no-yellow-paint).
27
+ - A narrator explaining what happened or what to feel stays out ([Show, Don't Tell](#show-dont-tell)).
28
+
29
+ ## Make Yourself
30
+
31
+ Relevant for: a player character.
32
+
33
+ The player can personalize the game to reflect themselves: the character can look like them, their hair, their face, their build, and the world carries what they stand for. Being represented matters more than a look of a certain vibe or graphical realism. A player who cannot make themselves is missing something.
34
+
35
+ The player needs the ability and the space to represent themselves: the personalization options, and no steering of their judgment. The game stays as neutral as it can, so the character can relate. That is no indifference when a bad guy is being bad. It means not clouding it with external reasoning or noise, the writer's judgment among them.
36
+
37
+ ## Related
38
+
39
+ - [Game Design Laws: Experience](game-design-laws-experience.md)
40
+ - [Game Design Laws: Progress](game-design-laws-progress.md)
41
+ - [Game Design Laws: UI](game-design-laws-ui.md)
42
+ - [Game Design Laws: Guidance](game-design-laws-guidance.md)
43
+ - [Game Design Laws: World](game-design-laws-world.md)
44
+ - [Game Design Laws: Own Style](game-design-laws-own-style.md)
45
+ - [Game Design Laws: Quality](game-design-laws-quality.md)
@@ -0,0 +1,52 @@
1
+ # Game Design Laws: UI
2
+
3
+ Laws about what the player sees and touches. The index and the way a game uses them are in [Game Design Laws](game-design-laws.md).
4
+
5
+ ## Communicate State
6
+
7
+ Always communicate state and interaction ([Communicate State](../ui/communicate-state.md)). What can be clicked reacts to hovering, what is disabled looks disabled yet stays readable, and what changed shows it. A cap is a gate: whatever is capped shows disabled with the cap explained in the tooltip, never hidden, and every cap needs a good reason, otherwise a better solution.
8
+
9
+ ## Alive App, Static Actions
10
+
11
+ The app feels alive: something is always moving on screen, things happen. Actions feel static: each action is just there. No idle animations on buttons, no slow bubble-up animations on modals or pop-ups that hold a secondary action, because those make the player wait again. The player stays in control.
12
+
13
+ ## No Hard Edges
14
+
15
+ No sharp edge exists anywhere unless it is necessary. Every panel, button, row and box has rounded corners, if only slightly, and so does everything the scenes draw, a screen on a wall included. In the world the law holds in a softer form: nothing real is perfectly sharp, a building's corner is worn and a plank is sanded, so a model's edges carry a slight bevel, and a hard edge sticks out. A corner stays sharp only when the thing itself would read wrong rounded. In the world that is a deliberate choice, and canon in the game: a blade, barbed wire, a spiked fence.
16
+
17
+ ## Glow In Contrast
18
+
19
+ A glow always takes a color that contrasts the text it wraps. Light text glows in color, colored text glows dark.
20
+
21
+ ## No Layout Shifts
22
+
23
+ Controls never move. A button stays where it is while the player acts, so two quick upgrades land where they were aimed. A form keeps every row it can have: a row that does not apply shows grayed out, never left out.
24
+
25
+ ## Same Trigger Both Ways
26
+
27
+ What opens an interaction closes it. A menu that opens on Escape closes on Escape. A key that opens an inventory never does something else when it is pressed again while the inventory is open. That is easy on expectations.
28
+
29
+ ## Say What Is Wrong
30
+
31
+ A warning says what is wrong. A warning sign alone leaves the player fishing for what is going on, so every warning carries its reason, and a supported choice is never warned about.
32
+
33
+ ## Mouse First
34
+
35
+ Relevant for: PC.
36
+
37
+ The game plays best on a mouse and its wheel, the way most gamers play. A trackpad is taken into account for accessibility, never at the mouse's cost.
38
+
39
+ - Every notch of a wheel moves a list by one step, at once, however fast the wheel turns
40
+ - A trackpad's small movements add up to a step, so a list stays usable on one
41
+ - A close icon carries a lot of padding: a bigger button is easier to click
42
+ - Every click in the game acts on the press, never waiting for the release, so it feels snappier
43
+
44
+ ## Related
45
+
46
+ - [Game Design Laws: Experience](game-design-laws-experience.md)
47
+ - [Game Design Laws: Progress](game-design-laws-progress.md)
48
+ - [Game Design Laws: Story](game-design-laws-story.md)
49
+ - [Game Design Laws: Guidance](game-design-laws-guidance.md)
50
+ - [Game Design Laws: World](game-design-laws-world.md)
51
+ - [Game Design Laws: Own Style](game-design-laws-own-style.md)
52
+ - [Game Design Laws: Quality](game-design-laws-quality.md)
@@ -0,0 +1,38 @@
1
+ # Game Design Laws: World
2
+
3
+ Laws about the world the player moves through: its secrets, its reactions and its friction. The index and the way a game uses them are in [Game Design Laws](game-design-laws.md).
4
+
5
+ ## Fair Surprise
6
+
7
+ The world has rules the player does not know yet, and the player finds them by playing, never by being told.
8
+
9
+ - A surprise answers something the player did. It never comes out of nothing.
10
+ - It warns once, in the world's own way: a sign of strength for the player who looks.
11
+ - It may hurt, at a cost the game has already made normal.
12
+ - It opens something: a path of discovery, a questline, a reward for the player who learns to use it.
13
+ - After the first time the risk is readable. The player sees it coming and can partly steer it.
14
+ - A risk that can never be read is a dice roll, and teaches nothing.
15
+
16
+ An example of the surprise: an ordinary-looking creature, attacked by accident, turns out far stronger than anything met so far. It takes the first hit and gives a warning no other character gives. The player who goes on loses the fight, wakes up where every lost fight ends, and has found the start of a hidden questline.
17
+
18
+ An example of the readable risk: speeding with forbidden goods can get the player pulled over. The player chose the speed, and can still pay, talk or run. A fine that lands at random leaves nothing to learn.
19
+
20
+ [Full Control](game-design-laws-experience.md#full-control) holds, since the surprise answers the player's own action. [Know What Is Coming](game-design-laws-progress.md#know-what-is-coming) keeps the progress visible, and the world keeps its secrets.
21
+
22
+ ## The World Reacts
23
+
24
+ The world acknowledges the player's presence: an action leaves a trace that can be seen. A trace may fade again. The reaction is what counts.
25
+
26
+ ## Friction In The World
27
+
28
+ Friction is something the player does in the world, never a menu or a wait.
29
+
30
+ ## Related
31
+
32
+ - [Game Design Laws: Experience](game-design-laws-experience.md)
33
+ - [Game Design Laws: Progress](game-design-laws-progress.md)
34
+ - [Game Design Laws: UI](game-design-laws-ui.md)
35
+ - [Game Design Laws: Story](game-design-laws-story.md)
36
+ - [Game Design Laws: Guidance](game-design-laws-guidance.md)
37
+ - [Game Design Laws: Own Style](game-design-laws-own-style.md)
38
+ - [Game Design Laws: Quality](game-design-laws-quality.md)
@@ -0,0 +1,114 @@
1
+ # Game Design Laws
2
+
3
+ Laws are short rules that hold unless there is a very good reason to break one. The generic set lives in the standards, in eight parts by theme, and this standard is its index. A game's own laws and overrides stand in the game's docs.
4
+
5
+ ## Why
6
+
7
+ Design builds on what is settled, and an agent decides the small things on its own.
8
+
9
+ ## The Set
10
+
11
+ ### Experience
12
+
13
+ The full text is in [Game Design Laws: Experience](game-design-laws-experience.md).
14
+
15
+ - [Never Wait](game-design-laws-experience.md#never-wait) - the player never waits unless continuing is technically impossible. Unavoidable waiting entertains
16
+ - [Always Something To Do](game-design-laws-experience.md#always-something-to-do) - a pull short term, a dot on the horizon long term
17
+ - [Exploration Is Rewarded](game-design-laws-experience.md#exploration-is-rewarded) - looking around always finds something
18
+ - [Full Control](game-design-laws-experience.md#full-control) - nothing is decided or happens without the player
19
+ - [Respect](game-design-laws-experience.md#respect) - no dumb tutorials
20
+ - [Speedrun Ready](game-design-laws-experience.md#speedrun-ready) - a returning speedrunner has as good an experience as a first-time player
21
+ - [Once Per Save](game-design-laws-experience.md#once-per-save) - a story cutscene and a progression minigame play once per save
22
+ - [AFK Safe](game-design-laws-experience.md#afk-safe) - away without negative effect. Nothing is lost, and only what the player set running keeps running
23
+ - [Easy Pause](game-design-laws-experience.md#easy-pause) - pausing is always easy
24
+ - [Soft Sound](game-design-laws-experience.md#soft-sound) - a soft mix, varied repeats, a layer per scene
25
+ - [Fun First](game-design-laws-experience.md#fun-first) - player experience is priority one. A good game clips well
26
+ - [Loop First](game-design-laws-experience.md#loop-first) - the core loop is fun in a greybox, before anything is built on it
27
+
28
+ ### Progress
29
+
30
+ The full text is in [Game Design Laws: Progress](game-design-laws-progress.md).
31
+
32
+ - [Start And End](game-design-laws-progress.md#start-and-end) - the game has both, prestige and new game plus included
33
+ - [As Long As It Is Interesting](game-design-laws-progress.md#as-long-as-it-is-interesting) - no target length
34
+ - [Doable 100%](game-design-laws-progress.md#doable-100) - no orthogonal skill demanded for completion
35
+ - [No Try Hard](game-design-laws-progress.md#no-try-hard) - every play style is supported
36
+ - [Bands, Not Bullseyes](game-design-laws-progress.md#bands-not-bullseyes) - success is a tolerance window, never an exact point
37
+ - [Desire Before Reward](game-design-laws-progress.md#desire-before-reward) - the player wants a thing before they can have it
38
+ - [Earned Progress](game-design-laws-progress.md#earned-progress) - start with as little as possible and earn the rest
39
+ - [Lasting Impact](game-design-laws-progress.md#lasting-impact) - what the player decides lasts
40
+ - [Emergent Gameplay](game-design-laws-progress.md#emergent-gameplay) - systems that open possibilities
41
+ - [Know What Is Coming](game-design-laws-progress.md#know-what-is-coming) - the next step and the distance to the next goal are always visible
42
+
43
+ ### Quality
44
+
45
+ The full text is in [Game Design Laws: Quality](game-design-laws-quality.md).
46
+
47
+ - [Always Polished](game-design-laws-quality.md#always-polished) - what goes out is polished, and whatever gets made is good at what it does
48
+ - [Every Mechanic Matters](game-design-laws-quality.md#every-mechanic-matters) - everything added adds value, or it goes
49
+
50
+ ### UI
51
+
52
+ The full text is in [Game Design Laws: UI](game-design-laws-ui.md).
53
+
54
+ - [Communicate State](game-design-laws-ui.md#communicate-state) - what reacts, what is disabled and what changed shows it
55
+ - [Alive App, Static Actions](game-design-laws-ui.md#alive-app-static-actions) - something always moves, actions are instant
56
+ - [No Hard Edges](game-design-laws-ui.md#no-hard-edges) - rounded corners everywhere, and soft edges in the world. Sharp only on purpose
57
+ - [Glow In Contrast](game-design-laws-ui.md#glow-in-contrast) - a glow contrasts the text it wraps
58
+ - [No Layout Shifts](game-design-laws-ui.md#no-layout-shifts) - controls never move while the player acts
59
+ - [Same Trigger Both Ways](game-design-laws-ui.md#same-trigger-both-ways) - what opens an interaction closes it
60
+ - [Say What Is Wrong](game-design-laws-ui.md#say-what-is-wrong) - a warning carries its reason
61
+ - [Mouse First](game-design-laws-ui.md#mouse-first) - a PC game plays best on a mouse
62
+
63
+ ### Story
64
+
65
+ The full text is in [Game Design Laws: Story](game-design-laws-story.md).
66
+
67
+ - [Show, Don't Tell](game-design-laws-story.md#show-dont-tell) - the player experiences it. Words short and never too spot on
68
+ - [Worth Reading](game-design-laws-story.md#worth-reading) - for dialog: a missed line stays missed
69
+ - [Dialog Gives Context](game-design-laws-story.md#dialog-gives-context) - dialog accompanies the screen as narrative and gives context, never instructions
70
+ - [Make Yourself](game-design-laws-story.md#make-yourself) - for a player character: the player can represent themselves
71
+
72
+ ### Guidance
73
+
74
+ The full text is in [Game Design Laws: Guidance](game-design-laws-guidance.md).
75
+
76
+ - [No Yellow Paint](game-design-laws-guidance.md#no-yellow-paint) - no steering that does the player's thinking. A hint is a context clue
77
+ - [Answer The Player's Next Question](game-design-laws-guidance.md#answer-the-players-next-question) - every word and number is weighed by what it means to the player
78
+ - [Adopt, Repeat, Confirm (ARC)](game-design-laws-guidance.md#adopt-repeat-confirm-arc) - a five step pattern for every new thing: awareness, trigger, adopt, repeat, confirm
79
+
80
+ ### World
81
+
82
+ The full text is in [Game Design Laws: World](game-design-laws-world.md).
83
+
84
+ - [Fair Surprise](game-design-laws-world.md#fair-surprise) - the world has rules the player finds by playing. A surprise answers the player, warns once and is readable after
85
+ - [The World Reacts](game-design-laws-world.md#the-world-reacts) - an action leaves a trace that can be seen
86
+ - [Friction In The World](game-design-laws-world.md#friction-in-the-world) - friction is something the player does there, never a menu or a wait
87
+
88
+ ### Own Style
89
+
90
+ The full text is in [Game Design Laws: Own Style](game-design-laws-own-style.md).
91
+
92
+ - [No Asset Flips](game-design-laws-own-style.md#no-asset-flips) - every asset is the game's own
93
+ - [Blueprint First](game-design-laws-own-style.md#blueprint-first) - things of one kind come from one blueprint
94
+ - [Shown Together](game-design-laws-own-style.md#shown-together) - everything of one kind is shown in one place
95
+ - [Generate, Never Reuse](game-design-laws-own-style.md#generate-never-reuse) - generate an asset, never reuse a pack, music aside
96
+ - [Unique Where It Counts](game-design-laws-own-style.md#unique-where-it-counts) - unique in what makes the game, best practice for the rest
97
+
98
+ ## How To Apply
99
+
100
+ - The player is a human who walks the dog, answers the door, goes to sleep and continues the next day. Laws about that human, such as Easy Pause, Never Wait and AFK Safe, translate into any genre. Only their concrete shape changes.
101
+ - A game's laws doc has three parts: the generic laws it adopts, the ones it leaves out with a reason, and its own laws and overrides in full.
102
+ - An adopted or left-out law is named by its name in this set, never copied.
103
+ - A law for one kind of game says so in its name or in a `Relevant for:` line, and is adopted or left out by it.
104
+ - An exception is a paragraph under the law in the game's overrides, naming the feature and the reason, added only when the director affirms it.
105
+ - Check a new feature against the laws before its spec. A conflict is surfaced, never averaged.
106
+ - Feature docs link the law they lean on instead of repeating it.
107
+ - A new law goes in the game's docs, in the director's wording. One that holds for other games too, a subset of them included, is filed with coentrify, its game specifics stripped, with a `Relevant for:` line for a subset ([File A Change With Coentrify](../behavior/file-a-change-with-coentrify.md)).
108
+
109
+ ## Related
110
+
111
+ - [Adopt, Configure, Override](../architecture/adopt-configure-override.md)
112
+ - [Communicate State](../ui/communicate-state.md)
113
+ - [Docs Hold Only What The Director Decided](../behavior/docs-hold-only-what-the-director-decided.md)
114
+ - [Work Workflow](../tickets-workflow/work-workflow.md)
@@ -0,0 +1,29 @@
1
+ # Game Phases: Concept
2
+
3
+ The first stage of a game ([Game Phases](game-phases.md)). Concept is divergent: everything can change and nothing is wrong.
4
+
5
+ ## Idea
6
+
7
+ The game in one line, with its pillars. Gate: does the line excite?
8
+
9
+ ## Gathering
10
+
11
+ Braindumps, a rant room, brainstorming. Gathering never closes: ideas keep coming, and land as tickets for later. Gate: does the director call the outline?
12
+
13
+ ## Outline
14
+
15
+ A basic outline of a plan, made from the ideas. Gate: does it say what to prototype?
16
+
17
+ ## Prototype
18
+
19
+ Trying things: a greybox, the outline and the size of the map, features. A prototype is thrown away. Gate: is the core loop fun in a greybox? ([Loop First](game-design-laws-experience.md#loop-first))
20
+
21
+ ## How To Apply
22
+
23
+ - Concept is a pile of gathering, and unorganized by nature. Its material is parsed from the director's prompts and brainstorms.
24
+ - The phases of Concept may overlap and loop back.
25
+ - Concept's gathering is logged, and needs no tickets. A prototype is tracked by its one ticket ([Prototype Mode Is Speed First](../behavior/prototype-mode-is-speed-first.md)), and an idea that Gathering files for later is a ticket too.
26
+
27
+ ## Related
28
+
29
+ - [Game Phases: Design](game-phases-design.md)