Skip to content

Commit e8fcf11

Browse files
lil-jon-crunklil-jon-crunk
authored
Merge pull request #1 from AvionBlock/dev
Some updates
2 parents 4db774e + b3e82cb commit e8fcf11

20 files changed

Lines changed: 845 additions & 14 deletions

‎content/en/1.start/1.overview.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,4 @@ VoiceCraft consists of three core parts:
2929
- [Quick Start](/en/start/quick-start)
3030
- [Client Installation](/en/client/installation)
3131
- [Server Installation](/en/server/installation)
32+
- [Ecosystem (VoiceCraft / GeyserVoice / Addon)](/en/ecosystem/overview)

‎content/en/1.start/2.quick-start.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44

55
1. Open the [latest release](https://github.com/AvionBlock/VoiceCraft/releases/latest).
66
2. Download the archive for your platform:
7-
- `VoiceCraft.Server.Windows.x64.zip` (or `x86`/`arm64`)
8-
- `VoiceCraft.Server.Linux.x64.zip` (or `arm`/`arm64`)
7+
- `VoiceCraft.Server.Windows.x64.zip` (or `x86`/`arm64`)
8+
- `VoiceCraft.Server.Linux.x64.zip` (or `arm`/`arm64`)
99

1010
## 2) Run the Server
1111

‎content/en/4.minecraft/1.mchttp-bds.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,17 +56,19 @@ In `world_resource_packs.json`, add:
5656
In world, run:
5757

5858
```text
59-
/vcconnect "http://<VOICECRAFT_HOST>:<PORT>" <LOGIN_TOKEN>
59+
/voicecraft:vcconnect "http://<VOICECRAFT_HOST>:<PORT>" <LOGIN_TOKEN>
6060
```
6161

6262
Example:
6363

6464
```text
65-
/vcconnect "http://127.0.0.1:9050" e4ad1f7e-4f90-4b21-bc15-6febe580bf1c
65+
/voicecraft:vcconnect "http://127.0.0.1:9050" e4ad1f7e-4f90-4b21-bc15-6febe580bf1c
6666
```
6767

6868
Use `LOGIN_TOKEN` from `McHttpConfig.LoginToken` in `ServerProperties.json`.
6969

70+
If your Bedrock build supports a short alias, `/vcconnect` may also work, but the safe/default form is `voicecraft:vcconnect`.
71+
7072
## Common Issues
7173

7274
- `HttpListenerException` on Windows: you may need `netsh http add iplisten 127.0.0.1`.

‎content/en/4.minecraft/2.mcwss-singleplayer.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,11 +43,13 @@ Example:
4343
2. Authenticate with token:
4444

4545
```text
46-
/vcconnect <LOGIN_TOKEN>
46+
/voicecraft:vcconnect <LOGIN_TOKEN>
4747
```
4848

4949
Use `LOGIN_TOKEN` from `McWssConfig.LoginToken`.
5050

51+
If your Bedrock build supports a short alias, `/vcconnect` may also work, but `voicecraft:vcconnect` is the recommended form.
52+
5153
## Tuning
5254

5355
If you see lag/crashes:

‎content/en/5.operations/2.troubleshooting.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@ Check:
1717
## McHttp Not Working
1818

1919
- Check `McHttpConfig.Enabled = true`.
20-
- Check `LoginToken` used in `/vcconnect` command.
20+
- Check `LoginToken` used in `/voicecraft:vcconnect` (or `/vcconnect` if alias is supported).
2121
- Ensure addon is attached to the world and permissions are configured.
2222

2323
## McWss Not Working
2424

2525
- Check `McWssConfig.Enabled = true`.
26-
- Run `/connect <host:port>` before `/vcconnect`.
26+
- Run `/connect <host:port>` before `/voicecraft:vcconnect`.
2727
- Verify token.
2828

2929
## No Audio

‎content/en/6.ecosystem/1.overview.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# VoiceCraft Ecosystem
2+
3+
This section documents the 3 repositories that are usually deployed together:
4+
5+
1. `VoiceCraft` — core stack (client + server + protocol + Bedrock integration).
6+
2. `GeyserVoice` — Java plugin for Paper/Velocity/Bungeecord, bridge between Java/Geyser and VoiceCraft.
7+
3. `VoiceCraft.Addon` — Bedrock addon (Basic/McHttp/McWss) for world-to-VoiceCraft API integration.
8+
9+
## When to use what
10+
11+
- Bedrock Dedicated Server: usually `VoiceCraft.Server` + `VoiceCraft.Addon.Core.McHttp`.
12+
- Singleplayer Bedrock world: `VoiceCraft` client + `Core.McWss` package.
13+
- Java server with Geyser/Floodgate: `GeyserVoice` on Paper server.
14+
- Java network with Geyser/Floodgate: `GeyserVoice` on proxy (Velocity/Bungee) + `GeyserVoice` on Paper (proxy mode).
15+
16+
## Quick interaction map
17+
18+
```mermaid
19+
flowchart LR
20+
A[VoiceCraft Client] --> B[VoiceCraft Server UDP]
21+
C[Bedrock World/Add-on] --> D[McHttp or McWss Layer]
22+
D --> B
23+
E[Java oor Bedrock Player via Geyser] --> F[GeyserVoice Plugin]
24+
F --> B
25+
```
26+
27+
## Continue with
28+
29+
- [VoiceCraft (repository and build)](/en/ecosystem/voicecraft-repository)
30+
- [GeyserVoice (Java/Geyser)](/en/ecosystem/geyservoice)
31+
- [VoiceCraft.Addon (Bedrock Addon)](/en/ecosystem/voicecraft-addon)
32+
- [Integration recipes](/en/ecosystem/integration-recipes)

‎content/en/6.ecosystem/2.voicecraft-repository.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# VoiceCraft (Repository and Build)
2+
3+
Repository: [AvionBlock/VoiceCraft](https://github.com/AvionBlock/VoiceCraft)
4+
5+
## Repository structure
6+
7+
- `VoiceCraft.Client/*` — platform clients (Windows/Linux/macOS/Android/iOS/Web).
8+
- `VoiceCraft.Server` — voice transport server and McHttp/McWss API layer.
9+
- `VoiceCraft.Core`, `VoiceCraft.Network` — shared models, protocol, network logic.
10+
11+
## Build requirements
12+
13+
From source code:
14+
15+
- .NET SDK `9.0.312` (`global.json`, rollForward `latestMinor`).
16+
17+
Check locally:
18+
19+
```bash
20+
dotnet --info
21+
```
22+
23+
## Build and run
24+
25+
```bash
26+
git clone https://github.com/AvionBlock/VoiceCraft.git
27+
cd VoiceCraft
28+
29+
dotnet restore
30+
dotnet build -c Release
31+
```
32+
33+
Run server:
34+
35+
```bash
36+
dotnet run --project VoiceCraft.Server -- --language en-US
37+
```
38+
39+
Useful server root options:
40+
41+
- `--language <locale>` — server log language.
42+
- `--exit-on-invalid-properties` — exit process if `ServerProperties.json` is invalid.
43+
44+
## Client builds (examples)
45+
46+
```bash
47+
dotnet build VoiceCraft.Client/VoiceCraft.Client.Windows -c Release
48+
dotnet build VoiceCraft.Client/VoiceCraft.Client.Linux -c Release
49+
dotnet build VoiceCraft.Client/VoiceCraft.Client.MacOS -c Release
50+
```
51+
52+
Mobile targets typically need their platform SDK toolchains.
53+
54+
## Embedded locales
55+
56+
From current client/server embedded resources:
57+
58+
- `en-US`
59+
- `ru-RU`
60+
- `nl-NL`
61+
- `de-DE`
62+
- `pl-PL`
63+
- `zh-CN`
64+
- `zh-TW`
65+
66+
## Production setup checklist
67+
68+
1. Run `VoiceCraft.Server` once to generate `config/ServerProperties.json`.
69+
2. Replace `LoginToken` values in `McHttpConfig` and `McWssConfig`.
70+
3. Validate `Port`, `Hostname`, and `MaxClients`.
71+
4. Open only required ports on firewall/NAT.
72+
5. Avoid changing `DisabledPacketTypes` unless you fully understand packet flow.
73+
74+
## Addon integration
75+
76+
- For BDS: usually `McHttpConfig.Enabled = true`.
77+
- For singleplayer worlds: usually `McWssConfig.Enabled = true` with `voicecraft:data_tunnel`.
78+
79+
See also:
80+
81+
- [VoiceCraft.Addon](/en/ecosystem/voicecraft-addon)
82+
- [Integration recipes](/en/ecosystem/integration-recipes)

‎content/en/6.ecosystem/3.geyservoice.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# GeyserVoice (Java/Geyser Bridge)
2+
3+
Repository: [AvionBlock/GeyserVoice](https://github.com/AvionBlock/GeyserVoice)
4+
5+
`GeyserVoice` links Java server infrastructure (Paper/Folia + proxy) to `VoiceCraft.Server`.
6+
7+
## Supported plugin platforms
8+
9+
From source code:
10+
11+
- Paper/Folia (`io.greitan.avion.paper.GeyserVoice`)
12+
- Velocity (`io.greitan.avion.velocity.GeyserVoice`)
13+
- Bungeecord (`io.greitan.avion.bungeecord.GeyserVoice`)
14+
15+
## Installation
16+
17+
1. Download plugin `.jar`.
18+
2. Put it into `plugins/`:
19+
- standalone Paper,
20+
- or proxy + backend Paper servers.
21+
3. Start server once to generate `plugins/GeyserVoice/config.yml`.
22+
4. Edit `config.yml`.
23+
5. Run `/voice reload`.
24+
25+
## `config.yml` reference
26+
27+
`config` block:
28+
29+
- `debug` — plugin debug mode.
30+
- `lang` — plugin message language.
31+
- `host` — `VoiceCraft.Server` host.
32+
- `port` — `VoiceCraft.Server` port.
33+
- `server-key` — server auth key used by plugin.
34+
- `auto-reconnect` — reconnect when transport is lost.
35+
- `server-behind-proxy` — required for Paper behind Velocity/Bungee.
36+
37+
`voice` block:
38+
39+
- `proximity-distance` — proximity logic distance.
40+
- `proximity-toggle` — enable/disable proximity mode.
41+
- `voice-effects` — enable/disable voice effects.
42+
- `not-in-voice-symbol` / `in-voice-symbol` — status symbols.
43+
- `send-binded-message` — show message on bind.
44+
- `send-disconnect-message` — show message on disconnect.
45+
- `send-voip-disconnect-message` — show message when VoIP transport closes.
46+
- `send-connection-lost-message` — show message when connection is lost.
47+
- `position-task-interval` — position update interval in ticks.
48+
49+
`players` block is internal cache/autobind data.
50+
51+
## `/voice` commands
52+
53+
From `BaseVoiceCommand`:
54+
55+
- `connect <host> <port> <key>`
56+
- `reconnect [true|false]`
57+
- `disconnect`
58+
- `settings`
59+
- `bind <key>`
60+
- `bindfake <key> <name>`
61+
- `updatefake <key>`
62+
- `clearautobind`
63+
- `reload`
64+
65+
## Permissions
66+
67+
From `plugin.yml` and `bungee.yml`:
68+
69+
- `voice.cmd` (default: true)
70+
- `voice.connect` (op)
71+
- `voice.reconnect` (op)
72+
- `voice.disconnect` (op)
73+
- `voice.settings` (op)
74+
- `voice.bind` (true)
75+
- `voice.bindfake` (op)
76+
- `voice.reload` (op)
77+
78+
## Proxy mode (important)
79+
80+
If backend Paper is behind Velocity/Bungee and plugin is present on proxy:
81+
82+
1. Set `server-behind-proxy: true` on backend Paper.
83+
2. Do not set backend `host/port/key` as source of truth.
84+
3. Keep valid `host/port/server-key` on proxy.
85+
86+
In Paper code, reconnect is intentionally skipped when `server-behind-proxy: true`.
87+
88+
## Integration internals
89+
90+
- Plugin messaging channel: `geyservoice:main`.
91+
- In proxy mode, dimensions/world IDs are namespaced with backend server name.
92+
- HTTP transport calls to `VoiceCraft.Server` use a 5-second timeout.
93+
94+
## Current code limitations
95+
96+
- `updatefake` is currently a placeholder.
97+
- `settings` command exists but currently has minimal practical logic.
98+
99+
## Production checklist
100+
101+
1. Restrict `/voice connect|reload` to staff roles.
102+
2. Use `server-behind-proxy` only on real proxy-backed backends.
103+
3. Ensure stable proxy routing to `VoiceCraft.Server`.
104+
4. Configure process supervision (systemd/panel/screen).

‎content/en/6.ecosystem/4.voicecraft-addon.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# VoiceCraft.Addon (Bedrock Addon)
2+
3+
Repository: [AvionBlock/VoiceCraft.Addon](https://github.com/AvionBlock/VoiceCraft.Addon)
4+
5+
This repository contains 3 practical packages:
6+
7+
1. `Basic` — ready-to-use addon with bind flow and effects UI.
8+
2. `Core.McHttp` — McHttp transport (typical for BDS).
9+
3. `Core.McWss` — command tunnel transport for singleplayer/world use.
10+
11+
## API namespace
12+
13+
Across packages:
14+
15+
- `VoiceCraft.Namespace = "voicecraft"`
16+
17+
## Addon commands
18+
19+
### Basic
20+
21+
- `voicecraft:vcbind <binding_key>`
22+
- permission: `Any`
23+
- binds a player to VoiceCraft network entity.
24+
- `voicecraft:vcsettings`
25+
- permission: `GameDirectors`
26+
- opens effects/player settings UI.
27+
28+
### Core.McHttp
29+
30+
- `voicecraft:vcconnect <hostname> <token>`
31+
- permission: `GameDirectors`
32+
- connects world to McHttp endpoint.
33+
34+
### Core.McWss
35+
36+
- `voicecraft:vcconnect <token>`
37+
- permission: `Host`
38+
- connects to McWss.
39+
- `voicecraft:data_tunnel [data]`
40+
- permission: `Host`
41+
- bi-directional packet tunnel (`|`-separated chunks, around 1000 chars per response batch).
42+
43+
## Bind flow details (Basic)
44+
45+
From `BindingManager.ts`:
46+
47+
1. A new network entity receives a random 5-char binding key.
48+
2. Entity description is updated to: `Welcome! Your binding key is ...`.
49+
3. Player runs `voicecraft:vcbind <key>`.
50+
4. Entity is mapped to player; name/description are updated.
51+
5. On player leave, entity is unbound and gets a new key.
52+
53+
Script events emitted:
54+
55+
- `voicecraft:onPlayerBind`
56+
- `voicecraft:onPlayerUnbind`
57+
58+
Useful for custom world automation.
59+
60+
## Effects UI (Basic)
61+
62+
`voicecraft:vcsettings` currently exposes:
63+
64+
- Visibility
65+
- Proximity
66+
- Directional
67+
- Proximity Echo
68+
- Echo
69+
- Proximity Muffle
70+
- Muffle
71+
72+
Effects are applied by bitmask through `McApiSetEffectRequestPacket`.
73+
74+
## What to customize
75+
76+
- Bind/unbind policy (tags, roles, game modes).
77+
- worldId/position/rotation update logic.
78+
- Staff UI forms (`@minecraft/server-ui`) for managing active bindings.
79+
80+
## Known limitations in current code
81+
82+
- Player action menu `Kick` in `Basic` is currently `Not implemented`.
83+
- `Core.McWss` stability heavily depends on command throughput and payload sizing limits.
84+
85+
## Recommended setup: BDS
86+
87+
1. Enable `McHttpConfig.Enabled = true` on `VoiceCraft.Server`.
88+
2. Ensure `McHttpConfig.Hostname` is reachable from BDS.
89+
3. Get `LoginToken` from `ServerProperties.json`.
90+
4. Install `Core.McHttp` package.
91+
5. Run `voicecraft:vcconnect <hostname> <token>`.
92+
6. Validate bind with `voicecraft:vcbind <key>`.
93+
94+
## Recommended setup: singleplayer/world
95+
96+
1. Enable McWss on VoiceCraft side.
97+
2. Install `Core.McWss` package.
98+
3. Run `voicecraft:vcconnect <token>`.
99+
4. Keep `voicecraft:data_tunnel` aligned with `ServerProperties.json` command name.

0 commit comments

Comments
 (0)