pulse

1# Pulse Architecture
2 
3## Overview
4 
5Pulse is a layered performance monitor that sits between Minecraft's client tick loop and game settings. It observes framerate metrics, computes a pressure score, maps it to optimization stages, and applies cosmetic setting changes via named modules.
6 
7```
8Client Tick Loop
9       │
10       ▼
11┌──────────────────────┐
12│  PerformanceEngine    │ ← frametime, FPS, spikes, entity count, velocity
13│  (rolling windows)    │
14└──────────┬───────────┘
15           ▼
16┌──────────────────────┐
17│  PressureEngine       │ ← normalizes metrics → 0–100 pressure score
18│  (weighted sum)       │
19└──────────┬───────────┘
20           ▼
21┌──────────────────────┐
22│  AdaptiveManager      │ ← maps score → OptimizationStage, handles recovery
23│  (hysteresis + timer) │
24└──────────┬───────────┘
25           ▼
26┌──────────────────────┐
27│  ModuleManager        │ ← calls update(stage) on every module
28│  (each module owns    │
29│   its own apply())    │
30└──────────────────────┘
31```
32 
33## Data Flow
34 
35### Per Tick (END_CLIENT_TICK)
36 
371. **PerformanceEngine.update()** — captures current FPS, frametime, spike detection, player velocity, entity count, GC events
382. **PressureEngine.update()** — normalizes each metric (0–1), multiplies by weights (total 1.0), sums to a 0–100 pressure score with rate-limiting and hysteresis
393. **AdaptiveManager.update()** — translates pressure score into `OptimizationStage`, manages recovery delays (wait N ticks before stepping down)
404. **ModuleManager.update(stage)** — calls `update()` on every registered module; each module that has a game-hook applies its own changes:
41   - EntityOptimizer → `options.entityDistanceScaling().set()` + `EntityRenderDispatcher.shouldRender()` mixin
42   - CloudOptimizer → `options.cloudStatus().set()`
43   - WeatherOptimizer → visual-only filtering (particle count, distance culling, thunder flash gating)
44   - Others (Particle, Animation, Transparency, UI, ChunkUpload, Shadow) → mixin hooks or internal parameters
45 
46**PulseClient no longer applies any optimizations directly.** All game-state changes are owned by individual modules, each with its own save/restore lifecycle.
47 
48## Package Structure
49 
50```
51io.github.pulse/
52  Pulse.java                     — Fabric ModInitializer, wires all singletons
53  api/
54    OptimizationStage.java       — NORMAL / MINOR / MODERATE / HEAVY / EMERGENCY
55    ModuleType.java              — enum: PARTICLES, ENTITIES, CHUNKS, CLOUDS, ...
56    AdaptiveModule.java          — interface for module framework
57    PulseAPI.java                — static accessors for engine state
58  performance/
59    PerformanceEngine.java       — rolling frametime stats, FPS, entity tracking
60    RollingStatistics.java       — sliding-window statistics
61  pressure/
62    PressureEngine.java          — weighted metric normalisation → 0–100 score
63  adaptive/
64    AdaptiveManager.java         — stage mapping with hysteresis and recovery delay
65  modules/
66    ModuleManager.java           — registers/updates all modules
67    EntityOptimizer.java         — entityDistanceScaling saved/applied/restored
68    CloudOptimizer.java          — cloudStatus saved/applied/restored
69    WeatherOptimizer.java        — weather particle count, distance, and thunder flash filtering
70    ParticleOptimizer.java       — internal parameters only
71    AnimationOptimizer.java      — internal parameters only
72    TransparencyOptimizer.java   — internal parameters only
73    UIOptimizer.java             — internal parameters only
74    ChunkUploadOptimizer.java    — internal parameters only
75    ShadowOptimizer.java         — Iris/OptiFine reflection (if shader mod present)
76  budget/
77    BudgetSystem.java            — tracks frametime vs target, estimates savings
78  config/
79    ConfigManager.java           — ModMenu integration + JSON save/load
80    PulseConfig.java             — config POJO (targetFps, sensitivity, etc.)
81  overlay/
82    HudOverlay.java              — debug overlay registered with HudElementRegistry
83  compat/
84    CompatibilityManager.java    — mod list scanner, marks stubs as disabled/reduced
85  client/
86    PulseClient.java             — ClientModInitializer, pure orchestration
87  util/
88    Constants.java               — thresholds, window sizes, recovery times
89```
90 
91## Module System
92 
93`AdaptiveModule` is an interface with `initialize()`, `update(stage)`, `enable()`, `disable()`, `recover()`, `shutdown()`. All 9 modules implement it. Their `update()` is called every tick with the current stage.
94 
95### Mixin infrastructure (require = 0)
96 
97Each mixin uses `require = 0` so the hook silently no-ops if the target method is renamed/restructured in a future Mojmap version. Modules remain functional at the internal-parameter level even when no mixin matches.
98 
99| Mixin | Target | Module |
100|-------|--------|--------|
101| `ParticleEngineMixin` | `ParticleEngine#add(Particle)` | ParticleOptimizer |
102| `EntityRenderDispatcherMixin` | `EntityRenderDispatcher#shouldRender(Entity, Frustum, double, double, double)` | EntityOptimizer / AnimationOptimizer |
103| `SectionRenderDispatcherMixin` | `SectionRenderDispatcher#rebuildSectionSync(RenderSection, RenderRegionCache)` | ChunkUploadOptimizer |
104| `TransparencyMixin` | `RenderSection#resortTransparency()` (0 params) | TransparencyOptimizer |
105| `ChatComponentMixin` | `ChatComponent#tick()` (0 params) | UIOptimizer |
106 
107Five modules wire into game code via mixins:
108 
109- **ParticleOptimizer** — mixin into `ParticleEngine#add` for particle cancellation
110- **EntityOptimizer** — mixin into `EntityRenderDispatcher#shouldRender` + Options API for `entityDistanceScaling`
111- **AnimationOptimizer** — mixin into `EntityRenderDispatcher#shouldRender` (same hook, different distance thresholds)
112- **ChunkUploadOptimizer** — mixin into `SectionRenderDispatcher#rebuildSectionSync` for upload queue prioritization
113- **TransparencyOptimizer** — mixin into `RenderSection#resortTransparency` for sort frequency reduction
114- **UIOptimizer** — mixin into `ChatComponent#tick` for chat update frequency reduction
115 
116Three modules use direct APIs:
117- **CloudOptimizer** — reads/writes `options.cloudStatus()`
118- **WeatherOptimizer** — visual-only filtering (no direct game-state manipulation)
119- **ShadowOptimizer** — Iris/OptiFine reflection with internal distance/resolution factors
120