game-systems-design
Skill2 starsChanged 4 months agoMITView on GitHub
Models engine-agnostic games as interacting parts, state, relationships, feedback, and core/meta loops. Use for cross-system architecture, feedback-loop diagnosis, system boundaries, player mental models, systemic prototypes, and design specifications; defer individual mechanic selection to game-mechanics-design and numerical tuning to game-balance.
In this repository14 other files it gives its agents.
- game-balanceSkill
- game-design-vocabularySkill
- gamedev-mathSkill
- game-mechanics-designSkill
- godot-2d-gameplaySkill
- godot-3d-gameplaySkill
- godot-desktop-appsSkill
- godot-fundamentalsSkill
- godot-game-architectureSkill
- godot-mobileSkill
- godot-navigation-aiSkill
- godot-procedural-generationSkill
- godot-programming-patternsSkill
- godot-uiSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
26 rules. About 0 are common, 26 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈26
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Treat the system boundary as a design choice made for a specific question and time horizon.
- Distinctive: line 24
Prefer a few reusable rules with meaningful interactions over many exceptions.
- Distinctive: line 26
Treat playtest comments as evidence of an experience or problem, not automatically as the correct solution.
- Distinctive: line 27
Keep intent, model, prototype, implementation, and current evidence traceable to one another.
- Distinctive: line 42
Do not block on unavailable information.
- Distinctive: line 48
Write a compact target before drawing the system:
- Distinctive: line 64
Use System Modeling for the boundary worksheet, part inventory, relationship map, feedback analysis, and worked example.
- Distinctive: line 66
Avoid silently mixing scales.
- Distinctive: line 78
Remove decorative nouns that do not participate in the question.
- Distinctive: line 93
Check reinforcing loops for runaway advantage, compounding scarcity, and irreversible decline.
- Distinctive: line 116
If the core loop is enjoyable but the meta loop is compulsory bookkeeping, simplify the meta loop.
- Distinctive: line 126
Ask whether a new player can notice the cue, connect it to the correct cause, predict a useful consequence, and recover from a wrong model.
- Distinctive: line 128
Do not solve a communication problem by adding explanation alone.
- Distinctive: line 132
Test the model on paper with representative traces:
- Distinctive: line 141
When a symptom appears, trace backward through relationships before changing a number.
- Distinctive: line 147
Use Prototyping and Playtesting to write the hypothesis card, test script, observation sheet, mental-model probes, and iteration record.
- Distinctive: line 149
Every gameplay prototype must let a player form an intent, act, receive a state-dependent result, and choose again.
- Distinctive: line 153
Run short tests early. Observe before explaining.
- Distinctive: line 161
Ask prediction and explanation questions, not only preference questions.
- Distinctive: line 178
Use Design Communication for the one-page brief, system specification, decision log, diagram notation, and handoff checks.
- Distinctive: line 185
Test evidence and unresolved risks for decision makers.
- Distinctive: line 187
Keep documents current. Mark proposals, tested behavior, and shipped behavior distinctly.
- Distinctive: line 220
Before presenting a design as ready:
- Distinctive: line 222
Every important state has an owner, unit or category, initial condition, and bound.
- Distinctive: line 223
Every state change has a rule, trigger, and destination.
- Distinctive: line 224
Every important loop closes or intentionally exits the boundary.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Game Systems Design
Design the behavior of a game across time, not just a list of features. Connect the intended player experience to explicit state, rules, feedback, and evidence.
Remain engine-agnostic. Express behavior with state tables, equations, diagrams, transition rules, and pseudocode unless the user names an implementation environment.
Core Principles
- Treat the system boundary as a design choice made for a specific question and time horizon.
- Model parts by their state and behavior, then model the relationships that let those parts change one another.
- Distinguish reinforcing feedback, which amplifies change, from balancing feedback, which opposes deviation. Neither is inherently good or bad.
- Define a core loop as the repeated intent-action-state change-feedback cycle holding the player's immediate attention.
- Define a meta loop as a slower cycle that changes the conditions of future core-loop attempts, sessions, or chapters.
- Separate game truth, player-visible evidence, and the player's likely interpretation. A rule the player cannot infer cannot reliably support planning.
- Prefer a few reusable rules with meaningful interactions over many exceptions.
- Prototype the riskiest assumption before polishing or expanding the system.
- Treat playtest comments as evidence of an experience or problem, not automatically as the correct solution.
- Keep intent, model, prototype, implementation, and current evidence traceable to one another.
Intake
Inspect existing design notes, data, diagrams, builds, tests, and constraints before proposing a replacement. Establish as much of the following as the task needs:
- Player promise: role, desired decisions, emotions, and mastery.
- Audience and context: expected knowledge, session length, player count, and competitive or cooperative setting.
- Design question: the uncertainty or failure being addressed.
- Scope: one encounter, a session, persistent progression, or the full game.
- Current system: parts, rules, resources, interfaces, and known dependencies.
- Constraints: production budget, content budget, accessibility, platform, networking, persistence, and business rules.
- Evidence: observations, playtest notes, telemetry, simulations, or only assumptions.
- Required deliverable and audience.
Do not block on unavailable information. State consequential assumptions, mark unknowns, and identify what evidence would resolve them.
Workflow
1. Frame the Intended Experience
Write a compact target before drawing the system:
The player repeatedly [decision/action] to pursue [goal].
The interesting tension is [tradeoff or uncertainty].
The player should learn [model] and eventually master [skill].
Success looks like [observable behavior or result].
The design must avoid [failure experience].Translate vague qualities into behavior. Replace "deep crafting" with claims such as "players choose among at least two contextually useful recipes and can explain why each fits a different need."
2. Set the Boundary and Time Scales
Name what is inside, outside, and crossing the boundary. Specify the smallest meaningful time step and the longest horizon relevant to the question.
Use System Modeling for the boundary worksheet, part inventory, relationship map, feedback analysis, and worked example.
Avoid silently mixing scales. A one-second combat reaction, a ten-minute encounter, and a ten-session upgrade cycle may interact, but each needs its own state and cadence.
3. Inventory Parts and Relationships
For every relevant part, record:
- State: mutable values, units, initial values, and bounds.
- Behavior: what it can sense, decide, create, consume, convert, or communicate.
- Ownership: which rule is allowed to change its state.
- Visibility: what the player sees and when.
- Relationships: what crosses to another part, under which condition, and after what delay.
Remove decorative nouns that do not participate in the question. Add missing nonphysical parts such as time, attention, capacity, threat, reputation, or turn order when they materially change behavior.
4. Close and Classify Feedback
Trace every important output until it either leaves the boundary or returns to affect an earlier state.
For each closed path:
- Name the player-facing purpose.
- Mark each relationship as same-direction or opposite-direction.
- Classify the loop as reinforcing or balancing.
- Mark delays, thresholds, caps, and nonlinear regions.
- Identify who can perturb the loop and what feedback exposes the result.
- Predict failure at low, normal, high, and adversarial values.
Check reinforcing loops for runaway advantage, compounding scarcity, and irreversible decline. Check balancing loops for sluggishness, oscillation, hidden compensation, and removal of earned advantage.
5. Connect Core and Meta Loops
Describe the core loop with verbs, not feature names:
read situation -> choose -> act -> resolve -> perceive result -> choose againDescribe every slower loop separately:
complete attempt -> earn or lose persistent resources -> invest -> alter future options -> begin next attemptThen identify each bridge between them. A bridge should explain:
- What leaves the core loop.
- How the meta loop transforms or stores it.
- What returns to a later core loop.
- Whether it expands decisions, merely raises numbers, or invalidates earlier learning.
If the core loop is enjoyable but the meta loop is compulsory bookkeeping, simplify the meta loop. If the meta loop makes the next core attempt automatic, cap or redirect its power.
6. Design the Player's Mental Model
For each decision-critical rule, complete this chain:
game state -> perceivable cue -> player interpretation -> prediction -> action -> confirming or correcting feedbackAsk whether a new player can notice the cue, connect it to the correct cause, predict a useful consequence, and recover from a wrong model. Preserve uncertainty only when reasoning under uncertainty is part of play.
Do not solve a communication problem by adding explanation alone. First improve rule consistency, state visibility, cause-and-effect timing, and feedback hierarchy.
7. Diagnose the System Before Adding Content
Test the model on paper with representative traces:
- First-use trace: no prior knowledge or upgrades.
- Typical trace: expected skill and resources.
- Expert trace: optimized choices and high execution.
- Recovery trace: player begins behind or makes a costly mistake.
- Saturation trace: caps, endgame stocks, and mature strategies.
- Adversarial trace: hoarding, stalling, collusion, degenerate loops, or repeated exploitation.
When a symptom appears, trace backward through relationships before changing a number. The visible failure may be several links away from its cause.
8. Prototype One Uncertainty
Choose the cheapest medium that preserves the interaction being tested: paper, cards, spreadsheet, scripted moderator, small simulation, or interactive digital build.
Use Prototyping and Playtesting to write the hypothesis card, test script, observation sheet, mental-model probes, and iteration record.
Every gameplay prototype must let a player form an intent, act, receive a state-dependent result, and choose again. A noninteractive model can test internal dynamics, but it cannot validate the play experience.
9. Playtest and Reconstruct Understanding
Run short tests early. Observe before explaining. Capture separately:
- What happened.
- What the player appeared to believe.
- What the player later said.
- What the system recorded.
- What interpretation the team draws.
Ask prediction and explanation questions, not only preference questions. For example: "What do you expect that choice to change?" and "How would you get a different result next time?"
Compare fresh players with returning players. Fresh players reveal learnability; returning players reveal depth, adaptation, and whether earlier knowledge remains useful.
10. Revise at the Correct Level
Choose the smallest change that addresses the diagnosed cause:
- Part level: value, bound, state, or local behavior.
- Relationship level: rate, condition, delay, direction, or visibility.
- Loop level: missing brake, weak reward, deadlock, or disconnected bridge.
- Whole-experience level: the system produces a coherent result that does not match the intended game.
Change one causal bundle at a time. Record the hypothesis, expected result, observed result, and decision. Re-run prior edge traces after each structural change.
11. Communicate the Current Design
Use Design Communication for the one-page brief, system specification, decision log, diagram notation, and handoff checks.
Layer the deliverable:
- One-page intent and loop summary for alignment.
- System map and state rules for design review.
- Data definitions and acceptance checks for implementation.
- Test evidence and unresolved risks for decision makers.
Keep documents current. Mark proposals, tested behavior, and shipped behavior distinctly.
Diagnostic Signals
- Feature inventory, no system: nouns are listed, but no state-changing relationships close into loops. Add behaviors and trace change over time.
- Unclear boundary: the model grows whenever a question is asked. Restate the decision and horizon; convert external detail into explicit inputs or outputs.
- Runaway leader: success increases the ability to secure more success faster than counterplay develops. Add costs, exposure, saturation, alternate routes, or a contextual balancing loop.
- Failure spiral: losing removes the means to recover. Protect a minimum action budget, create a risky recovery route, or make setbacks change strategy rather than end agency.
- Oscillation: a correction repeatedly overshoots its target. Reduce gain, shorten or expose delay, widen tolerance, or damp the response.
- Dominant path: one option is best across contexts. Add a real tradeoff or distinct context; do not hide superiority behind complexity.
- Core/meta disconnect: rewards do not change later decisions, or persistent power trivializes the core. Redesign the bridge rather than adding another currency.
- Mental-model break: similar actions yield inexplicably different outcomes. Remove exceptions, expose conditions, or make feedback more causal.
- Simulation without play: internal dynamics look healthy, but the player has no meaningful intervention. Add decision points and observable consequences.
- Playtest theater: the prototype is polished but no decision would change from the result. State a falsifiable question before testing.
- Stale specification: implementation and documentation disagree. Reconcile them and identify which is authoritative before further iteration.
Required Deliverables
Unless the user asks for a narrower artifact, produce:
- Experience target and explicit assumptions.
- Boundary, time scales, and dependency list.
- Part/state/behavior inventory.
- Relationship and feedback-loop map.
- Core loop, meta loop, and bridge descriptions.
- Player mental-model and feedback plan.
- Prototype or playtest plan tied to one uncertainty.
- Diagnostics, failure risks, and edge traces.
- Verification criteria and current evidence.
- Decision log or recommended next experiment.
Verification
Before presenting a design as ready:
- Every important state has an owner, unit or category, initial condition, and bound.
- Every state change has a rule, trigger, and destination.
- Every important loop closes or intentionally exits the boundary.
- Reinforcing loops have known limits; balancing loops have a target and acceptable response time.
- Core and meta loops exchange explicit state without invalidating the intended decisions.
- Decision-critical state has timely, distinguishable feedback.
- A player can state a useful prediction after limited exposure.
- At least one typical, edge, recovery, and exploit trace has been checked.
- The prototype tests the stated uncertainty at appropriate fidelity.
- Evidence is separated from inference, and unknowns remain labeled.
- The communication artifact is precise enough for its audience to make or implement the next decision.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

