# Sable Optimizer

Server-side NeoForge mod that reduces Sable physics CPU usage by detecting inactive sub-levels (ships) and scaling down their work.

## Commands

| Command | Description |
|---|---|
| `/sableoptimizer status @e[type=sable:sub_level]` | Shows activity state and velocity for targeted sub-levels |
| `/sableoptimizer reset @e[type=sable:sub_level]` | Force-wakes targeted sub-levels back to full activity |

Requires op level 2+.

## Config Presets

Edit the server config file (`config/sable_optimizer-server.toml`) to apply these values manually:

### Quality (gentle)

Smooth ship movement, minimal visual difference from vanilla.

| Setting | Value |
|---|---|
| `inactivityThresholdTicks` | 200 |
| `activeHeatmapTickInterval` | 4 |
| `inactiveHeatmapTickInterval` | 40 |
| `inactivePosesSubstepInterval` | 5 |
| `inactiveActorTickInterval` | 4 |

### Balanced (recommended)

Middle ground — recommended for most servers.

| Setting | Value |
|---|---|
| `inactivityThresholdTicks` | 400 |
| `activeHeatmapTickInterval` | 4 |
| `inactiveHeatmapTickInterval` | 10 |
| `inactivePosesSubstepInterval` | 5 |
| `inactiveActorTickInterval` | 4 |

### Performance (aggressive)

Maximum CPU savings — visual fidelity may decrease on inactive ships.

| Setting | Value |
|---|---|
| `inactivityThresholdTicks` | 200 |
| `activeHeatmapTickInterval` | 8 |
| `inactiveHeatmapTickInterval` | 70 |
| `inactivePosesSubstepInterval` | 8 |
| `inactiveActorTickInterval` | 8 |

## Optional: Create Aeronautics

If [Create Aeronautics](https://modrinth.com/mod/create-aeronautics) is installed, Sable Optimizer automatically applies the same optimizations to Aeronautics propellers, balloons, and other block entity actors. No extra config needed.

## Optional: Create

If [Create](https://modrinth.com/mod/create-fabric) is installed, Sable Optimizer applies server-side optimizations:

- **KineticBlockEntity tick skip** — idle kinetic block entities (no speed update, no network dirty, no validation pending) skip their entire tick, saving CPU for large networks with thousands of idle shafts/gears.
- **Contraption tick skip** — stationary contraptions (zero delta movement) skip entity collision checks, actor ticks, and related per-tick work.
- **KineticNetwork sync throttle** — network stress/capacity sync packets are throttled to every 4 ticks instead of every tick, reducing packet spam by 75% for large kinetic networks.

These are controlled by the `enableCreateOptimizations` config option (default: true). They are completely safe to leave enabled even without Create installed.

## Optional: Flywheel

Flywheel is **client-side only** — it has no server-side code. Sable Optimizer does not modify Flywheel.

## Full Config Options

| Option | Default | Description |
|---|---|---|
| `enableOptimization` | `true` | Master toggle |
| `inactivityThresholdTicks` | `400` | Ticks before a stopped sub-level is considered inactive |
| `velocityThreshold` | `0.01` | Velocity (m/s) below which a sub-level is considered stationary |
| `activeHeatmapTickInterval` | `4` | Heatmap frequency for active sub-levels |
| `inactiveHeatmapTickInterval` | `10` | Heatmap frequency for inactive sub-levels |
| `inactivePosesSubstepInterval` | `5` | Physics substep interval for inactive sub-level pose/force updates |
| `inactiveActorTickInterval` | `4` | Block entity actor tick interval for inactive sub-levels |
| `enableCreateOptimizations` | `true` | Enable Create-specific server optimizations |