McWss for Singleplayer Worlds

McWss is the websocket / command-tunnel transport mostly used for local worlds and lightweight Bedrock setups.

When to use it

Use McWss when:

  • you play in a local Bedrock world
  • you want a quick singleplayer setup
  • you are testing addon logic without a dedicated BDS host

Important limitations

  • usually less stable than McHttp
  • command throughput and payload size matter a lot
  • not the default recommendation for large public production environments

Requirements

  1. VoiceCraft.Server with McWssConfig.Enabled = true
  2. VoiceCraft.Addon.Core.McWss.zip
  3. Bedrock build that supports the required websocket / script functionality

Helpful links:

VoiceCraft server config

Typical setup:

{
  "McWssConfig": {
    "Enabled": true,
    "LoginToken": "replace-with-token",
    "Hostname": "ws://127.0.0.1:9051/",
    "MaxClients": 1,
    "MaxTimeoutMs": 10000,
    "DataTunnelCommand": "voicecraft:data_tunnel",
    "CommandsPerTick": 3,
    "MaxByteLengthPerCommand": 300,
    "DisabledPacketTypes": []
  }
}

Installation

Option 1: import as .mcaddon

  1. Rename archive to VoiceCraft.Addon.Core.McWss.mcaddon.
  2. Open it so Minecraft imports the addon.
  3. Enable the behavior pack and resource pack in the world.

Option 2: manual copy

  1. Extract the archive.
  2. Copy RP and BP to the Bedrock directories.
  3. Enable both packs in the target world.

Connection flow

Step 1: connect the world websocket

/connect <VOICECRAFT_HOST>:<MCWSS_PORT>

Example:

/connect 127.0.0.1:9051

Step 2: authenticate the addon

/voicecraft:vcconnect <LOGIN_TOKEN>

Use McWssConfig.LoginToken.

Data tunnel

The addon uses:

  • voicecraft:data_tunnel

This must stay aligned with McWssConfig.DataTunnelCommand.

If you rename one side and not the other, the bridge breaks.

The command currently carries:

  • optional max string length argument
  • packed payload data argument

Tuning

If you see lag or packet instability:

  • lower CommandsPerTick
  • review MaxByteLengthPerCommand
  • avoid large burst updates
  • test with fewer active entities

When to switch to another transport

Move to McHttp when:

  • you run a real dedicated Bedrock server
  • you want a cleaner production deployment
  • command tunnel instability becomes a problem

In that case, continue with McHttp for BDS.