unity-ecs-patterns
wshobson/agents
Reference patterns and best practices for high-performance Unity DOTS, ECS, Jobs, and Burst development.
What is unity-ecs-patterns?
This skill provides reference patterns and best practices for Unity's Data-Oriented Technology Stack (DOTS), covering Entity Component System (ECS), the Job System, and the Burst Compiler. Use it when building high-performance, data-oriented Unity games that need to efficiently manage large numbers of entities or convert existing OOP game code to ECS."
- Explains core DOTS concepts: Entity, Component, System, World, Archetype, and Chunk
- Compares ECS/DOTS against traditional OOP across data layout, memory, processing, and scaling
- Provides a references/details.md file with detailed patterns and worked examples
- Lists concrete best practices (Do's) such as using ISystem, Burst compilation, ECB for structural changes, and Aspects
- Lists common pitfalls (Don'ts) such as managed types, in-job structural changes, and native collection leaks
How to install unity-ecs-patterns
npx skills add https://github.com/wshobson/agents --skill unity-ecs-patterns- Unity project set up with the DOTS packages (Entities, Jobs, Burst) installed
- Basic familiarity with Unity development
How to use unity-ecs-patterns
- 1.Identify a performance-critical or large-scale entity system in your Unity project that could benefit from data-oriented design
- 2.Review the core ECS concepts (Entity, Component, System, World, Archetype, Chunk) provided in the skill
- 3.Consult references/details.md for detailed patterns and worked examples when the high-level guidance isn't sufficient
- 4.Apply the Do's: use ISystem, Burst-compile your code, batch structural changes with ECB, use Aspects for component grouping, and profile with the Unity Profiler
- 5.Avoid the Don'ts: managed types, structural changes inside jobs, over-architecting, poor chunk utilization, and unmanaged native collection leaks
Use cases
- Architecting a new Unity game system to handle thousands of entities efficiently
- Converting existing OOP-based Unity game code into a data-oriented ECS structure
- Optimizing CPU-bound game logic using Jobs and Burst compilation
- Diagnosing and fixing performance bottlenecks via chunk utilization and memory layout review
- Deciding whether ECS or traditional OOP is the right fit for a given game feature
- Unity game developers building high-performance or large-scale simulations
- Engineers optimizing CPU-bound game logic
- Developers converting OOP-based Unity game code to ECS architecture
- Technical leads evaluating DOTS adoption for a Unity project
unity-ecs-patterns FAQ
No, it's specifically for Unity's Data-Oriented Technology Stack (DOTS), including ECS, Jobs, and Burst, which is a different paradigm from traditional OOP-based Unity scripting.
Familiarity with Unity is assumed, but the skill explains core ECS concepts (Entity, Component, System, World, Archetype, Chunk) and provides best practices, with deeper patterns in a references file.
Use ECS when managing thousands of entities, optimizing CPU-bound logic, or building mass simulations where linear scaling and contiguous memory layout matter more than complex per-object behaviors.
The skill recommends using ISystem over SystemBase for better performance as a best practice, though it doesn't detail the full implementation differences within the SKILL.md itself.
Full instructions (SKILL.md)
Source of truth, from wshobson/agents.
name: unity-ecs-patterns description: Master Unity ECS (Entity Component System) with DOTS, Jobs, and Burst for high-performance game development. Use when building data-oriented games, optimizing performance, or working with large entity counts.
Unity ECS Patterns
Production patterns for Unity's Data-Oriented Technology Stack (DOTS) including Entity Component System, Job System, and Burst Compiler.
When to Use This Skill
- Building high-performance Unity games
- Managing thousands of entities efficiently
- Implementing data-oriented game systems
- Optimizing CPU-bound game logic
- Converting OOP game code to ECS
- Using Jobs and Burst for parallelization
Core Concepts
1. ECS vs OOP
| Aspect | Traditional OOP | ECS/DOTS |
|---|---|---|
| Data layout | Object-oriented | Data-oriented |
| Memory | Scattered | Contiguous |
| Processing | Per-object | Batched |
| Scaling | Poor with count | Linear scaling |
| Best for | Complex behaviors | Mass simulation |
2. DOTS Components
Entity: Lightweight ID (no data)
Component: Pure data (no behavior)
System: Logic that processes components
World: Container for entities
Archetype: Unique combination of components
Chunk: Memory block for same-archetype entities
Detailed patterns and worked examples
Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.
Best Practices
Do's
- Use ISystem over SystemBase - Better performance
- Burst compile everything - Massive speedup
- Batch structural changes - Use ECB
- Profile with Profiler - Identify bottlenecks
- Use Aspects - Clean component grouping
Don'ts
- Don't use managed types - Breaks Burst
- Don't structural change in jobs - Use ECB
- Don't over-architect - Start simple
- Don't ignore chunk utilization - Group similar entities
- Don't forget disposal - Native collections leak
Related skills
More from wshobson/agents and the wider catalog.
tailwind-design-system
Build production-ready design systems with Tailwind CSS v4, design tokens, and component libraries.
typescript-advanced-types
Master TypeScript's advanced type system: generics, conditional types, mapped types, and utility types for type-safe applications.
nodejs-backend-patterns
Build production-ready Node.js backends with Express/Fastify, middleware patterns, auth, and database integration.
python-performance-optimization
Profile and optimize Python code using cProfile, memory profilers, and performance best practices.
brand-landingpage
Brand-first landing page designer with guided interviews and Stitch-powered iteration.
python-testing-patterns
Implement comprehensive testing strategies with pytest, fixtures, mocking, and test-driven development.