Cursor Rules for Unity: Scenes, Assets, and C# Scripts

Cursor rules for Unity tell the assistant how your project organizes scenes and assets, where C# scripts belong, which MonoBehaviour patterns your team uses, and what a playtest check looks like. Unity projects accumulate decisions about folder layout, component design, and scene management that an assistant has no way to infer from a single file.

fenbs fills the gap that the rule file cannot: the gameplay decisions made during design sessions, the current state of each feature task, and where the last session left the work. The rule handles the static conventions; fenbs handles the live context.

What Unity rules should cover

Unity development mixes code, assets, and scene configuration. An assistant touching one can inadvertently break another. Rules that separate these concerns and name the conventions for each give the assistant guardrails that fit the Unity workflow rather than generic C# guidance.

• Folder structure: where scripts, prefabs, scenes, materials, and audio assets live.
• Script conventions: namespace usage, MonoBehaviour lifecycle method order, and serialization rules.
• Scene changes: whether scene files should be edited directly or through prefab instantiation.
• Asset naming: the naming convention for prefabs, materials, animations, and scriptable objects.
• Playtesting: what constitutes a playtest check for a gameplay change.

Scene and asset organization

Unity projects grow complex quickly when everyone follows different folder conventions. An assistant that does not know where prefabs live will create them in a convenient location rather than the correct one. A rule that maps your folder layout prevents scattered assets and makes the project easier to navigate for both people and assistants.

Asset naming is equally important. A prefab named Player and one named PlayerPrefab in different folders create confusion. State the convention once in the rule and the assistant follows it consistently from the first task.

---
description: Unity project conventions
globs: "**/*.cs,**/*.unity,**/*.prefab,**/*.asset"
alwaysApply: false
---

## Folder structure
- Scripts: `Assets/Scripts/` with subdirectories by system (Player, UI, Enemies, Managers).
- Prefabs: `Assets/Prefabs/` with subdirectories matching the script hierarchy.
- Scenes: `Assets/Scenes/`; the active scene is the one named in the current task.

## Scripts
- Namespace: `GameName.SystemName` (e.g., `MyGame.Player`, `MyGame.UI`).
- MonoBehaviour lifecycle order: Awake → OnEnable → Start → Update → FixedUpdate → OnDisable → OnDestroy.
- Serialize fields with `[SerializeField]` rather than making them public.
- Never use `GameObject.Find` at runtime; inject references through the Inspector or a ServiceLocator.

## Assets
- Prefabs use PascalCase without a "Prefab" suffix (e.g., `EnemySpawner`, not `EnemySpawnerPrefab`).
- Materials: `M_` prefix (e.g., `M_PlayerSkin`).

## Playtesting
- Any change to player movement, physics, or core gameplay requires an in-editor playtest before the task is done.
- Record the playtest result in the fenbs task note.

C# script conventions

Unity C# has a specific runtime context that differs from ordinary C# applications. GameObject.Find is a common source of performance problems at runtime. [SerializeField] is the correct way to expose a private field to the Inspector. Awake and Start have different guarantees about execution order. Rules that cover these Unity-specific patterns prevent the assistant from writing code that is valid C# but problematic in a Unity context.

The lifecycle order also matters for serialization. Fields marked with [SerializeField] are set by Unity before Awake runs. Code that reads those fields in the constructor, or that assumes they are populated before Awake, will fail in ways that are confusing to trace. A rule that states the lifecycle order and when each initialization step is safe removes that confusion for an assistant that may otherwise use the order that looks natural from a C# perspective.

A rule that also specifies namespace conventions keeps the project consistent as it grows. Scripts in different directories that share a namespace are easier to search and refactor. An assistant that knows the naming scheme follows it from the first new script.

Coroutines are another area where Unity-specific guidance helps. An assistant without a rule may start a coroutine in Update and create hundreds of them per second, or forget to stop a coroutine when the object is disabled. A line in the rule that says "check existing coroutines before starting a new one, and always stop them in OnDisable" prevents a class of subtle gameplay bugs that are hard to reproduce and trace.

The Inspector dependency pattern deserves a rule too. When a MonoBehaviour needs a reference to another component or a prefab, the clean approach is to expose a serialized field and assign it in the Inspector rather than using GetComponent in Awake or Find at runtime. That approach is explicit, visible, and testable. A rule that states the preference removes the ambiguity of which approach the assistant should use for a new component.

Gameplay decisions across sessions

Unity game development involves many decisions that are not visible in the code: the target feel for player movement, the approved enemy difficulty curve, the camera behavior that was tested and accepted. An assistant starting a new session has no way to recover those decisions from the project files.

Recording them as Decisions in fenbs solves this. When the team agrees that double-jump should have a specific arc or that enemy spawn rates should follow a particular progression, that decision goes into fenbs with the reason. The next assistant reads it before touching the related system.

How to set up Unity rules with fenbs

1. Create a free account and add your game project.
2. Record the approved gameplay decisions in fenbs: core mechanic parameters, system boundaries, any design choices made during testing.
3. Place the .cursor/rules/unity.mdc file at the project root and adjust the folder paths, namespace pattern, and asset prefix conventions to match your project.
4. Connect Cursor via Integrations and ask it to read the project context before starting work on any gameplay system.
5. Before ending a session, save progress on each task in fenbs: what was completed, what was playtested, and what needs to happen next.

For connecting Unity's own tooling to your AI workflow, see Unity MCP. For more rule patterns, see cursor rules examples and cursor rules for AI projects. For managing multiple rule files in a complex project, see cursor rules hierarchy.