Inter-Plugin Communication (IPC)

Pisual exposes a message-based IPC protocol on Pumpkin MC. Other plugins running on the server can dispatch JSON messages to spawn, update, relocate, or remove holograms programmatically at runtime.

Protocol Basics

Pisual handles IPC calls through Pumpkin's native pumpkin_plugin_api::ipc subsystem. When sending an IPC message, serialize the request struct to a JSON byte vector (Vec<u8>) and target plugin identifier "Pisual".

• Transport: Native WebAssembly component model IPC channel.
• Data Encoding: UTF-8 JSON payloads.
• Target Identifier: "Pisual" (case-sensitive).
• Response: Serialized JSON object implementing the standard IpcResponse wrapper.

Integration Guide

Add the dependencies below to your calling plugin's Cargo.toml:

[dependencies]
pumpkin-plugin-api = "0.1.0-dev"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Dispatching a message to Pisual from Rust:

use pumpkin_plugin_api::ipc;

pub fn spawn_hologram() -> Result<(), String> {
    // 1. Build JSON request payload
    let payload = serde_json::to_vec(&serde_json::json!({
        "action": "create",
        "id": "welcome_board",
        "world": "world",
        "position": [0.0, 65.0, 0.0],
        "lines": ["&6&lSERVER SPAWN", "&7Welcome to Pumpkin MC!"]
    })).map_err(|e| e.to_string())?;

    // 2. Send message to Pisual
    let response_bytes = ipc::send_ipc_message("Pisual".to_string(), payload)
        .map_err(|e| format!("IPC transport failed: {e}"))?;

    // 3. Parse JSON response
    let response: serde_json::Value = serde_json::from_slice(&response_bytes)
        .map_err(|e| format!("Malformed response: {e}"))?;

    if response["success"].as_bool().unwrap_or(false) {
        Ok(())
    } else {
        let err = response["error"].as_str().unwrap_or("Unknown error");
        Err(err.to_string())
    }
}

Interactive Request Builder

Select an action and configure fields to generate formatted JSON payloads and caller Rust snippets.

Action Reference

{
  "action": "create",
  "id": "rules_board",
  "world": "world",
  "position": [10.0, 65.0, 0.0],
  "lines": ["&c&lSERVER RULES", "&f1. Respect players"],
  "billboard": "vertical"
}

{
  "action": "create_ram",
  "id": "timer_arena_1",
  "world": "arena",
  "position": [50.0, 70.0, 50.0],
  "lines": ["&eMatch begins in: &a10s"]
}

{
  "action": "edit",
  "id": "rules_board",
  "lines": ["&c&lNEW RULES", "&aHave fun!"],
  "shadow": false
}

{
  "action": "move",
  "id": "rules_board",
  "world": "world_nether",
  "position": [0.0, 80.0, 0.0]
}

{
  "action": "delete",
  "id": "rules_board"
}

{
  "success": true,
  "data": {
    "id": "rules_board",
    "world_name": "world",
    "position": [10.0, 65.0, 0.0],
    "lines": ["&c&lSERVER RULES", "&f1. Respect players"],
    "billboard": "vertical",
    "shadow": true,
    "see_through": false,
    "scale": [1.0, 1.0, 1.0]
  }
}

{
  "action": "list"
}

Billboard Types

Determines how the hologram rotates relative to players in Minecraft:

Response Schema

Every IPC request receives an IpcResponse JSON structure:

pub struct IpcResponse {
    pub success: bool,
    pub message: Option<String>,
    pub error: Option<String>,
    pub data: Option<serde_json::Value>,
}

Error Handling

When success is false, the error field contains a descriptive failure string.