PulseThread SIS — Governed Execution and Offloading Framework for Minecraft Servers

PulseThread SIS (PT-SIS) is a Software Integration Suite (SIS) for Minecraft servers,
built to keep servers stable, responsive, and fast under real-world load.

Important: Project Scope and Separation

PulseThread SIS Core (Community) is the REQUIRED base plugin for the PulseThread SIS framework.

This project provides ONLY the shared execution engine, governance system, and safety model.
It does not offload world generation, AI behavior, or other domain-specific workloads by itself.

Other PulseThread projects (such as PulseGen, PulseAI, and PulseRuntime) are SEPARATE addon plugins
that extend this core with optional functionality.

Without this Core plugin installed:
- Other PulseThread addons cannot function
- No offloading or governance occurs

Without addons installed:
- PulseThread Core still runs
- The server behaves normally
- Only the execution engine and governance layer are active

Each PulseThread plugin is listed separately to allow server owners to install ONLY the components they need.

Instead of plugins competing independently for tick time, PulseThread introduces a
shared, governed execution system that observes server health and coordinates when
and how work is allowed to run.

PulseThread is not a single plugin.
It is a multi-plugin platform composed of a shared execution core, a runtime safety
layer, and hook-based offloaders that work together behind the scenes to manage load,
control execution, and eliminate unsafe async patterns.

In the Community Edition, four plugins are included:
- PulseThreadCore (this project)
- PulseRuntime
- PulseHook
- PulseGen

PulseThreadCore, PulseRuntime, and PulseHook form the required base.
Once loaded, PulseHook automatically discovers compatible plugins and stages their
work through PulseThread’s governed execution pipeline.

PulseGen enables offloading for generation-related workloads.
Additional plugins exist in other editions (such as PulseAI), and developers are free
to create their own integrations to hook into PulseThread’s execution pools.

PulseThread is built around ray-centric execution, cache-aware coordination, and strict runtime governance.

The goal is simple:
allow server owners and plugin authors to benefit from offloading and execution control
without having to build unsafe async systems themselves.

PulseThread is governance-first — but it is also very fast.

By enforcing stability and safety first, the server gains room to breathe.
When that happens, performance improves naturally.

Speed emerges from stability — not unsafe shortcuts.

## Performance at a Glance

PulseThread achieves high real-world throughput by aggressively eliminating
redundant work and coordinating execution through cache-aware, policy-governed systems.

At its core, it leverages:
- multi-tier caching (hot / warm / cold / execution-scoped)
- per-player caches for view-dependent, perception, and transient state
- global caches for shared world, structure, and simulation data
- snapshot reuse to safely bridge real-time and off-thread execution
- preloading and reuse of expensive computation
- fast math paths for hot execution loops
- optimized vector operations for AI, spatial, and physics-heavy logic
- execution-aware batching, merging, and staging
- dynamic backpressure and intake control
- virtual threads and efficiency-thread utilization (enabled by default)
- policy-driven execution lanes, not unrestricted async

The result is extremely fast turnaround for repeated and high-frequency workloads,
while maintaining predictable behavior and stability under spikes and worst-case scenarios.

When conditions are healthy, PulseThread pushes throughput hard.
When conditions degrade, it adapts immediately instead of collapsing.

## What You Get When You Install It (Community Edition)

The Community Edition of PulseThread SIS is designed to be drop-in and immediately usable.

No complex configuration is required. Once installed, PulseThread begins observing server load and adjusting execution automatically.

At runtime, it continuously:
- watches server load and tick health
- monitors MSPT and execution backlogs
- limits execution when needed
- allows more work when the server can safely handle it

With basic tuning and governor modes, performance can increase significantly while remaining controlled.

> This Community release is intentionally a bit more permissive to surface edge cases during public testing.
> Future releases will tighten policy and control, enabling even higher throughput without sacrificing safety.

Higher editions expand this behavior into a configurable execution framework for advanced and enterprise use.

> Project Repository:
> https://github.com/WhiskeyMC/PulseThread-SIS-Community-/tree/main
>
> Contains the full Community Edition source, documentation, and experimental surfaces intended for exploration and public testing.

## Commands & Live Runtime Control

PulseThread exposes live runtime commands that allow operators to observe and guide execution behavior in real time — without restarts or config churn.

### Core Commands

- /pulsethread
Displays a high-level overview of the system.

- /pulsethread status
Shows live execution state, including:
- active governor mode
- server health indicators
- execution intake and pressure

### Governor Control

- /pulsethread mode <safe|normal|aggressive>

Governor modes control how aggressively work is allowed to proceed:

- SAFE – prioritizes stability and recovery
- NORMAL – balanced execution and safety
- AGGRESSIVE – higher throughput when healthy, immediate fallback under stress

> Most servers will only need to view status and occasionally switch modes.
> AGGRESSIVE is currently recommended and is not the most hardware-intensive option. More advanced policy modes will be introduced in future editions.

> Full Command Reference:
> https://github.com/WhiskeyMC/PulseThread-SIS-Community-/blob/main/COMMANDS.txt

## Systems and Load Patterns This Suite Is Designed For

PulseThread is designed and tested against **real-world server load patterns**, including:

### Heavy Compute and Logic Systems
- EliteMobs
- BetterStructures
- MythicMobs
- WorldEdit / WorldGuard
- AI-heavy and structure-heavy plugins

### High-Frequency and Data-Critical Systems
- LuckPerms and permission systems
- data access and lookup-heavy workflows
- spark and other observability tools
- event-heavy gameplay paths

### Large Datapack and World Systems
- Terralith
- Incendium
- Nullscape
- Dungeons & Taverns (with side modules)

### Common Stress Conditions
- AI-dense combat
- large structure placement
- chunk generation spikes
- world scanning and indexing

## Execution Model (Synchronous-First)

PulseThread uses a synchronous-first execution model.

Heavy computation may occur asynchronously, but **all world mutation is applied synchronously or through region-safe execution paths. There are no unsafe async Bukkit mutation routes and no hidden bypasses.

All work flows through a shared pipeline where it is:
- staged
- batched
- rate-limited
- governed fairly between plugins, players, and worlds

The system continuously answers:

How much work can safely execute right now without harming gameplay?

## Ray-Based Behavior Systems (PulseAI)

PulseThread exposes ray-centric execution and perception services that
any plugin may hook into through PulseHook and the governed execution
pipeline.

PulseAI is the official reference implementation of these systems and
provides ray-based behavior modules such as PulseDodge and PulseStealth.
These implementations demonstrate how ray tracing, visibility context,
and execution-aware timing can be used to drive advanced entity behavior.

Key characteristics:
- shared ray tracing and visibility services available to all integrations
- PulseAI implements dodge and stealth as concrete, production examples
- ray-based line-of-attack, occlusion, and perception evaluation
- execution-governed reaction windows (no tick abuse)
- behavior dynamically scales with server health and load
- all systems remain policy-gated and safety-enforced

PulseAI does not introduce special privileges.
It uses the same public execution, cache, and ray interfaces that are
available to other developers through PulseThread.

PulseAI modules are nearing release and will ship separately once tuning
and validation are complete.

## PulseFabric SIS (Client)

PulseFabric SIS is the optional Fabric-side client component of PulseThread SIS.

It enables client-assisted computation by exposing controlled execution
surfaces on the client, allowing certain workloads to be shifted away
from the server when available. This includes ray-based evaluation,
perception support, and future GPU-accelerated computation paths.

PulseFabric does not bypass server authority.
All client-assisted work is capability-gated, validated, and coordinated
through PulseRuntime and the governed execution pipeline.

Key characteristics:
- optional, client-side compute participation
- ray-centric evaluation support for perception and visibility
- strict server authority and validation
- dynamic enablement based on client capability and server policy
- no rendering, shader, or visual modification requirements

PulseFabric is designed to integrate transparently.
When present, it provides additional execution headroom.
When absent, the server operates normally with safe fallback behavior.

## Real-World Results

PulseThread SIS is built from **real usage**, not theory.

Using this suite, I have been able to:
- run 30+ large and complex plugins
- operate multiple servers on a single machine (without waterfall)
- maintain stability on older or resource-constrained hardware

Before PulseThread, setups like this typically required high-end hardware and extensive manual tuning.

## Editions

### Community Edition
- Drop-in execution governor
- Full core safety model
- Architecture-locked
- Tuned for public testing and validation

### Pro / Enterprise Editions
- Configurable execution framework
- Fewer limits and stronger policy control
- Additional tuning surfaces and extension points

If CPU headroom exists, **Pro and Enterprise editions are designed to use it**.
Enterprise is effectively an **unbound configuration** for environments where throughput and hardware utilization are priorities.

## Project Status

This release completes the core PulseThread SIS architecture.

All primary systems are implemented and operational. Current work is
focused on tuning, optimization, and edge-case hardening rather than
introducing new architectural components. The Community Edition is
used to validate behavior under real workloads and heavy plugin stacks.

Dev Notes:
https://github.com/WhiskeyMC/PulseThread-SIS-Community-/blob/main/NOTES.md

## Looking Ahead

Ongoing work will focus on refinement and accuracy:
- tuning ray-based evaluation and visibility systems
- improving lighting, occlusion, and perception accuracy
- refining execution thresholds, budgets, and merge behavior
- reducing overhead in high-frequency and high-load scenarios
- continued stability and compatibility hardening

- Although originally built around 1.20.x, the current release targets 1.21.x only. Versions will be backported down to 1.16 before moving forward much at all again, with Folia reverse-async support being finalized afterward.

- New public API interfaces will be added on top of the existing system, enabling plugins to hook into PulseThread Core via PulseHook to offload work safely. These changes are planned for the next update, as this release marks the first full public release and will be used to identify issues that need patching.

Community License and Notice:
https://github.com/WhiskeyMC/PulseThread-SIS-Community-/blob/main/SCHEDULE_A_COMMUNITY.txt
https://github.com/WhiskeyMC/PulseThread-SIS-Community-/blob/main/NOTICE.txt

The full Pro Edition is now available via my Buy Me a Coffee shop:
https://buymeacoffee.com/WhiskeyMC/e/505301

Much love,

__ WhiskeyMC