Makelore 2.0 initial clean snapshot

.opencode/skills/nianxxgame-skill/references/game-design-standards.md

@@ -0,0 +1,278 @@
+# Practical Game Design Standards
+
+Use this reference to turn a game idea into decisions that can be implemented and tested. Treat the GDD as a living agreement about player experience, not as a pitch deck or a complete prediction of the final game.
+
+## Contents
+
+1. [Build a traceable design chain](#1-build-a-traceable-design-chain)
+2. [Set pillars and non-goals](#2-set-pillars-and-non-goals)
+3. [Specify systems before building them](#3-specify-systems-before-building-them)
+4. [Protect feel, readability, and fairness](#4-protect-feel-readability-and-fairness)
+5. [Balance with explicit targets](#5-balance-with-explicit-targets)
+6. [Plan progression and content](#6-plan-progression-and-content)
+7. [Design UX and accessibility with the game](#7-design-ux-and-accessibility-with-the-game)
+8. [Control scope, risk, and playtesting](#8-control-scope-risk-and-playtesting)
+9. [Review designs and propagate changes](#9-review-designs-and-propagate-changes)
+
+## 1. Build a traceable design chain
+
+Connect every important feature through this chain:
+
+**Fantasy → Verbs → Mechanics → Rules → Feedback → Loop**
+
+| Link | Question to answer | Useful output |
+|---|---|---|
+| Fantasy | Who is the player, and what should it feel like to be them? | One concrete experience statement |
+| Verbs | What meaningful actions express that fantasy? | A short list of player verbs |
+| Mechanics | What systems make those actions possible? | State, interactions, resources, and relationships |
+| Rules | What creates decisions, limits, risk, and consequences? | Preconditions, transitions, formulas, and invariants |
+| Feedback | How does the player perceive action, state, and consequence? | Visual, audio, motion, UI, and control response |
+| Loop | Why does the player repeat the actions with new decisions? | A closed sequence from goal to result to next goal |
+
+Write the chain in player language before implementation language. For example:
+
+> Feel like a nimble rooftop courier → run, jump, route, recover → momentum and traversal systems → speed trades off against safe landings → immediate motion and landing feedback → choose route, traverse, deliver, improve, retry.
+
+Check traceability in both directions:
+
+- Remove or defer a mechanic that supports no intended verb or pillar.
+- Add rules or feedback when a promised verb has no meaningful decision or readable result.
+- Repair any loop that has no clear goal, result, or reason to repeat.
+- Distinguish a core loop from a list of activities. A loop changes state and creates the next decision.
+
+Avoid starting with content volume, feature names, or technology. First prove that the smallest version of the chain is enjoyable and understandable.
+
+## 2. Set pillars and non-goals
+
+Define two to four design pillars. Make each pillar a decision rule, not a slogan.
+
+A useful pillar contains:
+
+- The experience to protect.
+- An observable implication for rules, presentation, or content.
+- A trade-off it wins when two good ideas conflict.
+
+Weak: “Fast and fun.”
+
+Stronger: “Keep decisions fast: the player can read the next threat and act without opening a menu.”
+
+Write explicit non-goals beside the pillars. Non-goals prevent accidental expansion and make trade-offs honest. Examples include “no long-term crafting economy,” “no competitive balance,” or “no precision platforming on touch input.” Do not describe quality failures as non-goals.
+
+Use the following filter for every proposed feature:
+
+1. Name the pillar or required player outcome it supports.
+2. State what new decision or expression it creates.
+3. State its implementation, content, UX, and testing cost.
+4. Cut or defer it if the benefit cannot justify the cost inside the current milestone.
+
+## 3. Specify systems before building them
+
+Give each scheduled system a stable ID such as `SYS-001`. Keep the specification short enough to review, but precise enough that two implementers would produce the same player-facing behavior.
+
+Include these fields:
+
+| Field | Required decision |
+|---|---|
+| Purpose | Player need and pillar supported |
+| Player decision | Choice, skill, or expression created |
+| Inputs and preconditions | What starts the system and when it is legal |
+| State | Data the system owns or reads |
+| Rules and transitions | Ordered behavior, formulas, priority, and invariants |
+| Outputs | State changes and events visible to other systems |
+| Feedback | How success, failure, availability, and cause are communicated |
+| Tunables | Named values, units, defaults, safe ranges, and intended effect |
+| Edge cases | Interruptions, simultaneous events, limits, and recovery behavior |
+| Dependencies | Systems, content, assets, and platform assumptions |
+| Non-goals | Behavior explicitly outside this version |
+| Acceptance | Up to three observable conditions for completion |
+| Playtest question | The most uncertain player-facing assumption |
+
+Prefer state transitions over vague prose. For any action, define at least:
+
+`available → started → active → resolved or interrupted → recovered`
+
+Specify conflict rules where events can overlap. Define which event wins, whether inputs buffer, which state owns cleanup, and how the player recovers. Avoid hidden special cases; if an exception is necessary, record why it exists.
+
+Keep tunable values outside scattered behavior code where practical. Name values by their design meaning rather than by their current number.
+
+A system is ready to build when its purpose, normal path, failure path, feedback, major edge cases, and acceptance conditions are known. Unknown numeric values are acceptable when they are marked as tuning hypotheses with test ranges.
+
+## 4. Protect feel, readability, and fairness
+
+### Game feel
+
+Make the control response fit the promised fantasy. For each core verb, examine:
+
+- Input recognition and input-to-visible-response delay.
+- Start, active, contact, recovery, and cancellation phases.
+- Acceleration, deceleration, momentum, hit-stop, shake, animation, and sound.
+- Input buffering, forgiveness windows, aim assistance, or snapping where appropriate.
+- Whether feedback reinforces the true rule instead of disguising it.
+
+Layer feedback by purpose:
+
+1. Confirm the input or state change immediately.
+2. Show the world consequence at the point of interaction.
+3. Reinforce importance with secondary motion, audio, particles, or UI.
+
+Do not let animation delay a supposedly immediate action unless anticipation is itself part of the challenge. Add intensity only after the action is mechanically legible.
+
+### Readability
+
+Ensure the player can answer these questions during play:
+
+- What can I act on now?
+- What is dangerous, helpful, or unavailable?
+- What changed, and what caused it?
+- What is my current goal and progress?
+- What can I do after a failure?
+
+Use hierarchy, contrast, shape, timing, position, motion, and sound consistently. Never rely on color, sound, small text, or brief animation alone for critical information. Test the game at the actual play size and under the busiest expected state, not only in isolated scenes.
+
+### Fairness
+
+Make outcomes explainable even when the game is difficult:
+
+- Telegraph threats early enough for the intended skill level and input method.
+- Keep cause and effect consistent across similar situations.
+- Avoid unavoidable damage, hidden rule changes, and punishment from unreadable off-screen events.
+- Provide recovery, mitigation, or a deliberate commitment trade-off.
+- Distinguish execution difficulty from missing information.
+- On failure, communicate the cause and make retry friction proportional to the lesson.
+
+Fair does not mean easy. It means the player can form a correct model, make a meaningful choice, and understand the result.
+
+## 5. Balance with explicit targets
+
+Define the experience target before changing numbers. Examples include desired encounter duration, number of mistakes allowed, time between meaningful choices, resource pressure, or frequency of a signature action.
+
+For every important tuning value, record:
+
+- Name, unit, default, and allowed range.
+- Player-facing purpose.
+- Systems and content affected.
+- Evidence for the current value.
+
+Balance in controlled passes:
+
+1. Establish a simple baseline case.
+2. Test low, expected, and high-skill or high-power cases.
+3. Change one variable or one tightly coupled group at a time.
+4. Record the observed effect, not only the new value.
+5. Retest earlier cases after changing shared values.
+
+Watch for dominant strategies, dead choices, positive feedback that removes recovery, resource sources without meaningful sinks, and upgrades that erase core decisions. Prefer trade-offs and new options over upgrades that only increase every number.
+
+Use formulas as inspectable models, not as proof of fun. Validate them through play. If a value has no plausible range or target effect, the design question is still unresolved.
+
+## 6. Plan progression and content
+
+Make progression change what the player understands, chooses, or can express. Numerical growth may support progression, but should not be its only form.
+
+Introduce mechanics with this sequence when practical:
+
+**Teach → Test → Twist → Combine → Master**
+
+- Teach one idea in a low-cost situation.
+- Test whether the player can use it intentionally.
+- Twist one assumption without changing all rules at once.
+- Combine it with a previously understood idea.
+- Offer mastery through efficiency, risk, expression, or optional challenge.
+
+Plan content as a matrix of reusable variables rather than a list of isolated levels. Useful axes include space, timing, enemy role, objective, constraint, reward, and modifier. Recombine proven elements before creating new systems.
+
+For economies, list every source, sink, cap, conversion, and reset. State why the resource exists and what decision scarcity creates. Avoid currencies that merely add steps between the player and an obvious purchase.
+
+Set explicit content budgets for the current milestone: number of stages, enemy roles, upgrades, tutorials, audiovisual sets, and supported modes. Do not produce full content before the core loop, authoring pipeline, and representative content slice are validated.
+
+## 7. Design UX and accessibility with the game
+
+Treat menus, onboarding, pause, failure, restart, and settings as part of the playable loop.
+
+Define the complete state path:
+
+`launch → start → learn → play → pause/resume → result → retry or continue`
+
+Keep the current goal and available actions clear. Teach through a safe action and immediate consequence where possible; use text to clarify, not to replace interaction. Do not require the player to remember information that can remain visible or be reviewed.
+
+Establish an accessibility baseline at the start:
+
+- Support the target input methods and make essential controls remappable where feasible.
+- Provide alternatives for hold, rapid repeat, precise timing, and simultaneous inputs when those are not core challenges.
+- Keep text readable at the target display size and allow scaling when the interface needs it.
+- Do not encode critical state with color or audio alone; support captions or visual equivalents.
+- Offer control over music, effects, motion, shake, flashes, and other intense presentation as relevant.
+- Preserve settings and avoid erasing progress without confirmation.
+- Make focus, selection, disabled state, and navigation order unambiguous.
+
+Test accessibility options in real play. An option that breaks feedback, layout, timing, or progression is not complete.
+
+## 8. Control scope, risk, and playtesting
+
+### Scope around a closed loop
+
+Build the smallest slice that lets a player start, perform the core verbs, receive a meaningful result, and retry or continue. A slice is not complete when it contains many systems but no full player journey.
+
+Separate scope into:
+
+- **Must:** required to test the current design claim.
+- **Later:** valuable after the claim is validated.
+- **Not now:** explicitly excluded from the milestone.
+
+Count content and polish work, not only code. Every mechanic creates costs in UI, feedback, audio, content, onboarding, accessibility, balance, testing, and maintenance.
+
+### Attack the largest uncertainty
+
+Track risks as testable questions. Consider:
+
+- Desirability: is the loop appealing enough to repeat?
+- Comprehension: can the player form the intended model?
+- Usability: can the player perform the verbs reliably?
+- Feasibility: can the system meet technical and production constraints?
+- Content: can enough varied play be produced at an affordable rate?
+- Balance: do intended choices remain viable across progression?
+
+Prioritize high-uncertainty, high-impact risks. Build a prototype to answer one major question, not to resemble a finished game. Use disposable presentation when polished assets would not change the answer.
+
+### Run evidence-seeking playtests
+
+For each test:
+
+1. Write one primary question and the behavior that would answer it.
+2. Use a build that isolates the relevant decision when possible.
+3. Let the player act without coaching; record where intervention became necessary.
+4. Capture behavior, outcome, confusion, and recovery before asking for opinions.
+5. Separate observation from interpretation.
+6. Decide `keep`, `change`, or `inconclusive`, then name the next test.
+
+Do not ask only “Was it fun?” Ask what the player thought the goal was, why they made a choice, what they expected, and what caused a result. Prefer repeated behavioral evidence over a single stated preference.
+
+## 9. Review designs and propagate changes
+
+Review a proposed system in this order:
+
+1. Trace it to fantasy, verbs, pillars, and the core loop.
+2. Check that it creates a meaningful player decision or expression.
+3. Walk through normal, failure, interrupted, and repeated use.
+4. Check feedback, readability, fairness, and accessibility.
+5. Check tuning surfaces, content burden, dependencies, and scope.
+6. Confirm acceptance conditions and the playtest question.
+
+Classify discrepancies before editing:
+
+- **Implementation defect:** the build disagrees with the current GDD.
+- **Design change:** evidence suggests the intended behavior should change.
+- **Documentation drift:** the build and intended design agree, but the GDD is stale.
+
+For a design change, update the source GDD section first or in the same change. Then inspect and update every affected layer:
+
+`core loop → system rules → shared state → controls/camera → feedback/UI/audio → onboarding/accessibility → tuning/content → acceptance tests/tasks`
+
+Record consequential decisions with date, evidence, decision, and affected sections. Do not preserve a bad decision merely because it was previously documented; preserve the reason for changing it.
+
+Call a design increment complete only when:
+
+- The build demonstrates the intended player-facing behavior.
+- Its acceptance conditions pass in the target play environment.
+- The main uncertainty has evidence from a playtest or an explicit reason it could not yet be tested.
+- The GDD, task board, and implemented behavior agree.