unity-physicscore2d-performance - SKILL.md Agent Skill

name: unity-physicscore2d-performance description: Performance optimization, benchmarking, capacity testing, and large-scale physics simulations

Unity PhysicsCore2D Performance Expert

You are now acting as a Unity PhysicsCore2D performance expert, specialized in optimization and large-scale simulations.

Overview

Optimizing PhysicsCore2D for performance involves:

Capacity planning - Understanding system limits
Benchmarking - Measuring performance
Optimization techniques - Improving efficiency
Large-scale simulations - Handling many objects
Memory management - Reducing allocations

Repository Examples

Reference examples from the PhysicsExamples2D repository (Benchmark category):

System Capacity

Body Count Limits

Maximum concurrent physics bodies:

Static bodies: virtually unlimited
Dynamic bodies: depends on interaction count
Kinematic bodies: between static and dynamic cost
Target: 1000-5000 dynamic bodies typically feasible

Shape Complexity

Impact of shape complexity:

Circles: cheapest collision detection
Polygons: cost scales with vertex count
Compounds: sum of individual shape costs
Keep polygons under 8 vertices when possible

Joint Limits

Joint constraint capacity:

Each joint adds computation cost
Grid of joints (like soft body): expensive
Typical limit: 500-2000 joints
Disable distant joints for optimization

Collision Pairs

Active collision pair limits:

Cost is O(n²) without broad phase optimization
Spatial partitioning reduces to O(n)
Limit active collision pairs per frame
Use layers to reduce pair count

Benchmarking

Key Metrics

Monitor these performance indicators:

Physics step time (ms per frame)
Body count (static/kinematic/dynamic)
Active collision pairs
Joint count
Query count per frame
Memory usage

Profiling Tools

Use Unity profiler markers:

Physics.World.Step - main simulation cost
Collision detection time
Constraint solver time
Query operations
Transform synchronization

Stress Testing

Test with extreme scenarios:

Maximum expected body count
Worst-case collision situations
Complex joint networks
Many simultaneous queries
Large world extents

Optimization Techniques

Broad Phase Optimization

Reduce collision pair testing:

PhysicsCore2D uses spatial hashing
Large worlds perform well
Keep bodies in reasonable area
Extremely sparse distributions may be slower

Shape Optimization

Optimize collision geometry:

Use circles when possible (fastest)
Minimize polygon vertex count
Use compound shapes sparingly
Cache reused geometries

Sleep Optimization

Sleeping bodies don't simulate:

Objects at rest automatically sleep
Sleeping bodies have minimal cost
Wake only when needed
Tune sleep thresholds

Layer-Based Culling

Reduce collision pairs:

Use collision layers effectively
Disable unnecessary interactions
Group objects by interaction needs
Minimize "collides with all" layers

Query Optimization

Efficient spatial queries:

Minimize query count
Use appropriate query bounds
Batch queries when possible
Cache query results

Joint Optimization

Reduce joint cost:

Disable distant joints
Use simpler joint types
Remove unnecessary constraints
Consider joint-less alternatives

Large-Scale Simulations

World Partitioning

Divide large worlds:

Multiple sub-simulations
Load/unload regions
Spatial culling
Distance-based LOD

Level of Detail (LOD)

Reduce cost by distance:

Simplify distant geometry
Disable distant joints
Reduce update rate
Remove distant triggers

Streaming

Load physics progressively:

Stream in nearby objects
Unload distant objects
Maintain active region
Seamless transitions

Culling Strategies

Remove invisible objects:

Frustum culling
Distance culling
Occlusion culling
Disable physics for culled objects

Memory Management

Allocation Patterns

Minimize GC pressure:

Use NativeArray with Persistent
Avoid List, use NativeList
Preallocate pools
Reuse containers

Object Pooling

Reuse physics bodies:

Pre-create common objects
Recycle instead of destroy
Batch creation at startup
Pool management overhead vs. benefit

Batch Operations

Use batch APIs:

CreateBatch for bodies
DestroyBatch for cleanup
Batch queries
Parallel processing

Common Performance Issues

Excessive Collisions

Too many bodies colliding
Missing layer filtering
Unnecessarily complex shapes
No sleeping behavior

Solutions:

Add collision filtering
Simplify geometry
Use triggers for detection only
Tune sleep parameters

Long Physics Steps

Too many active bodies
Complex joint networks
High iteration counts
Many compound shapes

Solutions:

Reduce body count
Simplify joints
Lower solver iterations
Optimize shapes

Memory Spikes

Creating/destroying bodies each frame
Query allocations
Not disposing NativeArrays
List allocations

Solutions:

Use object pooling
Reuse queries
Dispose properly
Use NativeCollections

Query Overhead

Too many queries per frame
Large query bounds
Redundant queries
Allocating results each frame

Solutions:

Minimize query count
Tighten bounds
Cache results
Reuse result arrays

Best Practices

Design Considerations

Plan for target body count early
Design with layers in mind
Consider physics cost in gameplay
Profile throughout development

Optimization Priority

Reduce collision pairs (layers)
Simplify shapes
Enable sleeping
Use batching
Pool objects
Optimize queries

Performance Budget

Set and maintain limits:

Maximum body count
Physics time budget (< 5ms ideal)
Memory budget
Update frequency

Continuous Profiling

Profile frequently during development
Test on target hardware
Monitor worst-case scenarios
Maintain performance metrics

Platform Considerations

Mobile Optimization

Lower body count (500-1000)
Simpler geometry
Aggressive culling
Lower solver iterations

Desktop/Console

Higher capacity (2000-5000)
More complex simulations
Better sleep tuning
Higher quality simulation

WebGL

Similar to mobile constraints
WASM performance considerations
Memory limits
Browser compatibility

Related Skills

When users need information about:

Batch operations - Use unity-physicscore2d-batching
Query optimization - Use unity-physicscore2d-queries
Collection types - Use Unity.Collections
Profiling - Use Unity Profiler documentation

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/CapacityTest.cs — auto-spawns batches of 200 dynamic bodies until world.profile.simulationStep exceeds a target ms threshold for 60 consecutive frames; reports final world.counters snapshot. Capacity-planning helper.
examples/ManyBodies.cs — 15×15 grid of rotating kinematic tumblers each filled with capsule debris over time; ~225 islands stress test for broad-phase + narrow-phase.
examples/LargeCompound.cs — (splits+1)² dynamic compound bodies of span² boxes each (~5184 shapes default); demonstrates startMassUpdate=false + a single body.ApplyMassFromShapes() per body — the recommended pattern when adding many shapes to one body.
examples/JointGrid.cs — 32×32 grid of circle bodies wired with vertical+horizontal hinge joints (~1984 joints), 7-body strip anchored Static — joint-solver scaling test.