# xinzheki/particle-boost architecture

> Architecture diagram of the GitHub repository xinzheki/particle-boost, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xinzheki/particle-boost
- Repository: https://github.com/xinzheki/particle-boost

## Overview

ParticleBoost is a client-side Minecraft particle optimizer. On client startup it loads JSON settings; during particle extraction, a frame hook snapshots the camera and updates governor state, then a wrapped quad-particle extraction applies distance, frustum, and optional block-occlusion culling. During particle ticking, a separate hook may replace distant particles’ full ticks with a cheap simulation step, using accessor-exposed fields. The README documents these feature stages and their hook mappings. Source excerpts show the core calls; unsampled metadata and runtime wiring are not inferred.

Main entry points: [`src/main/java/dev/particleboost/engine/ParticleFrame.java`](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/engine/ParticleFrame.java) (Frame Governor), [`src/main/java/dev/particleboost/engine/TickThrottle.java`](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/engine/TickThrottle.java) (Tick Throttle), [`src/main/java/dev/particleboost/engine/ParticleCuller.java`](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/engine/ParticleCuller.java) (Particle Culler), [`src/main/java/dev/particleboost/PBConfig.java`](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/PBConfig.java) (JSON Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and Config"]
  node_initializer["Client Initializer"]
  node_config["JSON Config<br/>[PBConfig.java]"]
end

subgraph group_render["Render Culling"]
  node_engine_hook["Frame Hook"]
  node_frame["Frame Governor<br/>[ParticleFrame.java]"]
  node_quad_hook["Quad Extraction Hook"]
  node_culler["Particle Culler"]
end

subgraph group_lod["Tick LOD"]
  node_particle_group["Particle Tick Hook"]
  node_throttle["Tick Throttle<br/>[TickThrottle.java]"]
  node_accessor["Particle Accessor"]
end

node_client(("Minecraft Client"))
node_world[("Loaded Block World")]

node_client -.->|"initializes"| node_initializer
node_initializer -->|"loads"| node_config
node_engine_hook -->|"begins frame"| node_frame
node_frame -->|"reads settings"| node_config
node_frame -->|"resets budget"| node_culler
node_quad_hook -->|"checks visibility"| node_culler
node_culler -->|"reads frame state"| node_frame
node_culler -->|"queries blocks"| node_world
node_particle_group -->|"tries cheap step"| node_throttle
node_throttle -->|"reads settings"| node_config
node_throttle -->|"reads LOD state"| node_frame
node_throttle -->|"accesses fields"| node_accessor

click node_initializer "https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/ParticleBoostClient.java"
click node_config "https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/PBConfig.java"
click node_engine_hook "https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/mixin/ParticleEngineMixin.java"
click node_frame "https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/engine/ParticleFrame.java"
click node_quad_hook "https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/mixin/QuadParticleGroupMixin.java"
click node_culler "https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/engine/ParticleCuller.java"
click node_particle_group "https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/mixin/ParticleGroupMixin.java"
click node_throttle "https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/engine/TickThrottle.java"
click node_accessor "https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/mixin/ParticleAccessor.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_initializer,node_config,node_client toneBlue
class node_engine_hook,node_frame,node_quad_hook,node_culler,node_world toneAmber
class node_particle_group,node_throttle,node_accessor toneMint
```

## Components

### Startup and Config

- [Client Initializer](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/ParticleBoostClient.java): `src/main/java/dev/particleboost/ParticleBoostClient.java`
- [JSON Config](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/PBConfig.java): `src/main/java/dev/particleboost/PBConfig.java`

### Render Culling

- [Frame Hook](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/mixin/ParticleEngineMixin.java): `src/main/java/dev/particleboost/mixin/ParticleEngineMixin.java`
- [Frame Governor](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/engine/ParticleFrame.java): `src/main/java/dev/particleboost/engine/ParticleFrame.java`
- [Quad Extraction Hook](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/mixin/QuadParticleGroupMixin.java): `src/main/java/dev/particleboost/mixin/QuadParticleGroupMixin.java`
- [Particle Culler](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/engine/ParticleCuller.java): `src/main/java/dev/particleboost/engine/ParticleCuller.java`

### Tick LOD

- [Particle Tick Hook](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/mixin/ParticleGroupMixin.java): `src/main/java/dev/particleboost/mixin/ParticleGroupMixin.java`
- [Tick Throttle](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/engine/TickThrottle.java): `src/main/java/dev/particleboost/engine/TickThrottle.java`
- [Particle Accessor](https://github.com/xinzheki/particle-boost/blob/main/src/main/java/dev/particleboost/mixin/ParticleAccessor.java): `src/main/java/dev/particleboost/mixin/ParticleAccessor.java`

### Other components

- **Minecraft Client**
- **Loaded Block World**

## Connections

- Minecraft Client → Client Initializer: initializes (evidence: `README.md`)
- Client Initializer → JSON Config: loads (evidence: `src/main/java/dev/particleboost/ParticleBoostClient.java`)
- Frame Hook → Frame Governor: begins frame (evidence: `src/main/java/dev/particleboost/mixin/ParticleEngineMixin.java`)
- Frame Governor → JSON Config: reads settings (evidence: `src/main/java/dev/particleboost/engine/ParticleFrame.java`)
- Frame Governor → Particle Culler: resets budget (evidence: `src/main/java/dev/particleboost/engine/ParticleFrame.java`)
- Quad Extraction Hook → Particle Culler: checks visibility (evidence: `src/main/java/dev/particleboost/mixin/QuadParticleGroupMixin.java`)
- Particle Culler → Frame Governor: reads frame state (evidence: `src/main/java/dev/particleboost/engine/ParticleCuller.java`)
- Particle Culler → Loaded Block World: queries blocks (evidence: `src/main/java/dev/particleboost/engine/ParticleCuller.java`)
- Particle Tick Hook → Tick Throttle: tries cheap step (evidence: `src/main/java/dev/particleboost/mixin/ParticleGroupMixin.java`)
- Tick Throttle → JSON Config: reads settings (evidence: `src/main/java/dev/particleboost/engine/TickThrottle.java`)
- Tick Throttle → Frame Governor: reads LOD state (evidence: `src/main/java/dev/particleboost/engine/TickThrottle.java`)
- Tick Throttle → Particle Accessor: accesses fields (evidence: `src/main/java/dev/particleboost/engine/TickThrottle.java`)