gsd-skill-creator

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 threads touch the same (chunk_x, chunk_z, section_y).

5-phase batch write:

1. Parse (main thread): ByteBuffer → coords + NMS states
2. Pre-load (main thread): collect unique chunks, load from ServerLevel
3. Group (main thread): organize blocks by section key
4. Dispatch (worker threads): LevelChunkSection.setBlockState() per section
5. Sync (main thread): await futures, mark chunks unsaved

Section key packing (collision-free across signed coords):

sectionKey = ((cx + 0x100000) << 43) | ((cz + 0x100000) << 22) | (sy + 0x200000)

Thresholds: batch parallel at 10K+ blocks, fill parallel at 4K+ blocks.

Chunk Visibility Fix (Critical)

Direct NMS writes bypass client notification. After placement:

1. Call Heightmap.primeHeightmaps() to recalculate WORLD_SURFACE / OCEAN_FLOOR
2. Build ClientboundLevelChunkWithLightPacket per affected chunk
3. Send packet to all players via ServerPlayerConnection.send()
4. Trigger LevelLightEngine.checkBlock() for light propagation

Tick-batched sending: for large operations (50+ chunks), spread packets across ticks (50 chunks/tick) to avoid client flooding and vertical stripe rendering gaps.

Phase 3: C Client Library (libsocketedit)

API (socketedit.h)

// Connection
se_client* se_connect(const char* host, uint16_t port, const char* password);
void       se_disconnect(se_client* client);

// Single operations
int se_set_block(se_client*, const char* world, int x, short y, int z, const char* block);
int se_fill(se_client*, const char* world, const char* block, int x1, short y1, int z1, int x2, short y2, int z2);
int se_get_block(se_client*, const char* world, int x, short y, int z, char* out, int maxlen);
int se_exec_command(se_client*, const char* cmd);

// Batch builder (palette deduplication via FNV-1a hash)
se_batch* se_batch_create(const char* world);
int       se_batch_add(se_batch*, const char* block, int x, short y, int z);
int       se_batch