Performance Tuning

VirtualViewList was built for extreme data volumes. This chapter gathers the knobs you can use to balance smoothness and memory.

Cache & Frame Splitting

cacheRatio: extra viewport fraction to render off-screen (default 0.1). Increase for faster flick scrolls, decrease for lower memory.
- Dynamic buffer expansion: When scroll velocity exceeds 50px/frame, buffer size automatically doubles to reduce blank areas.
mAutoPreloadCount: number of nodes to prepare ahead of time.
PreloadItems(count): manual preload hook, useful during scene loading.
mNeedFrameLoading: internal flag that spreads work across multiple frames.

autoOptimizePerformance enables VirtualListPerformanceManager to intelligently adjust refresh strategies based on scroll velocity and frame performance.
- Smart Refresh Rate Strategy (3 tiers):
  - Fast scrolling (>50px/frame): 30fps - Reduce render pressure, avoid lag
  - Medium scrolling (5-50px/frame): 60fps - Standard smoothness
  - Slow/Idle (≤5px/frame): 120fps - Ultra smooth display
- Fixed rate per scroll: Refresh rate is determined at scroll start and remains constant throughout the scroll session, preventing rate fluctuations that cause blank frames.
Use performanceManager.IsLowPerformanceMode() to downgrade expensive visual effects when needed.

EnableDebugMode(true) prints verbose logs and frame stats—handy during profiling sessions.
GetStatus() returns itemCount, visibleCount, pool size, low-performance flag and memory usage snapshot.

Keep templates lightweight to reduce update cost.
Delay heavy asset loading until an item is fully visible.
Avoid running multiple insert/remove animations simultaneously—queue them when possible.
Large dataset optimization: For 10,000+ items, the component uses sampling to calculate averages, avoiding full array traversal for better initialization performance.
Combine with the Cocos Profiler to watch draw calls and memory while tuning list settings.