VoiceCraft.Addon (Bedrock Addon)

This repository contains practical Bedrock addon packages and the script-side McApi surface for custom world logic.

Use it when Minecraft Bedrock is the source of player/entity state. The addon connects Bedrock worlds to the VoiceCraft server through either McHttp or McWss, then exposes bind flow, UI, events, and packet helpers for world scripts.

Quick links:

Packages

Package	Purpose	Use when
`Basic`	ready-to-use bind flow, settings UI, in-game voice indicators, common script events	you want a working reference or default Bedrock behavior
`Core.McHttp`	HTTP transport package	you run Bedrock Dedicated Server
`Core.McWss`	websocket / command-tunnel transport package	you run a local Bedrock world or test setup

Most real Bedrock setups combine a transport package with the behavior/UI pieces needed by the world.

Version alignment

VoiceCraft v1.6.1 requires updating the addon packages together with the client/server release. This release includes in-game voice icons, auto connection quality-of-life, broadcasted events, and McHttp/McWss disconnect fixes that depend on the matching addon-side packages.

Do not upgrade the server/client and leave an old addon package in the world. Mismatched packages can connect but fail later during bind, event, or icon behavior.

Namespace

Across packages:

VoiceCraft.Namespace = "voicecraft"

Commands

Basic

voicecraft:vcbind <binding_key> permission: Any
voicecraft:vcsettings permission: GameDirectors

Core.McHttp

voicecraft:vcconnect <hostname> <token> permission: GameDirectors

Core.McWss

voicecraft:vcconnect <token> permission: Host
voicecraft:data_tunnel [max_string_length] [data] permission: Host

What the Basic package gives you

bind / unbind flow
player settings UI
effect toggles
script events for automation
in-game indicators used by supported releases

Start from Basic if you want to understand the expected player experience before writing custom addon logic.

Bind flow details

From the current implementation:

a new network entity receives a random 5-character binding key
entity description is updated with the key prompt
player runs voicecraft:vcbind <key>
entity binds to the player
on leave, unbind happens and a new key is generated

Script events:

voicecraft:onPlayerBind
voicecraft:onPlayerUnbind

VoiceCraft v1.6.1 also broadcasts more addon-side lifecycle and packet events so custom worlds can react without polling the transport layer directly.

The binding key is intentionally short because it is typed in game. Treat it as a temporary link token, not as a long-term secret.

Effects UI

voicecraft:vcsettings currently exposes:

Visibility
Proximity
Directional
Proximity Echo
Echo
Proximity Muffle
Muffle

Effects are sent through McApiSetEffectRequestPacket.

What you can customize

bind / unbind policy
role or tag based restrictions
world ID rules
position / rotation update behavior
staff forms through @minecraft/server-ui
packet handlers around the McApi surface

Customize only after a basic stock setup works. That gives you a known-good baseline for transport, bind, and position behavior.

Current limitations

Core.McWss stability depends on command and payload limits
host/provider restrictions can block the network path required by Core.McHttp
custom packet handlers need testing on the target Bedrock version

Recommended setup: BDS

enable McHttpConfig.Enabled = true
ensure BDS can reach McHttpConfig.Hostname
copy the Core.McHttp package
run voicecraft:vcconnect <hostname> <token>
validate bind with voicecraft:vcbind <key>

Recommended setup: local world

enable McWss
install Core.McWss
run /connect
run voicecraft:vcconnect <token>
keep voicecraft:data_tunnel aligned with server config

Validation checklist

correct transport package is installed
both behavior and resource packs are active
vcconnect uses the token from the matching server config section
player can bind with voicecraft:vcbind <key>
player movement changes position data in VoiceCraft
effects UI opens for authorized users