# boatbomber/cullthrottle architecture

> Architecture diagram of the GitHub repository boatbomber/cullthrottle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boatbomber/cullthrottle
- Repository: https://github.com/boatbomber/cullthrottle

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layer
    subgraph "Core Layer"
        A["CullThrottle Core Module"]:::core
    end

    %% Management Layer
    subgraph "Management Layer"
        B["Object Management & Priority Queue"]:::submodule
        C["PriorityQueue Subsystem"]:::submodule
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        D["Configuration & Options"]:::config
        E["Configuration Module (Config)"]:::config
    end

    %% Utilities
    subgraph "Utilities"
        F["Utility Modules"]:::utility
        G["CameraCache"]:::utility
        H["GoodSignal"]:::utility
        I["ObjectDimensions"]:::utility
    end

    %% Event System
    subgraph "Event System"
        J["Event System"]:::event
        K["ObjectEnteredView Signal"]:::event
        L["ObjectExitedView Signal"]:::event
    end

    %% Integration Layer
    subgraph "Integration Layer"
        M["Usage / Integration Layer"]:::demo
        O["Roblox Services (RunService,CollectionService)"]:::external
        subgraph "Demo Scripts"
            M1["init.client.luau"]:::demo
            M2["Blocks.luau"]:::demo
            M3["MetricGraph.luau"]:::demo
            M4["Utility.luau"]:::demo
        end
    end

    %% Frame Update Cycle
    P["Frame Update Cycle"]:::cycle

    %% Connections
    A -->|"RegistersObjects"| B
    B -->|"OrdersUpdates"| C
    C -->|"UpdatesPriorities"| A
    A -->|"ReadsConfig"| D
    D -->|"LoadsOptions"| E
    E -->|"ConfiguresCore"| A
    A -->|"UtilizesUtilities"| F
    F -->|"ProvidesCameraData"| G
    F -->|"ManagesSignals"| H
    F -->|"CalculatesDimensions"| I
    A -->|"EmitsEvents"| J
    J -->|"TriggersEnter"| K
    J -->|"TriggersExit"| L
    A -->|"IntegratesUsage"| M
    M -->|"ConnectsToServices"| O
    M -->|"ContainsDemo"| M1
    M -->|"ContainsDemo"| M2
    M -->|"ContainsDemo"| M3
    M -->|"ContainsDemo"| M4
    A -.->|"IteratesObjects"| P

    %% Click Events
    click A "https://github.com/boatbomber/cullthrottle/blob/main/src/init.luau"
    click C "https://github.com/boatbomber/cullthrottle/blob/main/src/PriorityQueue.luau"
    click E "https://github.com/boatbomber/cullthrottle/blob/main/src/Config.luau"
    click F "https://github.com/boatbomber/cullthrottle/tree/main/src/Utilities"
    click M1 "https://github.com/boatbomber/cullthrottle/blob/main/demo/init.client.luau"
    click M2 "https://github.com/boatbomber/cullthrottle/blob/main/demo/Blocks.luau"
    click M3 "https://github.com/boatbomber/cullthrottle/blob/main/demo/MetricGraph.luau"
    click M4 "https://github.com/boatbomber/cullthrottle/blob/main/demo/Utility.luau"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef submodule fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef config fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef utility fill:#FFE0B2,stroke:#E65100,stroke-width:2px;
    classDef event fill:#F8BBD0,stroke:#880E4F,stroke-width:2px;
    classDef demo fill:#D1C4E9,stroke:#4527A0,stroke-width:2px;
    classDef external fill:#B2EBF2,stroke:#006064,stroke-width:2px;
    classDef cycle fill:#CFD8DC,stroke:#37474F,stroke-width:2px;
```
