@mcbe-mods/ipc

Inter-Pack Communication system for Minecraft Bedrock Edition Script API.

Built on scriptEvent — no commands, no binary protocols, just JSON + LZ-string compression + chunked transfer.

Install

npm install @mcbe-mods/ipc

Usage

import { IPC } from '@mcbe-mods/ipc'

const ipc = new IPC({ namespace: 'myAddon' })
// scriptEvent ID → ipc:myAddon

One-way message

ipc.send('chat', { text: 'hello', sender: 'alice' })

ipc.on<{ text: string, sender: string }>('chat', (data) => {
  console.log(data.text)
})

Request / Response (RPC)

const res = await ipc.invoke<Req, Res>('inv.get', { slot: 5 })

ipc.handle<Req, Res>('inv.get', (req) => {
  return { item: 'stone', count: 1 }
})

Cancel subscription

const off = ipc.on('chat', handler)
off()

Custom serializer

import type { Deserializer, Serializer } from '@mcbe-mods/ipc'

const mySer: Serializer<MyType> = { serialize: v => JSON.stringify(v) }
const myDeser: Deserializer<MyType> = { deserialize: s => JSON.parse(s) }

ipc.send('channel', mySer, data)
ipc.on('channel', myDeser, (data) => {
  // ...
})

Options

interface IPCOptions {
  /**
   * Namespace for script events: `ipc:<namespace>`.
   * All addons with the same namespace can communicate.
   * @default 'global'
   */
  namespace?: string
  /**
   * Max bytes per chunk before splitting.
   *
   * Minecraft's `/scriptevent` has a **2048-byte** limit:
   * @see https://learn.microsoft.com/en-us/minecraft/creator/reference/content/commandsreference/examples/commands/scriptevent?view=minecraft-bedrock-stable#usage
   *
   * With Base64, 1 char = 1 byte, so safe value satisfies
   * `chunkSize + JSON(wrapper) ≤ 2048`.
   * @default 1800
   */
  chunkSize?: number
  /**
   * Raw JSON payloads larger than this are lz-string compressed before sending.
   * @default 800
   */
  compressThreshold?: number
  /**
   * Chunk reassembly timeout in milliseconds.
   * @default 5000
   */
  chunkTimeout?: number
  /**
   * Max serialized packet size in characters. Throws if exceeded.
   * @default 1_000_000
   */
  maxPacketSize?: number
}

License

MIT License