pulse

1# Module Implementation Template
2 
3Use this template to create new Pulse optimisation modules.
4 
5## Step 1: Create the Package
6 
7Create a new package under `src/main/java/io/github/yourorg/pulse/module/<name>/`.
8 
9## Step 2: Implement the Module Interface
10 
11```java
12package io.github.yourorg.pulse.module.<name>;
13 
14import io.github.yourorg.pulse.module.Module;
15 
16public class <Name>Module implements Module {
17    private int currentLevel;
18    private final <Name>Config config;
19 
20    public <Name>Module(<Name>Config config) {
21        this.config = config;
22        this.currentLevel = config.maxLevel();
23    }
24 
25    @Override
26    public String id() {
27        return "<name>";
28    }
29 
30    @Override
31    public String displayName() {
32        return "<Display Name>";
33    }
34 
35    @Override
36    public int levelCount() {
37        return config.maxLevel();
38    }
39 
40    @Override
41    public int currentLevel() {
42        return currentLevel;
43    }
44 
45    @Override
46    public void applyLevel(int level) {
47        this.currentLevel = level;
48        // Apply the level to the relevant game state
49    }
50 
51    @Override
52    public float costImpact() {
53        // Return a normalised cost multiplier (0.0 = no cost, 1.0 = max cost)
54        return (float) currentLevel / config.maxLevel();
55    }
56}
57```
58 
59## Step 3: Add Config Options
60 
61In `io.github.yourorg.pulse.config.PulseConfig`, add a nested config class:
62 
63```java
64public static class <Name>Config {
65    @ConfigEntry(name = "enabled")
66    public boolean enabled = true;
67 
68    @ConfigEntry(name = "maxLevel")
69    public int maxLevel = <default>;
70 
71    @ConfigEntry(name = "minLevel")
72    public int minLevel = 1;
73}
74```
75 
76## Step 4: Register the Module
77 
78In `io.github.yourorg.pulse.module.ModuleRegistry`, add:
79 
80```java
81registry.register(new <Name>Module(config.<name>));
82```
83 
84## Step 5: Add Compatibility Rules
85 
86If the new module conflicts with existing mods, add rules in `io.github.yourorg.pulse.compat.CompatibilityChecker`.
87 
88## Step 6: Document
89 
90Add configuration entries to `CONFIGURATION.md` and if the module is notable, add it to `README.md`.
91 
92## Guidelines
93 
94- Each module must be **independently disableable**.
95- Level transitions must be **instant** and **safe to call every frame**.
96- Do not allocate memory during `applyLevel()` — allocate in the constructor.
97- Use the cost impact value to help the BudgetScheduler decide activation order.
98- Test with both vanilla and Sodium rendering pipelines.
99