OracleServer

A ground-up Java implementation of the Minecraft 1.8.8 server protocol. No dependency on Bukkit, Spigot, Paper, or any other forks: the handshake, login, play loop, world tick, chunk pipeline, and entity broadcast layer are all implemented directly on top of Netty.

The project targets a stable 20 TPS under load while keeping per-tick allocations close to zero, so the JVM stays out of GC even when broadcasting thousands of entity updates per second.

Highlights

• Pure Java, zero forks. Implements the Minecraft 1.8.8 protocol end-to-end on Netty.
• Custom tick loop. Drives entity ticks, scheduler tasks, async chunk loading, and connection drains.
• Allocation-aware hot path. Profiled and tuned so the per-broadcast cost is bounded by Netty's own write pipeline, not application code.
• Custom MPSC packet queue. Unbounded chunked design with one ~8 KB chunk allocated per 1024 enqueued packets (vs. one node per packet for ConcurrentLinkedQueue).
• Built-in profiler. Per-section CPU time and per-thread allocation tracking, accessible from the /pt command in-game.

Performance

Numbers below are from a single 10-second profile window with 1 real client (teixayo) + 1000 FakePlayers orbiting in a circle (the /benchmark load test). Hardware: local development machine, localhost loopback.

Metric	Before optimization	After optimization	Reduction
Total allocation rate	11.40 MB/s	2.41 MB/s	79%
Tracked-section allocation	7.20 MB/s	0.65 MB/s	91%
broadcast.dispatch.EntityLook	3.41 MB/s	0.09 MB/s	97%
broadcast.dispatch.EntityHeadLook	3.09 MB/s	0.07 MB/s	98%
Main thread allocations	1.73 MB/s	0.53 MB/s	69%
GC pauses in window	1 ms	0 ms	—
Avg tick.total	1959 us	1981 us	unchanged

Server CPU usage during the benchmark stayed below 1.5%, and the heap stabilized at ~49 MB. See docs/PERFORMANCE.md for the full optimization journey and methodology.

Prerequisites

• Java 21+
• Maven 3.6+
• Environment variable PORT (the TCP port to listen on, e.g. 25565)
• Optional environment variable ONLINE_MODE (set to false for offline-mode development)

Quick start

Clone and build:

git clone https://github.com/teixayo/OracleServer.git
cd OracleServer
mvn clean package

Run:

PORT=25565 ONLINE_MODE=false java --enable-preview -jar target/Main-0.5.0-BETA.jar

Connect with a Minecraft 1.8.8 client and add a server at localhost:25565.

In-game commands

Command	Description
/pt	Show live performance counters in tab
/profiler start <seconds>	Capture a CPU + allocation profile for N seconds, then print a report
/benchmark <count>	Spawn N FakePlayers orbiting around you (load test)
/npc <name>	Spawn a static NPC
/hologram <text>	Create an armor-stand-based hologram
/save	Persist loaded chunks to disk
/heal	Restore your health
/kill	Set your health to zero
/viewdistance <chunks>	Change chunk view distance
/drop	Drop a test item entity

Status

Working: handshake, login, play loop, chunk send, entity spawn/despawn, movement broadcasts, basic combat, inventory clicks, command framework, profiler, benchmark.

Work in progress: full combat mechanics, mob AI, plugin API.

License

No license file is included yet. Treat as source-available for inspection. If you want to use it elsewhere, open an issue first.