/minecraft-socketedit

SocketEdit: High-Performance Minecraft Block Engine

Activation

Triggers when: user mentions Minecraft server, block editing, world building, video display in Minecraft, image-to-blocks, SocketEdit, or bulk block placement.

Overview

SocketEdit is a complete pipeline for programmatic Minecraft world editing at extreme throughput. It consists of:

1. **Paper server** with a custom TCP plugin (Java) for direct NMS block writes 2. **C client library** (`libsocketedit.so`) for fast binary encoding 3. **Python orchestration layer** for image/video/procedural generation 4. **CUDA kernels** for GPU-accelerated block generation and video quantization 5. **JNI bridge** connecting CUDA to the Java plugin

Proven benchmarks (4 threads, parallel chunk writer):

• **Batch**: 3.7M blk/s (500K blocks)
• **Fill**: 59M blk/s (150^3+ volumes)
• **Pipeline**: 6.2M blk/s (10x100K overlapping I/O)

---

Phase 1: Server Setup

Prerequisites

• Java 21+ (compiled with 25)
• Paper 1.21.4 (build 232)
• 4GB+ RAM allocated to server
• Linux host with gcc, make

Step-by-step

# 1. Create server directory
mkdir -p /path/to/server && cd /path/to/server

# 2. Download Paper
curl -o paper-1.21.4-232.jar \
  https://api.papermc.io/v2/projects/paper/versions/1.21.4/builds/232/downloads/paper-1.21.4-232.jar

# 3. Accept EULA
echo "eula=true" > eula.txt

# 4. Create start script
cat > start.sh << 'EOF'
#!/bin/bash
java -Xms4G -Xmx4G \
  -XX:+UseG1GC -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions \
  -XX:+DisableExplicitGC -XX:+AlwaysPreTouch \
  -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 \
  -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 \
  -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 \
  -XX:InitiatingHeapOccupancyPercent=15 \
  -XX:G1MixedGCLiveThresholdPercent=90 \
  -XX:G1RSetUpdatingPauseTimePercent=5 \
  -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem \
  -XX:MaxTenuringThreshold=1 \
  -jar paper-1.21.4-232.jar --nogui
EOF
chmod +x start.sh

# 5. First run to generate configs
./start.sh  # then stop it after configs generate

Key server.properties settings

server-port=25565
enable-rcon=true
rcon.port=25575
rcon.password=minecraft123
gamemode=survival
view-distance=16
simulation-distance=10
enable-command-block=true
enforce-secure-profile=false
max-players=20

Optional: Install WorldEdit + WorldGuard

Download plugin JARs into `plugins/` directory before starting:

• WorldEdit: https://dev.bukkit.org/projects/worldedit
• WorldGuard: https://dev.bukkit.org/projects/worldguard

Set WorldEdit `max-blocks-changed: -1` and `max-radius: -1` in `plugins/WorldEdit/config.yml` for unlimited operations.

---

Phase 2: SocketEdit Plugin (Java)

Architecture

TCP Client ──► SocketServer (port 9900, daemon thread)
                 └─► ClientHandler (per-connection thread)
                       └─► CommandQueue (ConcurrentLinkedQueue)
                             └─► BlockPlacer (main Bukkit thread, drained every tick)
                                   ├─► NMSBridge (direct chunk section writes)
                                   ├─► ParallelChunkWriter (multi-threaded sections)
                                   └─► NativeEngine (JNI → CUDA kernels)

Wire Protocol

Frame:  [4B length (big-endian)] [1B opcode] [4B request_id] [payload...]
String: [2B length (big-endian)] [UTF-8 bytes]

Response: [4B length] [1B status] [4B request_id] [payload...]
  status: 0x00 = OK, 0x01 = ERROR

Opcodes

| Code | Name | Payload | |------|------|---------| | 0x00 | PING | arbitrary echo data | | 0x10 | AUTH | password string (must be first message) | | 0x02 | SET_BLOCK | world:str, x:i32, y:i16, z:i32, blockdata:str | | 0x03 | BATCH_SET_BLOCKS | world:str, palette_count:u16, palette:str[], block_count:u32, blocks:[idx:u16, x:i32, y:i16, z:i32]... | | 0x04 | FILL | world:str, blockdata:str, x1:i32, y1:i16, z1:i32, x2:i32, y2:i16, z2:i32 | | 0x05 | GET_BLOCK | world:str, x:i32, y:i16, z:i32 | | 0x06 | EXEC_COMMAND | command:str | | 0x07 | GET_HEIGHTMAP | world:str, x1:i32, z1:i32, x2:i32, z2:i32, minY:i16, maxY:i16 | | 0x08 | NATIVE_BATCH | kernelType:i32, params:bytes, outputBuffer |

Block data per entry: 12 bytes

[palette_idx: uint16] [x: int32] [y: int16] [z: int32]

All integers are big-endian.

Plugin config.yml

port: 9900
password: ""
blocks-per-tick: 50000
parallel-threads: 4
native-lib-path: ""

Build

cd socketedit/
# build.gradle.kts uses Paper API 1.21.4-R0.1-SNAPSHOT
gradle build
# Output: SocketEdit-1.0.0.jar → ../plugins/

Key Java classes

**9 source files** in `com.foxcraft.socketedit`:

| Class | Role | |-------|------| | `SocketEditPlugin` | Lifecycle: init components, schedule tick drain | | `SocketServer` | TCP listener on port 9900, spawns ClientHandlers | | `ClientHandler` | Per-connection: auth handshake, opcode dispatch | | `Protocol` | Frame encoding/decoding, string I/O, response builders | | `CommandQueue` | Thread-safe bridge: network threads → main thread | | `BlockPlacer` | High-level operations: batch, fill, heightmap, GPU dispatch | | `NMSBridge` | Direct NMS chunk section writes via MethodHandles | | `ParallelChunkWriter` | Section-partitioned multi-threaded block placement | | `NativeEngine` | JNI bridge to CUDA: allocate, generate, quantize, sort |

NMSBridge — Direct Chunk Access

Bypasses Bukkit API entirely. Uses MethodHandle reflection resolved once at startup:

CraftWorld.getHandle() → ServerLevel
ServerLevel.getChunk(cx, cz) → LevelChunk
LevelChunk.getSections() → LevelChunkSection[]
LevelChunkSection.setBlockState(lx, ly, lz, state, lock) → direct palette write
CraftBlockData.getState() → NMS BlockState
LevelChunk.setUnsaved(true)

**Last-chunk cache**: tracks `(cx, cz)` to skip redundant lookups within a batch.

ParallelChunkWriter — Section-Partitioned Parallelism

Thread safety model: no two