@mcbe-mods/ipc

Inter-Pack Communication for Minecraft Bedrock Edition Script API.

Fire-and-forget messaging with automatic chunking and optional pluggable compression.

Install

npm install @mcbe-mods/ipc

Usage

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

const ipc = new IPC({ namespace: 'myAddon' })

// Send a message
ipc.send('chat', { text: 'hello', sender: 'alice' })

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

// One-shot (auto-unsubscribes after first message)
ipc.once('greeting', (data) => {
  console.log('First message only:', data.text)
})

// Cancel subscription
const off = ipc.on('channel', handler)
off()

Events

ipc.events.on(EVENTS.ERROR, (err) => {
  console.error('IPC error:', err.message)
})

Lifecycle

ipc.dispose()

Options

interface IPCOptions {
  namespace?: string // default: 'global'
  chunkSize?: number // default: 1800 (max safe bytes per scriptEvent)
  compressThreshold?: number // default: 800 (only compress when payload exceeds this)
  compress?: DataCompressor // pluggable compression (e.g. @mcbe-mods/compress)
  maxPacketSize?: number // default: 1_000_000
  chunkTimeout?: number // default: 30_000 (ms)
  cipher?: ProtocolCipher // transport-layer encryption
}

Compression

Compression is optional and pluggable via the compress option. IPC compares the compressed result length against the original — if shorter, the compressed version is sent with a c flag; the receiver decompresses automatically.

Use the standalone @mcbe-mods/compress package:

import { Compressor } from '@mcbe-mods/compress'

const ipc = new IPC({ compress: new Compressor(), compressThreshold: 500 })

Or provide any custom implementation matching DataCompressor:

const ipc = new IPC({
  compress: {
    compress: s => myPack(s),
    decompress: s => myUnpack(s),
  },
})

Encryption

Transport-layer encryption is optional via the cipher option. All IPC payloads are encrypted before sending and decrypted on receipt.

Use the standalone @mcbe-mods/crypto package:

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

const cipher = Cipher.fromPassword('my-shared-secret')
const ipc = new IPC({ cipher })

// All messages are automatically encrypted/decrypted
ipc.send('secret-channel', { key: 'value' })
ipc.on('secret-channel', (data) => { /* decrypted */ })

Or provide any ProtocolCipher implementation:

const ipc = new IPC({
  cipher: {
    encrypt(s: string) { return myEncrypt(s) },
    decrypt(s: string) { return myDecrypt(s) },
  },
})

Messages that fail decryption are silently dropped (handled by the underlying Protocol layer).

License

MIT