Cursor Rules

Cursor Rules are a feature of Cursor AI that let you define project-specific guidelines for code generation. By storing these guidelines in .mdc (Markdown Cursor) files, you can ensure the AI consistently follows your coding styles, ECS patterns, and architecture rules—particularly useful in Viber3D or any ECS-based React project.

Introduction

When building a 3D game or any application, it's crucial to maintain consistent styles and best practices. Cursor Rules provide a centralized way to instruct the AI about your project's needs:

• ECS architecture guidelines
• React Three Fiber best practices
• Trait naming conventions
• System structure (pure functions, minimal side effects)
• Directory layouts (e.g., src/components, src/systems, etc.)

This is especially handy if multiple developers or AI instances are collaborating on the same codebase.

What Are Cursor Rules?

Cursor Rules come in two varieties:

1. Global Rules: Applied to all projects on your machine via Cursor's global settings.
2. Project Rules: Kept in .cursor/rules/*.mdc within your project. These are more specific to your current codebase or framework (e.g. "Use ECS with Koota," "Use useTraitEffect for trait-based triggers," etc.).

.mdc stands for Markdown Cursor, indicating these rules are written as Markdown with some extra front matter for metadata (like description: and globs:).

Example MDC File

---
description: React Component Rules
globs: *.tsx
---

# React Component Guidelines
- Use functional components
- Implement ECS data flow with Koota (no direct game logic in components)
- Keep all game logic in systems, not `useFrame`

Project Rules and .mdc Files

In your Viber3D game, you'll see a .cursor/rules directory containing .mdc files, for example:

.cursor/
└── rules/
    ├── base.mdc
    ├── components.mdc
    ├── systems.mdc
    ├── traits.mdc
    └── utils.mdc

Each file has:

• Front matter: fields like description and globs.
• Markdown content: sets out the code style, architecture, or other guidelines.

When Cursor AI processes your code, if your open file matches a .mdc rule's globs (e.g. *.ts, src/components/**/*.tsx), it automatically includes that rule's content into the conversation context. As a result, the AI's suggestions will better align with your instructions.

Typical Fields

• description: Summarizes what the rule is about.
• globs: Indicates which files or directories it applies to (src/components/**/*.tsx, *.md, etc.).
• alwaysApply: (Optional) If set true, the rule is always used.
• Then a Markdown body explaining your guidelines, best practices, do's/don'ts, or code examples.

How They're Used in Viber3D

In a typical Viber3D project:

1. ECS Systems need certain constraints: pure functions, minimal side effects, delta-based movement, etc.
2. React Components should avoid game logic (only visuals).
3. Traits should remain small and data-focused.
4. Directory Structure might follow the pattern src/{components, systems, traits, utils}.

All these guidelines can go into .mdc files. For instance:

• base.mdc might state overarching ECS + R3F principles.
• components.mdc can specify that "Components must not contain ECS logic" and "Use useTraitEffect only for visual triggers."
• systems.mdc can define how you structure your system files (export const functionName = (world: World) => { ... }).
• traits.mdc can detail how to define trait({ ... }) objects for data.
• utils.mdc might outline your best practices for math or utility modules.

During development, whenever you open or modify a file that matches the rule's glob pattern, Cursor AI automatically includes those rules. As you ask for code suggestions or expansions, the AI will do so in alignment with your .mdc definitions.

Creating or Editing Cursor Rules

1. Open the Command Palette (Cmd+Shift+P on macOS) and choose "New Cursor Rule."
2. Name your file and specify the globs.
3. Write the guidelines in the Markdown body. Provide bullet points, code samples, or detailed instructions.
4. Commit it to version control so your team shares the same rules.

You can also edit existing .mdc files in .cursor/rules at any time.

Benefits of Cursor Rules

1. Consistency: The AI's code suggestions remain consistent with your ECS architecture, naming conventions, or React style.
2. Productivity: Faster code generation that needs fewer manual fixes.
3. Team Alignment: Everyone on the project sees the same .mdc rules, ensuring uniform coding standards.
4. Reduced Errors: By embedding best practices (e.g. "do not mix ECS logic in React components"), you reduce logic bugs.

Example Use Cases

• Framework-Specific: Mandating SolidJS or React patterns for *.tsx.
• Auto-Generated Files: Telling Cursor not to modify .proto or .glb files.
• Folder-Specific: For src/systems/**/*.ts, always mention a "pure system, no side effects" approach.
• UI Patterns: Ensuring usage of Tailwind classes for styling, or restricting inline styles.

Best Practices

• Keep rules clear and concise.
• Provide code examples in the markdown.
• Use globs to apply the rule only where relevant.
• Keep them up to date as your team's conventions evolve.

Conclusion

Cursor Rules—and the .mdc files that store them—offer a powerful way to guide the Cursor AI so it consistently follows your Viber3D game's coding patterns. Whether you're enforcing ECS best practices, React Three Fiber do's and don'ts, or file-based architecture rules, well-crafted .mdc rules can greatly improve your development flow.