> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/best-practices/development-methodology.md). # Development Methodology The most common reason an AI-assisted game feels generic is not the AI: it is the absence of design. When you skip the design phase and go straight to building, the AI fills every gap you leave with the most statistically average version of what you asked for. The result works but it feels like nothing in particular. The fix is not a better prompt. It is doing the design work first. ## **Design Before You Build** ### **Design the game before you touch Cursor** One-shotting a game, describing a concept to the AI and asking it to build the whole thing, produces a technically functional result with no identity. The AI will make every creative decision you did not: what the movement feels like, how combat is paced, what the feedback loop rewards, what the game actually is. Those decisions will be correct on average and wrong for your game specifically. The alternative is to design before you build. This does not require a formal document. It requires you to answer the questions the AI would otherwise answer for you: What does playing this feel like? What is the moment-to-moment loop? What happens when the player succeeds and when they fail? What makes this game different from the obvious version of the same idea? Write these down. Not for the AI: for yourself. The act of writing them forces decisions that vague ideas let you avoid. ### **Take reference seriously** Every game worth playing was designed with reference. The designers of the games you love were thinking about the games they loved. Reference is not copying: it is understanding why something works and applying that understanding to your own context. Before building anything, play the games closest to what you are making. Note specifically what they do: how fast things move, how long actions take, when the game gives feedback and what kind, what the camera does, how difficulty is introduced. Write down the specific things you want your game to borrow and the specific things you want to do differently. This reference material becomes part of your brief to the AI. “The combat should feel like X in this game: tight, committed, no input buffering” is a directive the AI can work with. “Make the combat feel good” is not. ### **Turn your design into an AI brief** Once your design is clear, a document transforms how your AI sessions go. Instead of exploring what to build, you are directing how to build it. The AI stops making creative decisions and starts executing yours. Your brief does not need to be long. It needs to answer: what is the game, what is the core loop, what are the key systems, and what does each system need to feel like. Paste the relevant section at the start of each session. The AI will use it as its reference point for every decision it makes. {% hint style="info" %} *TIP: Keep your design brief in a single file in your project, something like DESIGN.md. Reference it with @DESIGN.md at the start of any session where creative decisions matter. The AI will anchor its choices to your intentions rather than making its own.* {% endhint %} ## **Build and Verify Incrementally** ### **Build incrementally, not all at once** The most reliable development pattern for AI-assisted games is: design one thing, build it, verify it feels right, then move to the next. This sounds slow. It is actually faster, because errors do not compound. When you build multiple systems at once, a problem in one propagates into everything built on top of it. Finding it requires unwinding code the AI wrote in a dozen different sessions. Building incrementally means each piece is confirmed correct before the next relies on it. A bug has nowhere to hide. The practical application: build your core loop first. Get the single most important thing, whether that is player movement, the core combat action, or whatever the game is fundamentally about, to a state where it feels right before you build anything else. Everything else in the game will be influenced by that foundation. If it is wrong, everything is wrong. {% hint style="warning" %} *NOTE: "Feels right" is not a technical standard: it is a design one. Before moving on from any system, play it. Ask whether it matches your reference and your brief. The AI cannot tell you whether the movement feels good. Only you can.* {% endhint %} ### **Verify before you extend** Each feature is a checkpoint. Build it, play it, confirm it works as designed, then use it as the foundation for the next thing. Never build on top of something you have not verified. This discipline matters more in AI-assisted development than in hand-coded development, because the AI produces working-looking code that can contain wrong assumptions about your design. Code that compiles and runs is not the same as code that does what your game needs. The verification step is where you catch the difference. If something does not feel right at this stage, fix it before continuing. The cost of correcting a wrong foundation grows with every system built on top of it. ### **Keep a playable state at all times** At every point in development, you should have a version of the game you can upload, share, and play. This is not just good practice: it is your primary feedback mechanism. Use Sandbox Studio’s unpublished draft state to keep a live, shareable build available. Upload frequently. Send it to people. Play it yourself in the browser, not just in the editor. The game feels different when it is running as a player would experience it, and that difference surfaces problems that editor testing does not. {% hint style="info" %} *TIP: Treat each completed feature as a release candidate. Once verified, upload it. You now have a known-good **Git** commit to return to if the next session introduces a problem. Re-upload **overwrites** the hosted files; the editor does not keep an upload history you can restore. See* [*Updating and unpublishing your game*](/publishing/updating-and-unpublishing-your-game.md)*.* {% endhint %} ## **Working with the AI Across a Full Project** The sessions that produce the best results follow a consistent shape: open with the design brief and handover context, plan before building, verify before extending, close with a handover summary. Each session should cover one system or one well-defined part of a system. Use the right model for the work: planning and architectural decisions warrant a capable model; implementation following a clear plan can go to a lighter one. Save the most capable models for problems that genuinely resist everything else. When a session produces something that does not match your design brief, the fix is almost always in the brief. Either it was ambiguous, or it did not include the reference that would have pointed the AI in the right direction. Tighten the brief before starting the next session rather than correcting mid-stream. {% hint style="info" %} *TIP: At the end of any session that moved the design forward, update your DESIGN.md to reflect the decisions that were made. The brief is a living document. It should always reflect the current state of the game, not the state it was in when you started.* {% endhint %} ## **Practical Guidance** * Write your design before opening Cursor. The AI fills every gap you leave: fill them yourself first. * Use reference games deliberately. Note specifically what they do and what you want to borrow or do differently. * Keep your design brief in a single file and reference it with @ at the start of every session where creative decisions matter. * Build the core loop first and verify it feels right before building anything that depends on it. * One system per session. Verify it works before the next session builds on top of it. * Upload and play in the browser regularly, not just in the editor. The game feels different to a player and that difference matters. * Use the unpublished draft state as your running build. Upload after every verified feature so testers always have the latest files. Keep Git checkpoints so you can restore the project on disk; the host only stores the last finished upload. * Use the right model for the task: lighter models for implementation once the plan is clear, mid-tier for planning and architecture, upper tier for problems that resist everything else. * Update your design brief as the game evolves. It is your primary reference: keep it accurate. ## **Common Mistakes** | Mistake | What to do instead | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Describing a concept to the AI and asking it to build the whole thing | Design the game first: the AI executes your decisions, not its own | | Starting to build before the core loop is defined | Write down what the moment-to-moment experience should feel like before a single line of code is written | | Using vague creative direction ("make it feel good") | Use specific reference: name the game, name the mechanic, describe what specifically you are borrowing | | Building multiple systems at once | One system at a time; verify each before extending | | Testing only in the editor | Upload regularly and test in the browser: player experience and editor experience are different | | Treating the design brief as a one-time document | Update it as the game evolves; stale briefs produce sessions that drift from the game’s actual direction | | Moving to the next feature before the current one feels right | Verify against your design brief and your reference before moving on: fixing a wrong foundation costs more than taking the time now | ## **The AI Is a Builder, Not a Designer** The design is yours. The games that come out of AI-assisted development with a real identity are the ones where a creator made every meaningful creative decision before the first prompt was written, and kept making those decisions throughout. The AI’s job is to execute that design as precisely as possible. Your job is to give it one worth building. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://studio-docs.sandbox.game/best-practices/development-methodology.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.