Chunk batches: encode each column once a tick, its new sections on warm-up threads

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-18 18:47:55 +02:00
parent f422cbb79a
commit 1f2f2a9f6d
2 changed files with 415 additions and 148 deletions
+291 -75
View File
@@ -15,7 +15,13 @@ use horizon_protocol::{
registry::{Builtin, ceil_log2},
};
use horizon_world::nbt::Tag;
use std::{collections::HashMap, sync::Arc};
use std::{
collections::HashMap,
sync::{
Arc, OnceLock,
atomic::{AtomicUsize, Ordering},
},
};
const NON_AIR: u8 = 1;
const FLUID: u8 = 2;
@@ -83,12 +89,10 @@ pub fn block_entity_type(name: &str) -> Option<&'static str> {
/// Per-state facts and registry ids for encoding chunks.
pub struct ChunkEncoder {
flags: Vec<u8>,
/// What encoding a section needs, shared with the warm-up threads.
coder: Arc<SectionCoder>,
/// Block entity type id per state (-1 for none).
entity_types: Vec<i16>,
/// Network biome id per internal biome index.
pub biome_ids: Vec<i32>,
biome_bits: u8,
/// The block registry id of each state's block, for BlockEvent.
pub block_ids: Vec<i32>,
/// The save's tables, for the heightmaps.
@@ -104,6 +108,14 @@ pub struct ChunkEncoder {
sky: bool,
}
/// Per-state flags and biome ids: all a section's encoding reads.
struct SectionCoder {
flags: Vec<u8>,
/// Network biome id per internal biome index.
biome_ids: Vec<i32>,
biome_bits: u8,
}
/// A column's client heightmaps, valid while it holds the same sections.
struct Heights {
sections: Vec<std::sync::Weak<Section>>,
@@ -170,8 +182,151 @@ impl Layers {
}
}
impl SectionCoder {
/// LevelChunkSection.write, and its block entity blocks.
fn wire(&self, section: &Section) -> (Arc<[u8]>, Entities) {
let (encoded, entities) = self.section(section);
let mut w = horizon_protocol::buf::Writer::new();
encoded.write(&mut w);
(w.data.into(), entities.into())
}
fn section(&self, section: &Section) -> (horizon_protocol::chunk::Section, Vec<(u16, u32)>) {
let mut values = Vec::with_capacity(BLOCKS);
let (mut non_empty, mut fluids, mut entities) = (0i16, 0i16, Vec::new());
let mut count = |state: u32, n: i16| {
let f = self.flags.get(state as usize).copied().unwrap_or(0);
if f & NON_AIR != 0 {
non_empty += n;
if f & FLUID != 0 {
fluids += n;
}
}
f & ENTITY != 0
};
// One block everywhere (all air, mostly): what from_values would give.
let uniform = section.blocks.uniform();
if let Some(v) = uniform {
if count(v, BLOCKS as i16) {
entities = (0..BLOCKS as u16).map(|i| (i, v)).collect();
}
} else {
let mut unpacked = [0u32; BLOCKS];
section.unpack(&mut unpacked);
for (i, &v) in unpacked.iter().enumerate() {
if count(v, 1) {
entities.push((i as u16, v));
}
values.push(v as i32);
}
}
let biome_values: Vec<i32> = (0..BIOMES)
.map(|j| {
let internal = section.biomes.get(j) as u16;
self.biome_ids
.get(usize::from(internal))
.copied()
.unwrap_or(0)
})
.collect();
(
horizon_protocol::chunk::Section {
non_empty,
fluids,
states: match uniform {
Some(v) => Paletted {
bits: 0,
palette: vec![v as i32],
data: Vec::new(),
},
None => Paletted::from_values(
&values,
Strategy::Blocks,
crate::chunk::block_strategy().global_bits,
),
},
biomes: Paletted::from_values(&biome_values, Strategy::Biomes, self.biome_bits),
},
entities,
)
}
}
/// Sections kept before the ones no longer resident are dropped.
const CACHE_SWEEP: usize = 1 << 15;
/// Uncached sections below which a batch is encoded on the tick's thread
/// alone: waking the warm-up threads costs more than a few sections.
const WARM_MIN: usize = 16;
/// Sections a batch needs, each taken by whichever thread is free first,
/// and what each gave: its wire bytes and, with varying light, its layers.
struct Warm {
coder: Arc<SectionCoder>,
sections: Vec<Arc<Section>>,
next: AtomicUsize,
done: Vec<OnceLock<Warmed>>,
}
type Warmed = ((Arc<[u8]>, Entities), Option<Arc<Layers>>);
impl Warm {
/// Encode sections until none is left to take.
fn run(&self) {
loop {
let i = self.next.fetch_add(1, Ordering::Relaxed);
let Some(s) = self.sections.get(i) else {
return;
};
let light = matches!(s.light, Light::Full(_)).then(|| Arc::new(Layers::of(&s.light)));
let _ = self.done[i].set((self.coder.wire(s), light));
}
}
}
/// The warm-up threads (one per core besides the tick's) and the job they
/// take: its number, and the job while it has sections left to take.
struct WarmPool {
job: std::sync::Mutex<(u64, Option<Arc<Warm>>)>,
ready: std::sync::Condvar,
}
/// The warm-up threads, started the first time; none on a single core or
/// when no thread could start.
fn warm_pool() -> Option<&'static WarmPool> {
static POOL: OnceLock<Option<Arc<WarmPool>>> = OnceLock::new();
POOL.get_or_init(|| {
let threads = std::thread::available_parallelism().map_or(1, |n| n.get()) - 1;
let pool = Arc::new(WarmPool {
job: Default::default(),
ready: Default::default(),
});
let started = (0..threads)
.filter(|i| {
let pool = pool.clone();
std::thread::Builder::new()
.name(format!("horizon-chunk-encode-{i}"))
.spawn(move || {
let mut done = 0;
loop {
let job = {
let mut slot = pool.job.lock().unwrap();
while slot.0 == done {
slot = pool.ready.wait(slot).unwrap();
}
done = slot.0;
slot.1.clone()
};
if let Some(job) = job {
job.run();
}
}
})
.is_ok()
})
.count();
(started > 0).then_some(pool)
})
.as_deref()
}
impl ChunkEncoder {
/// `biome_names`: the internal biome list in order; `biome_registry`:
/// the synchronized biome entries in network order.
@@ -218,10 +373,12 @@ impl ChunkEncoder {
})
.collect();
Self {
flags,
coder: Arc::new(SectionCoder {
flags,
biome_ids,
biome_bits: ceil_log2(biome_registry.len()),
}),
entity_types,
biome_ids,
biome_bits: ceil_log2(biome_registry.len()),
block_ids,
tables: None,
cache: Default::default(),
@@ -297,7 +454,8 @@ impl ChunkEncoder {
/// LevelChunkSection.hasOnlyAir, negated.
fn non_air(&self, section: &Section) -> bool {
let non_air = |v: u32| self.flags.get(v as usize).copied().unwrap_or(0) & NON_AIR != 0;
let non_air =
|v: u32| self.coder.flags.get(v as usize).copied().unwrap_or(0) & NON_AIR != 0;
// The palette first: most sections are all air, or one block.
if !section.blocks.maybe_has(non_air) {
false
@@ -314,10 +472,7 @@ impl ChunkEncoder {
if let Some(wire) = self.cached(section, |e| e.wire.clone()) {
return wire;
}
let (encoded, entities) = self.section(section);
let mut w = horizon_protocol::buf::Writer::new();
encoded.write(&mut w);
let wire: (Arc<[u8]>, Entities) = (w.data.into(), entities.into());
let wire = self.coder.wire(section);
self.cached(section, |e| e.wire = Some(wire.clone()));
wire
}
@@ -340,71 +495,12 @@ impl ChunkEncoder {
.map(|t| i32::from(*t))
}
pub fn is_air(&self, state: u32) -> bool {
self.flags
self.coder
.flags
.get(state as usize)
.is_none_or(|f| f & NON_AIR == 0)
}
fn section(&self, section: &Section) -> (horizon_protocol::chunk::Section, Vec<(u16, u32)>) {
let mut values = Vec::with_capacity(BLOCKS);
let (mut non_empty, mut fluids, mut entities) = (0i16, 0i16, Vec::new());
let mut count = |state: u32, n: i16| {
let f = self.flags.get(state as usize).copied().unwrap_or(0);
if f & NON_AIR != 0 {
non_empty += n;
if f & FLUID != 0 {
fluids += n;
}
}
f & ENTITY != 0
};
// One block everywhere (all air, mostly): what from_values would give.
let uniform = section.blocks.uniform();
if let Some(v) = uniform {
if count(v, BLOCKS as i16) {
entities = (0..BLOCKS as u16).map(|i| (i, v)).collect();
}
} else {
let mut unpacked = [0u32; BLOCKS];
section.unpack(&mut unpacked);
for (i, &v) in unpacked.iter().enumerate() {
if count(v, 1) {
entities.push((i as u16, v));
}
values.push(v as i32);
}
}
let biome_values: Vec<i32> = (0..BIOMES)
.map(|j| {
let internal = section.biomes.get(j) as u16;
self.biome_ids
.get(usize::from(internal))
.copied()
.unwrap_or(0)
})
.collect();
(
horizon_protocol::chunk::Section {
non_empty,
fluids,
states: match uniform {
Some(v) => Paletted {
bits: 0,
palette: vec![v as i32],
data: Vec::new(),
},
None => Paletted::from_values(
&values,
Strategy::Blocks,
crate::chunk::block_strategy().global_bits,
),
},
biomes: Paletted::from_values(&biome_values, Strategy::Biomes, self.biome_bits),
},
entities,
)
}
/// The chunk column with its light and block entities.
/// The non-air sections of a column as bits (LevelChunkSection.hasOnlyAir).
fn occupied(&self, chunk: &Chunk) -> u64 {
@@ -442,6 +538,65 @@ impl ChunkEncoder {
self.body(chunk, &world.block_entities, self.around(chunk, world))
}
/// Encode the sections of these columns not cached yet before their
/// bodies are made, shared out to the warm-up threads: a batch of new
/// terrain costs mostly its sections' first encoding. This thread takes
/// sections too until none is left, then caches what is done; it never
/// waits for the other threads (they keep their results to themselves
/// until then), and a section one of them is still on is encoded again
/// by `body_in`, with the same bytes.
pub fn warm(&self, columns: &[&Chunk]) {
let sections: Vec<Arc<Section>> = {
let cache = self.cache.lock().unwrap();
columns
.iter()
.flat_map(|c| &c.sections[self.sections.clone()])
.filter(|s| {
cache
.get(&(Arc::as_ptr(s) as usize))
.is_none_or(|e| e.wire.is_none())
})
.cloned()
.collect()
};
if sections.len() < WARM_MIN {
return;
}
let Some(pool) = warm_pool() else {
return;
};
let job = Arc::new(Warm {
coder: self.coder.clone(),
done: sections.iter().map(|_| OnceLock::new()).collect(),
sections,
next: AtomicUsize::new(0),
});
{
let mut slot = pool.job.lock().unwrap();
slot.0 += 1;
slot.1 = Some(job.clone());
}
pool.ready.notify_all();
job.run();
// Every section is claimed: the job leaves the slot.
{
let mut slot = pool.job.lock().unwrap();
if slot.1.as_ref().is_some_and(|j| Arc::ptr_eq(j, &job)) {
slot.1 = None;
}
}
let mut cache = self.cache.lock().unwrap();
for (s, done) in job.sections.iter().zip(&job.done) {
if let Some((wire, light)) = done.get() {
let e = self.entry(&mut cache, s);
e.wire = Some(wire.clone());
if light.is_some() {
e.light = light.clone();
}
}
}
}
fn body(
&self,
chunk: &Chunk,
@@ -930,7 +1085,7 @@ mod tests {
/// The bytes on the wire for a section, encoded afresh.
fn fresh(encoder: &ChunkEncoder, section: &Section) -> Vec<u8> {
let mut w = horizon_protocol::buf::Writer::new();
encoder.section(section).0.write(&mut w);
encoder.coder.section(section).0.write(&mut w);
w.data
}
@@ -1077,6 +1232,67 @@ mod tests {
);
}
/// Columns whose sections the warm-up threads encoded give the bytes
/// each gives on its own, also with a column twice and its neighbours'
/// sections deciding the light layers.
#[test]
fn warmed_columns_give_the_same_bodies() {
let builtin = Builtin::parse(
r#"{"minecraft:block_entity_type": {"entries": {
"minecraft:sign": {"protocol_id": 7}}}}"#,
)
.unwrap();
let states = [
"minecraft:air",
"minecraft:stone",
"minecraft:water",
"minecraft:oak_sign",
]
.map(|n| (Arc::<str>::from(n), n.ends_with("water")));
let mut world = crate::world::World::new(horizon_world::registry::BlockStateId(0), 0);
for x in -2..2 {
for z in -2..2 {
let mut chunk = Chunk::empty(x, z);
let n = (x * 7 + z * 13).rem_euclid(17);
for i in 0..40 + n * 30 {
let (bx, bz) = ((i * 5 + n) % 16, (i * 11) % 16);
chunk.set(bx, MIN_Y + (i * 37 + n * 50) % 384, bz, 1 + (i % 3) as u32);
}
let mut light = Box::new([0u8; 4096]);
for (i, v) in light.iter_mut().enumerate() {
*v = (i * 31 + n as usize) as u8;
}
Arc::make_mut(&mut chunk.sections[(n % 24) as usize]).light = Light::Full(light);
world.block_entities.insert(
(x * 16 + 2, 70, z * 16 + 3),
BlockEntity::Sign(crate::signs::SignData::default()),
);
chunk.set(2, 70, 3, 3);
world.chunks.insert((x, z), Arc::new(chunk));
}
}
let mut keys: Vec<(i32, i32)> =
(-2..2).flat_map(|x| (-2..2).map(move |z| (x, z))).collect();
keys.push(keys[5]);
let chunks: Vec<&Chunk> = keys
.iter()
.map(|k| &**world.chunks.get(k).unwrap())
.collect();
let alone = ChunkEncoder::new(states.clone(), &builtin, &[], &[]);
let expected: Vec<Vec<u8>> = chunks.iter().map(|c| alone.body_in(c, &world)).collect();
let warmed = ChunkEncoder::new(states, &builtin, &[], &[]);
let bodies = |encoder: &ChunkEncoder| -> Vec<Vec<u8>> {
chunks.iter().map(|c| encoder.body_in(c, &world)).collect()
};
assert!(chunks.len() * SECTIONS >= WARM_MIN);
warmed.warm(&chunks);
assert_eq!(bodies(&warmed), expected);
// Again, from the cache, with nothing left to warm.
warmed.warm(&chunks);
assert_eq!(bodies(&warmed), expected);
warmed.warm(&[]);
}
#[test]
fn a_nether_column_sends_its_sixteen_sections_without_sky_light() {
let chunk = Chunk::empty(0, 0);
+124 -73
View File
@@ -12,6 +12,7 @@ use super::{
guest::{Guest, SentEffect, stack_to_network},
};
use crate::{
chunk::Chunk,
collisions::SceneCollisions,
effects::{EffectInstance, PlayerEffects},
items::ItemStack,
@@ -1027,11 +1028,7 @@ impl Hub {
ctx.world.light_log = Some(Default::default());
}
self.sync_world(ctx);
for i in 0..self.guests.len() {
if self.here(&self.guests[i]) {
self.update_chunks(i, ctx);
}
}
crate::spans::time("lan_chunks", || self.update_chunks(ctx));
self.broadcast_light_changes(ctx.world);
self.broadcast_block_changes(ctx.world);
// ServerGamePacketListenerImpl.tick: the actions handled since the last tick are
@@ -1170,86 +1167,140 @@ impl Hub {
// ---- chunks --------------------------------------------------------
fn update_chunks(&mut self, i: usize, ctx: &TickCtx) {
/// Every player's chunks here: their views, then the next batch of each
/// (PlayerChunkSender.sendNextChunks). The batches are chosen first, the
/// columns in them encoded once each, their new sections on the warm-up
/// threads too (`ChunkEncoder::warm`), then sent: nothing changes the
/// level in between, and each player's packets keep their order.
fn update_chunks(&mut self, ctx: &TickCtx) {
let world = &*ctx.world;
let mut batches = Vec::new();
for i in 0..self.guests.len() {
if self.here(&self.guests[i]) {
self.update_view(i);
if let Some(batch) = self.next_batch(i, world) {
batches.push((i, batch));
}
}
}
if batches.is_empty() {
return;
}
// Each column once, however many players it goes to, with the
// number of batches that take it.
let (mut columns, mut uses): (Vec<&Chunk>, Vec<usize>) = Default::default();
let mut index = crate::fast_hash::FxHashMap::default();
let batches: Vec<(usize, Vec<usize>, Vec<usize>)> = batches
.into_iter()
.map(|(i, batch)| {
let (taken, bodies) = batch
.into_iter()
.map(|(idx, chunk)| {
let j = *index.entry((chunk.x, chunk.z)).or_insert_with(|| {
columns.push(chunk);
uses.push(0);
columns.len() - 1
});
uses[j] += 1;
(idx, j)
})
.unzip();
(i, taken, bodies)
})
.collect();
self.encoder.warm(&columns);
let mut bodies: Vec<Vec<u8>> = columns
.iter()
.map(|c| self.encoder.body_in(c, world))
.collect();
for (i, taken, batch) in batches {
let g = &mut self.guests[i];
let size = batch.len();
g.batch_quota -= size as f32;
g.send(&C::ChunkBatchStart(horizon_protocol::packets::Empty));
g.sender.send_many(batch.into_iter().map(|j| {
uses[j] -= 1;
if uses[j] == 0 {
std::mem::take(&mut bodies[j])
} else {
bodies[j].clone()
}
}));
g.send(&C::ChunkBatchFinished(play::ChunkBatchFinished {
size: size as i32,
}));
g.unacknowledged += 1;
for idx in taken.into_iter().rev() {
let key = g.chunk_queue.remove(idx);
g.sent_chunks.insert(key);
}
}
}
/// ChunkMap.move's view change: the new centre, the chunks that left
/// the view forgotten and the ones that entered it queued, closest first.
fn update_view(&mut self, i: usize) {
let (cx, cz) = self.guests[i].chunk();
let r = self.guests[i].view_distance;
let g = &mut self.guests[i];
if g.center != Some((cx, cz)) {
g.center = Some((cx, cz));
if g.center_sent.take() != Some((cx, cz)) {
g.send(&C::SetChunkCacheCenter(play::SetChunkCacheCenter {
x: cx,
z: cz,
}));
}
// Chunks that left the view.
let forget: Vec<_> = g
.sent_chunks
.iter()
.copied()
.filter(|&(x, z)| !tracked(cx, cz, r, x, z))
.collect();
for (x, z) in forget {
g.sent_chunks.remove(&(x, z));
g.send(&C::ForgetLevelChunk(play::ForgetLevelChunk { pos: [x, z] }));
}
g.chunk_queue.retain(|&(x, z)| tracked(cx, cz, r, x, z));
for dz in -r - 2..=r + 2 {
for dx in -r - 2..=r + 2 {
let key = (cx + dx, cz + dz);
if tracked(cx, cz, r, key.0, key.1)
&& !g.sent_chunks.contains(&key)
&& !g.chunk_queue.contains(&key)
{
g.chunk_queue.push(key);
}
if g.center == Some((cx, cz)) {
return;
}
g.center = Some((cx, cz));
if g.center_sent.take() != Some((cx, cz)) {
g.send(&C::SetChunkCacheCenter(play::SetChunkCacheCenter {
x: cx,
z: cz,
}));
}
// Chunks that left the view.
let forget: Vec<_> = g
.sent_chunks
.iter()
.copied()
.filter(|&(x, z)| !tracked(cx, cz, r, x, z))
.collect();
for (x, z) in forget {
g.sent_chunks.remove(&(x, z));
g.send(&C::ForgetLevelChunk(play::ForgetLevelChunk { pos: [x, z] }));
}
g.chunk_queue.retain(|&(x, z)| tracked(cx, cz, r, x, z));
for dz in -r - 2..=r + 2 {
for dx in -r - 2..=r + 2 {
let key = (cx + dx, cz + dz);
if tracked(cx, cz, r, key.0, key.1)
&& !g.sent_chunks.contains(&key)
&& !g.chunk_queue.contains(&key)
{
g.chunk_queue.push(key);
}
}
g.chunk_queue
.sort_by_key(|&(x, z)| i64::from(x - cx).pow(2) + i64::from(z - cz).pow(2));
}
// PlayerChunkSender.sendNextChunks: ready chunks, closest first, in
// batches the client's acknowledgements pace.
g.chunk_queue
.sort_by_key(|&(x, z)| i64::from(x - cx).pow(2) + i64::from(z - cz).pow(2));
}
/// PlayerChunkSender.sendNextChunks' choice: ready chunks, closest first,
/// as many as the batch quota the client's acknowledgements pace allows,
/// with their places in the queue.
fn next_batch<'w>(&mut self, i: usize, world: &'w World) -> Option<Vec<(usize, &'w Chunk)>> {
let g = &mut self.guests[i];
if self.ticks <= g.placed_at + 1 || g.unacknowledged >= g.max_unacknowledged {
return;
return None;
}
g.batch_quota = (g.batch_quota + g.chunks_per_tick).min(g.chunks_per_tick.max(1.0));
if g.batch_quota < 1.0 || g.chunk_queue.is_empty() {
return;
return None;
}
let budget = g.batch_quota.floor() as usize;
let mut packets = Vec::new();
let mut taken = Vec::new();
for (idx, key) in g.chunk_queue.iter().enumerate() {
if packets.len() >= budget {
break;
}
let Some(chunk) = ctx.world.chunks.get(key) else {
continue;
};
if !chunk.lit {
continue;
}
packets.push(self.encoder.body_in(chunk, ctx.world));
taken.push(idx);
}
if packets.is_empty() {
return;
}
let size = packets.len();
g.batch_quota -= size as f32;
g.send(&C::ChunkBatchStart(horizon_protocol::packets::Empty));
for body in packets {
g.sender.send(body);
}
g.send(&C::ChunkBatchFinished(play::ChunkBatchFinished {
size: size as i32,
}));
g.unacknowledged += 1;
for idx in taken.into_iter().rev() {
let key = g.chunk_queue.remove(idx);
g.sent_chunks.insert(key);
}
let batch: Vec<_> = g
.chunk_queue
.iter()
.enumerate()
.filter_map(|(idx, key)| Some((idx, &**world.chunks.get(key).filter(|c| c.lit)?)))
.take(budget)
.collect();
(!batch.is_empty()).then_some(batch)
}
/// Resend a chunk to everyone who has it (a block entity changed, relight).