# Unity Physicscore2d Batching

> Unity Physicscore2d Batching is an Agent Skill for development published in the Unity-Technologies/PhysicsExamples2D repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Batching techniques for queries, projectiles/shooters, and swarm/flocking behaviors (boids)

- Skill name: `unity-physicscore2d-batching`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/Unity-Technologies/PhysicsExamples2D/blob/HEAD/.claude/skills/unity-physicscore2d-batching/SKILL.md
- Repository: Unity-Technologies/PhysicsExamples2D (730 GitHub stars when collected)

## SKILL.md

# Unity PhysicsCore2D Batching Expert

You are now acting as a Unity PhysicsCore2D batching expert, specialized in optimizing performance through batching techniques.

## Overview

Batching operations in PhysicsCore2D significantly improves performance:
- **Body creation batching** - Create many bodies at once
- **Query batching** - Perform multiple queries efficiently
- **Projectile systems** - Efficient bullet management
- **Swarm behaviors** - Flocking and boids simulation
- **Batch updates** - Update many bodies together

## Repository Examples

Reference examples from the PhysicsExamples2D repository:
- **Boids** - https://github.com/Unity-Technologies/PhysicsExamples2D/blob/master/Sandbox/Assets/Examples/Boids.cs
- **Queries** - https://github.com/Unity-Technologies/PhysicsExamples2D/blob/master/Sandbox/Assets/Examples/Queries.cs
- **Shooter** - https://github.com/Unity-Technologies/PhysicsExamples2D/blob/master/Sandbox/Assets/Examples/Shooter.cs

## Batch Creation

### Creating Bodies in Batches
Use `PhysicsBody.CreateBatch` instead of loops:
- Single allocation for all bodies
- Faster than individual CreateBody calls
- Returns NativeArray of bodies
- Must dispose array properly

**Example:**
```csharp
// Create 1000 bodies at once
var bodyDefinition = PhysicsBodyDefinition.defaultDefinition;
var bodies = PhysicsBody.CreateBatch(world, bodyDefinition, 1000, Allocator.Persistent);

// Dispose when done
PhysicsBody.DestroyBatch(bodies);
bodies.Dispose();
```

### Batch Shape Creation
Create shapes for multiple bodies efficiently:
- Reuse shape definitions
- Batch similar geometries
- Minimize individual CreateShape calls

## Query Batching

### Multiple Overlap Queries
Perform many overlap tests efficiently:
- Batch query allocations
- Process results together
- Reduce GC allocations
- Use job system for parallel processing

### Raycast Batching
Cast multiple rays in one operation:
- Single native array for results
- Parallel processing
- Useful for projectile hit detection
- Line-of-sight checks

### Spatial Queries
Query multiple areas simultaneously:
- Find all bodies in multiple regions
- Batch circle/box overlap tests
- Cache frequently used queries

## Projectile Systems

### Bullet Pool Management
Efficient projectile handling:
- Pre-create bullet bodies
- Reuse inactive projectiles
- Enable/disable instead of create/destroy
- Batch position updates

**Shooter system pattern:**
1. Create bullet pool at startup
2. Disable unused bullets
3. Enable and position when firing
4. Disable bullets on impact or timeout
5. Reuse from pool

### Trajectory Updates
Update many projectiles together:
- Batch velocity calculations
- Parallel processing
- Collision detection batching
- Culling inactive projectiles

## Swarm and Flocking (Boids)

### Boid Simulation
Simulate many agents efficiently:
- Batch neighbor queries
- Calculate flocking rules in parallel
- Update all boid positions together
- Use spatial partitioning

**Flocking behaviors:**
- **Separation** - Avoid crowding neighbors
- **Alignment** - Steer toward average heading
- **Cohesion** - Move toward average position

### Spatial Partitioning
Optimize neighbor searches:
- Grid-based partitioning
- Hash spatial grid
- Reduce query complexity
- Update partitioning incrementally

### Boid Optimization
- Limit neighbor search radius
- Update boids in groups
- Use LOD for distant boids
- Cull off-screen boids

## Batch Updates

### Transform Synchronization
Update many transforms at once:
- Batch GetPosition/GetRotation calls
- Parallel transform updates
- Reduce overhead
- Job system integration

### Property Updates
Modify multiple bodies together:
- Batch velocity changes
- Mass updates
- Layer changes
- Flag modifications

## Performance Patterns

### Object Pooling
Reuse physics bodies:
- Pre-create object pools
- Disable instead of destroy
- Reset properties when reusing
- Batch activation/deactivation

### Job System Integration
Parallelize operations:
- Use Unity Jobs for batch processing
- Process bodies in parallel
- Calculate forces in jobs
- Update results together

### Memory Management
Minimize allocations:
- Use NativeArray with Persistent allocator
- Reuse arrays across frames
- Batch disposal operations
- Pool query result arrays

## Best Practices

### Body Batching
- Always use batch creation for > 10 bodies
- Specify correct allocator lifetime
- Dispose batched arrays properly
- Reuse definitions in batches

### Query Optimization
- Batch similar query types together
- Cache query results when possible
- Use appropriate query bounds
- Avoid redundant queries

### Projectile Systems
- Pool at least 2x expected concurrent bullets
- Use kinematic bodies for simple projectiles
- Batch collision checks
- Implement timeout cleanup

### Swarm Systems
- Limit flock size to 100-500 boids
- Use grid partitioning for > 100 agents
- Update in groups per frame
- Adjust behavior complexity by count

### Profiling
- Profile before optimizing
- Measure batch vs. individual performance
- Monitor allocation patterns
- Check parallel job efficiency

## Common Pitfalls

- Creating bodies individually in loops
- Allocating new arrays every frame
- Not disposing NativeArrays
- Over-batching (diminishing returns)
- Incorrect allocator usage
- Forgetting to destroy batched bodies

## Advanced Techniques

### Hierarchical Batching
- Batch by object type
- Group similar operations
- Cascade batch updates
- Multi-level optimization

### Adaptive Batching
- Scale batch size by load
- Dynamic pooling
- LOD-based batching
- Performance-driven decisions

## Related Skills

When users need information about:
- **Batch body creation** - Covered in main unity-physicscore2d skill
- **Queries** - Use unity-physicscore2d-queries
- **Performance optimization** - Use unity-physicscore2d-performance
- **Collections** - Use Unity.Collections NativeArray

## Worked Examples

> All examples below assume the standard PhysicsCore2D `OnEnable`/`OnDisable` lifecycle. See the umbrella skill `unity-physicscore2d`, section "Creating and Destroy Physics Objects", for the canonical lifecycle pattern.

- [examples/Boids.cs](examples/Boids.cs) — 1000 kinematic boids; Burst-compiled flocking job + `PhysicsBody.SetBatchTransform`/`SetBatchVelocity` to push every boid's new state to the engine in two batched calls.
- [examples/BulkQueries.cs](examples/BulkQueries.cs) — fan of `BatchCount` raycasts run in `IJobParallelFor`, hits converted to a `BatchForce` array and applied via single `PhysicsBody.SetBatchForce`.
- [examples/ProjectileShooter.cs](examples/ProjectileShooter.cs) — periodic projectile spawner using `world.CreateBodyBatch(definitions)`; on each step inspects `world.contactBeginEvents` and tears down hits via `PhysicsBody.DestroyBatch`.

---

Source: https://www.openparable.com/skill/development/unity-physicscore2d-batching (OpenParable). Cite the canonical URL above.
