Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
The diff you're trying to view is too large. We only load the first 3000 changed files.
63 changes: 63 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
name: CI

on:
push:
pull_request:
# Weekly
schedule:
- cron: '0 6 * * 1'
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

env:
VFLAGS: -no-parallel

jobs:
# Building V takes longer than every check here put together, so they share
# one build rather than running as separate jobs.
checks:
name: Checks
runs-on: ubuntu-latest
steps:
- name: Checkout V
uses: actions/checkout@v7
with:
repository: vlang/v

- name: Checkout protocol
uses: actions/checkout@v7
with:
path: protocol

- name: Build V
run: |
make
echo "$GITHUB_WORKSPACE" >> "$GITHUB_PATH"

- name: Install nbt
run: v install bedrock-v.nbt

- name: Link the module into V's module path
run: ln -s "$GITHUB_WORKSPACE/protocol" "$HOME/.vmodules/protocol"

# - name: Verify formatting
# working-directory: protocol
# run: v fmt -verify .

- name: Vet
working-directory: protocol
run: v vet .

- name: Test
working-directory: protocol
run: v test tests

- name: Build and run the example
working-directory: protocol
run: v run examples/roundtrip.v
54 changes: 28 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,59 +2,61 @@

A Minecraft: Bedrock Edition network protocol implementation in V.

## Versions
## Scope

Packets live under versioned modules in `version/`. Each supported protocol
version ships its own packet pool, later versions only materialize the packets,
types and enums that changed and inherit the rest from earlier modules.
Current version: **1.26.50, protocol 2192**.

The latest supported version lives in `protocol.current`. Older releases remain
available under their numbered `protocol.version` modules.
```
packets/ one file per packet
types/ the types packets carry on the wire
enums/ the enums they use
model/ the types callers work with, independent of the wire layout
serializer/ the reader and writer
```

## Dependency: nbt

This project consumes the standalone network-NBT codec from
[bedrock-v/nbt](https://github.com/bedrock-v/nbt) via `import nbt`. Install it into
your V module path before building:
[bedrock-v/nbt](https://github.com/bedrock-v/nbt). Install it into your V module
path before building:

```bash
git clone https://github.com/bedrock-v/nbt ~/.vmodules/nbt
v install bedrock-v.nbt
```

## Build and Run
## Tests

```bash
v -shared -skip-unused . # compile the library
v -path 'src|@vlib|@vmodules' run examples/roundtrip.v
v -path 'src|@vlib|@vmodules' run examples/all_versions.v
v test tests # the test suite
v run examples/roundtrip.v
```

## Usage

```v
import protocol
import protocol.serializer
import protocol.version
import protocol.current
import protocol.version.v662.packets as packets_662
import protocol.packets

mut pool := current.new_pool()
println('proto=${current.proto_version.protocol_id()} mc=${current.proto_version.minecraft_version()}')
mut pool := protocol.new_pool()
println('proto=${protocol.protocol_id} mc=${protocol.minecraft_version}')

// encode any packet from the pool's version slice
packet := &packets_662.RequestNetworkSettingsPacket{
client_network_version: i32(current.proto_version.protocol_id())
packet := &packets.RequestNetworkSettingsPacket{
client_network_version: i32(protocol.protocol_id)
}
bytes := protocol.encode_packet_to_bytes(packet)

// decode straight from bytes
mut r := serializer.new_reader(bytes)
decoded := pool.decode(mut r)!
if decoded is packets_662.RequestNetworkSettingsPacket {
if decoded is packets.RequestNetworkSettingsPacket {
println('decoded=${decoded.name()} client_network_version=${decoded.client_network_version}')
}

// pick a pool from a client's protocol id
v := version.from_protocol_id(1001)
println('selected=${v} mc=${v.minecraft_version()}')
```

## Tests

`tests/` exercises the module from outside, the way a dependent does.
`roundtrip_test.v` encodes and decodes every packet the pool registers and
compares the result against a recorded baseline, so a packet that stops
round-tripping is caught even though the suite has no wire fixtures yet.
62 changes: 62 additions & 0 deletions constants.v
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
module protocol

import protocol.enums

// The wire values the game carries as plain numbers rather than as a type. A
// caller that spells one of these out by hand has no way of noticing when the
// game moves it.

pub const difficulty_peaceful = int(0)
pub const difficulty_easy = int(1)
pub const difficulty_normal = int(2)
pub const difficulty_hard = int(3)

pub const game_type_survival = int(0)
pub const game_type_creative = int(1)
pub const game_type_adventure = int(2)
pub const game_type_survival_spectator = int(3)
pub const game_type_creative_spectator = int(4)
pub const game_type_default = int(5)
pub const game_type_spectator = int(6)

// Ability indices are bit positions in the ability layers, so they are needed
// as numbers even though the enum names them.
pub const ability_build = int(enums.AbilitiesIndex.build)
pub const ability_mine = int(enums.AbilitiesIndex.mine)
pub const ability_doors_and_switches = int(enums.AbilitiesIndex.doors_and_switches)
pub const ability_open_containers = int(enums.AbilitiesIndex.open_containers)
pub const ability_attack_players = int(enums.AbilitiesIndex.attack_players)
pub const ability_attack_mobs = int(enums.AbilitiesIndex.attack_mobs)
pub const ability_may_fly = int(enums.AbilitiesIndex.may_fly)
pub const ability_instabuild = int(enums.AbilitiesIndex.instabuild)
pub const ability_walk_speed = int(enums.AbilitiesIndex.walk_speed)
pub const ability_count = int(20)

// Actor metadata keys.
pub const meta_key_flags = u32(0)
pub const meta_key_color_index = u32(3)
pub const meta_key_name = u32(4)
pub const meta_key_air_supply = u32(7)
pub const meta_key_effect_color = u32(8)
pub const meta_key_effect_ambience = u32(9)
pub const meta_key_scale = u32(38)
pub const meta_key_air_supply_max = u32(42)
pub const meta_key_width = u32(53)
pub const meta_key_height = u32(54)
pub const meta_key_always_show_name_tag = u32(81)

// Bit positions inside the actor flags metadata value.
pub const entity_flag_show_name = 14
pub const entity_flag_always_show_name = 15
pub const entity_flag_can_climb = 19
pub const entity_flag_breathing = 35
pub const entity_flag_has_collision = 48
pub const entity_flag_affected_by_gravity = 49

pub const move_actor_flag_on_ground = int(1)

pub const level_event_particles_destroy_block = int(2001)
pub const level_event_particles_punch_block = int(2014)
pub const level_event_start_block_cracking = int(3600)
pub const level_event_stop_block_cracking = int(3601)
pub const level_event_update_block_cracking = int(3602)
153 changes: 153 additions & 0 deletions convert.v
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
module protocol

import protocol.enums
import protocol.model
import protocol.packets
import protocol.types
import bedrock_v.nbt

// The bridge between the version independent model types and the shapes the
// selected version puts on the wire. Callers work in model types and never
// have to know which of the two a packet happens to want.

// shield_runtime_id is the item the client draws a blocking pose for. It is a
// runtime id, so it moves with the item palette rather than with the protocol.
const shield_runtime_id = 358

pub fn actor_unique_id(value i64) types.ActorUniqueID {
return types.ActorUniqueID{
value: value
}
}

pub fn actor_runtime_id(value u64) types.ActorRuntimeID {
return types.ActorRuntimeID{
value: value
}
}

pub fn vec3(v model.Vector3) [3]f32 {
return [v.x, v.y, v.z]!
}

pub fn vec3_from_array(v [3]f32) model.Vector3 {
return model.Vector3{v[0], v[1], v[2]}
}

pub fn block_pos(v model.BlockPosition) types.NetworkBlockPosition {
return types.NetworkBlockPosition{
x: i32(v.x)
y: i32(v.y)
z: i32(v.z)
}
}

pub fn block_pos_from(v types.NetworkBlockPosition) model.BlockPosition {
return model.BlockPosition{
x: int(v.x)
y: int(v.y)
z: int(v.z)
}
}

// block_pos_from_legacy reads the older of the two block position shapes, which
// the packets that predate types.NetworkBlockPosition still carry.
pub fn block_pos_from_legacy(v types.BlockPos) model.BlockPosition {
return model.BlockPosition{
x: int(v.x)
y: int(v.y)
z: int(v.z)
}
}

pub fn item_descriptor(item model.ItemStack) types.NetworkItemStackDescriptor {
return types.NetworkItemStackDescriptor{
id: i16(item.id)
stack_size: u16(item.count)
aux_value: u32(item.meta)
block_runtime_id: u32(item.block_runtime_id)
user_data_buffer: item.raw_extra_data
blocking: item.id == shield_runtime_id
}
}

pub fn item_instance(item model.ItemStack) types.NetworkItemInstanceDescriptor {
return types.NetworkItemInstanceDescriptor{
id: i32(item.id)
stack_size: u16(item.count)
aux_value: u32(item.meta)
block_runtime_id: i32(item.block_runtime_id)
user_data_buffer: item.raw_extra_data
blocking: item.id == shield_runtime_id
}
}

pub fn item_descriptor_v2(item model.ItemStack) types.NetworkItemStackDescriptorV2 {
return item_descriptor_v2_tracked(item, 0)
}

pub fn item_descriptor_v2_tracked(item model.ItemStack, net_id int) types.NetworkItemStackDescriptorV2 {
mut d := types.NetworkItemStackDescriptorV2{
id: i16(item.id)
stack_size: u16(item.count)
aux_value: u32(item.meta)
block_runtime_id: u32(item.block_runtime_id)
user_data_buffer: item.raw_extra_data
blocking: item.id == shield_runtime_id
}
if item.count > 0 && item.id != 0 && net_id != 0 {
d.net_id = i32(net_id)
}
return d
}

pub fn item_stack_from_descriptor_v2(item types.NetworkItemStackDescriptorV2) model.ItemStack {
return model.ItemStack{
id: int(item.id)
count: int(item.stack_size)
meta: int(item.aux_value)
block_runtime_id: int(item.block_runtime_id)
raw_extra_data: item.user_data_buffer
}
}

pub fn level_sound_event(event_name string, position model.Vector3, data i32, actor_identifier string, entity_unique_id u64) &packets.LevelSoundEventPacket {
mut packet := &packets.LevelSoundEventPacket{
event_name: event_name
data: data
actor_identifier: actor_identifier
entity_unique_id: entity_unique_id
}
packet.position[0] = position.x
packet.position[1] = position.y
packet.position[2] = position.z
return packet
}

pub fn rotation_byte(value f32) i8 {
mut scaled := int(value * 256.0 / 360.0)
scaled %= 256
if scaled < 0 {
scaled += 256
}
return i8(u8(scaled))
}

pub fn uuid_from_bytes(b []u8) types.Uuid {
mut uuid := types.Uuid{}
for i := 0; i < 16 && i < b.len; i++ {
uuid.bytes[i] = b[i]
}
return uuid
}

pub fn empty_nbt() nbt.RootTag {
return nbt.RootTag{
name: ''
tag: nbt.Tag(nbt.new_compound())
}
}

pub fn game_type(value int) enums.GameType {
return unsafe { enums.GameType(value) }
}
Loading
Loading