How boatbomber/cullthrottle works
Based on our analysis of the file tree and README, CullThrottle is a Luau module for Roblox designed to manage and cull update operations efficiently for tens of thousands of objects (typically BaseParts). It enables developers to control per-frame updates by prioritizing objects based on visibility and distance from the camera. The project is essentially a performance-optimization library that provides a well-documented API for object management, visibility culling, and update iteration—all of which are critical in large-scale Roblox experiences.
Main Components
• CullThrottle API Module – This is the core component that the consumers interact with. It exposes methods like new(), AddObject, AddPhysicsObject, CaptureTag, IterateObjectsToUpdate, and GetVisibleObjects.
• Object Management & Update Prioritization – Within the CullThrottle module, sub-components like the PriorityQueue (located in src/PriorityQueue.luau) manage update order and timing.
• Configuration and Utility Modules – Components like Config (src/Config.luau) and various utility modules in src/Utilities (e.g., CameraCache, GoodSignal, ObjectDimensions) support essential functionality such as tracking camera updates, event signaling, and calculating object dimensions.
• Event Handling / Signals – The design should include the ObjectEnteredView and ObjectExitedView signals, which notify subscribers when objects enter or leave view.
• Demo Usage – Although not part of production code, the demo folder (with scripts like init.client.luau, Blocks.luau) illustrates how CullThrottle gets integrated into a Roblox game and interacts with common services like RunService and ReplicatedStorage.
Relationships and Data Flow
• Placement & Interactions:
• The central “CullThrottle” component accepts objects (and tags from CollectionService) and then routes them to utility modules for calculations (e.g., for object dimensions or camera distance).
• The PriorityQueue subsystem orders objects based on “importance” determined by visibility (via voxel checks) and camera proximity.
• Two-way interactions exist: the CullThrottle continuously queries the current state (using GetVisibleObjects and IterateObjectsToUpdate) and then emits events like ObjectEnteredView/ObjectExitedView.
• Data Flow / Update Cycle:
• Visual objects are captured (via CaptureTag or manual AddObject/AddPhysicsObject) then internally processed each frame—object priorities are updated and the iterator provides the most important objects.
• Render distance, refresh rates, and time budgets (set through provided API methods) adjust the update policies in real time.
Architectural Patterns and Design Principles
• Modular Design – The project is divided into clear modules (core, utilities, configuration) working collaboratively.
• Event-Driven Programming – Signals are used to handle dynamic addition and removal of objects based on their visibility.
• Prioritization and Performance Budgeting – The use of a PriorityQueue and configurable time budgets reflects a focus on keeping execution within performance constraints.
• Loose Coupling – The segregation between the core culling logic, configuration, and utilities ensures they can be modified or replaced independently.
Relevant Technologies and Frameworks
• Luau – The project is written in Luau, Roblox’s variant of Lua.
• Roblox Services – It integrates deeply with Roblox’s game services such as RunService, CollectionService, and utilizes bulk operations (e.g., BulkMoveTo) for performance.
• Wally – Provided as dependency management for Roblox modules.
• GitHub for open-source contributions and version control.