Home › Unity (C#) › Unity DOTS / ECS rules
Unity DOTS / ECS rules
Cursor rules for Unity Entities 1.x (DOTS): baking, ISystem with Burst, jobs, IJobEntity, and structural changes.
CursorUnity (C#)
How to use
Save this as .cursor/rules/unity-dots.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.
.cursor/rules/unity-dots.mdcDownload ---
description: Unity DOTS / ECS conventions
globs: ["Assets/**/*.cs"]
alwaysApply: false
---
# Unity DOTS (Entities 1.x)
- Authoring MonoBehaviours + `Baker<T>` convert GameObjects in SubScenes to entities. Runtime code never touches GameObjects for ECS data.
- Components are small unmanaged `struct`s implementing `IComponentData` (or `IBufferElementData`, `IEnableableComponent`). No managed types in hot-path components.
- Systems are `partial struct` implementing `ISystem` with `[BurstCompile]` on `OnCreate`/`OnUpdate`. Use `SystemBase` only when managed code is unavoidable.
- Declare requirements in `OnCreate` (`state.RequireForUpdate<GameConfig>()`) and read singletons via `SystemAPI.GetSingleton<T>()`.
- Iterate with `foreach (var (transform, speed) in SystemAPI.Query<RefRW<LocalTransform>, RefRO<Speed>>())` for simple cases; schedule `IJobEntity` (`new MoveJob { Dt = SystemAPI.Time.DeltaTime }.ScheduleParallel()`) for heavy work.
- Use `RefRO` when you only read, so the job scheduler can parallelize.
- Structural changes (create/destroy/add/remove components) go through an `EntityCommandBuffer` from `BeginSimulationEntityCommandBufferSystem.Singleton`, using `.AsParallelWriter()` in parallel jobs.
- Prefer enableable components over adding/removing tags every frame.
- Order systems with `[UpdateInGroup]`, `[UpdateBefore/After]`.
- Native containers allocated with the right `Allocator` and disposed (or `Allocator.Temp` inside a frame).
## Done when
No Burst compile errors or safety-system exceptions in Play mode, and the Entities Profiler shows the new systems within budget.