Distant Decorations
Distant Decorations 是一个高性能的 Fabric 框架,适用于 Minecraft 26.2,允许参与的模组在远超原版区块距离的范围内持久化并渲染装饰性方块实体(block-entity)视觉效果。其默认客户端订阅范围为 512 个区块(8,192 个方块),服务端权威最大值为 1,024 个区块(16,384 个方块)。Fast Paintings 和 Camerapture 等集成提供了各自的轻量级服务端元数据提供程序和远程客户端渲染器。
通过将视觉表现与方块实体的 ticking 过程解耦,并利用分层空间索引、投影大小裁剪和有界 Top-K 选择,即使面对大型同步数据集,Distant Decorations 也能将远距离装饰遍历保持在毫秒级低延迟——并能无缝地与 Voxy 等长距离地形渲染器共存。
? Key Features
- Extreme Visibility Range: Extends decoration visibility up to 512 chunks (8,192 blocks) by default, with server support for subscriptions up to 1,024 chunks (16,384 blocks), independent of vanilla chunk render distance.
- Hierarchical Spatial Indexing:
- 4×4 Chunk Cells (64×64 blocks): Aggregate bounding box calculation for instantaneous coarse frustum culling.
- 32×32 Chunk Regions (512×512 blocks): Monotonic revision tracking, dirty-region flushing (every 5s), and idle eviction (60s).
- Dynamic Level of Detail (LOD) & Far-Visual Scaling:
- Provider-Aware Projected-Size Culling: Allows renderers to specify custom subpixel culling thresholds via
cullBelowProjectedPixelSize()(defaults to global0.10 px, configurable down to0.01 px). - Far-LOD Footprint Support: Core delivers precise projection metrics and non-culled submissions so provider renderers can scale subpixel distant quads around their center to maintain a rasterizable
~1 pxvisual footprint (e.g. clamped up to16xwithout altering physical world AABBs.
- Provider-Aware Projected-Size Culling: Allows renderers to specify custom subpixel culling thresholds via
- Flicker-Free Live Handoff:
- Dynamic distance threshold (
64 x entityDistanceScalingblocks) and a 200 ms chunk-load grace period ensuring seamless transitions between live block entity renderers and Distant Decorations. - Real-time mutation capture (
MixinBlockEntity) tracking block entity updates (setChanged) and removals in active chunks.
- Dynamic distance threshold (
- OBE Coexistence: Designed to cleanly coexist with OptimisedBlockEntities (OBE) by operating completely independently of ticking block entity lifecycles.
- Chunky Integration: Safely intercepts asynchronous chunk generation from Chunky and marshals reconciliation back onto the server main thread to atomically commit newly generated block entities to the world index.
- GPU & Network Throttling:
- Distance & screen-space prioritized budget limiter (
projectedPixelSize * 1000 - distance) using bounded top-K selection (O(N log K)). - Bandwidth-throttled (128 KiB/tick) chunked multipart snapshot packet streaming (nearest-first) with atomic client-side assembly.
- Ingestion-time payload pre-decoding: zero payload deserialization or
ByteBufallocation in the render loop.
- Distance & screen-space prioritized budget limiter (
? Provider Architecture
Distant Decorations is designed as a modular core framework. Content mods register their own lightweight metadata providers on the server and custom renderers on the client:
| Mod | Integration Architecture |
|---|---|
| Really Fast Paintings | Registers a painting provider and renderer leveraging vanilla atlas sprites with single-quad FAR LOD and far-LOD visual footprint scaling. |
⚙️ Configuration & Diagnostics
Distant Decorations provides runtime diagnostics commands and system property configuration:
Diagnostic Commands
- Client:
/ddc stats: Displays active configuration, synced region/decoration counts, and last-frame breakdown (Visible/Rendered,Far-LOD Scaled,Suppressed (Live),Culled (Distance),Culled (Subpixel),Culled (Frustum), andCulled (Budget))./ddc toggle: Toggles distant decoration rendering on or off at runtime.
- Server:
/dd stats: Displays indexed decoration counts, loaded dimensions, active client subscriptions, and dirty region tracking./dd toggle: Master server toggle for decoration synchronization.
Configuration Properties
| JVM Property | Default | Description |
|---|---|---|
distantdecorations.subscription_radius_chunks |
512 |
Client subscription radius in chunks (decoupled from vanilla render distance). |
distantdecorations.min_projected_pixel_size |
0.10 |
Global subpixel culling threshold in screen pixels (floored at 0.01). |
distantdecorations.max_render_distance |
radius * 16.0 |
Absolute max rendering distance in blocks (defaults to 8192.0 at 512 chunks). |
distantdecorations.disabled |
false |
Master kill-switch to disable DD processing. |
distantdecorations.provider.<namespace>.<path>.disabled |
false |
Disables a specific decoration provider/renderer by identifier. |
distantdecorations.provider.<namespace>.disabled |
false |
Disables all decoration providers from a given namespace. |
?️ Developer API
Distant Decorations provides a clean, extensible API allowing third-party mods to register custom decoration types, server providers, and client renderers.
1. Define a Decoration Type & Provider (Server-Side)
public record MyCustomData(Identifier texture, Direction facing, int width, int height, int packedLight) {}
```java
public class MyCustomProvider implements DecorationProvider<MyCustomData> {
public static final DecorationType<MyCustomData> TYPE = new DecorationType<>(
Identifier.fromNamespaceAndPath("mymod", "custom_deco"),
(data, buf) -> {
buf.writeIdentifier(data.texture());
buf.writeByte(data.facing().get2DDataValue());
buf.writeVarInt(data.width());
buf.writeVarInt(data.height());
buf.writeInt(data.packedLight());
},
buf -> new MyCustomData(
buf.readIdentifier(),
Direction.from2DDataValue(buf.readByte()),
buf.readVarInt(),
buf.readVarInt(),
buf.readInt()
)
);
@Override
public DecorationType<MyCustomData> type() { return TYPE; }
@Override
public boolean matches(BlockEntity be) { return be instanceof MyCustomBlockEntity; }
@Override
public MyCustomData capture(ServerLevel level, BlockPos pos, BlockEntity be) {
MyCustomBlockEntity custom = (MyCustomBlockEntity) be;
return new MyCustomData(custom.getTexture(), custom.getFacing(), custom.getWidth(), custom.getHeight(), getPackedLight(level, pos));
}
@Override
public AABB calculateBounds(ServerLevel level, BlockPos pos, MyCustomData data) {
return new AABB(pos);
}
}
2. 实现客户端渲染器(客户端)
public class MyCustomRenderer implements DecorationClientRenderer<MyCustomData> {
@Override
public DecorationType<MyCustomData> type() { return MyCustomProvider.TYPE; }
@Override
public double cullBelowProjectedPixelSize() {
// 启用自定义子像素阈值以进行远距离 LOD 缩放
return 0.01;
}
@Override
public void render(
DecorationRecord record,
MyCustomData data,
Camera camera,
PoseStack poseStack,
SubmitNodeCollector submitNodeCollector,
ProjectionMetrics metrics,
double projectedPixelSize
) {
BlockPos anchor = record.pos();
Vec3 camPos = camera.position();
poseStack.pushPose();
poseStack.translate(anchor.getX() - camPos.x, anchor.getY() - camPos.y, anchor.getZ() - camPos.z);
poseStack.translate(0.5, 0.5, 0.5);
// 可选:用于子像素四边形的远距离 LOD 视觉缩放
double targetMinPixelSize = 1.0;
if (projectedPixelSize > 0 && projectedPixelSize < targetMinPixelSize) {
double visualScale = Math.min(16.0, targetMinPixelSize / projectedPixelSize);
poseStack.scale((float) visualScale, (float) visualScale, 1.0F);
TelemetryMetrics.clientFarLodScaledRenders++;
}
RenderType renderType = RenderTypes.entityCutout(data.texture());
submitNodeCollector.submitCustomGeometry(poseStack, renderType, (pose, buffer) -> {
// 提交顶点几何数据
});
poseStack.popPose();
}
}
3. 注册
// 通用/服务端模组初始化器
DecorationRegistry.registerProvider(new MyCustomProvider());
// 客户端模组初始化器
ClientDecorationRegistry.registerRenderer(new MyCustomRenderer());
? 从源代码构建与测试
git clone https://github.com/justbecauseph/distant-decorations.git
cd distant-decorations
./gradlew build
要运行包含 Voxy、Sodium 和 Spark 的完整客户端测试环境,请执行:
./gradlew runIntegrationClient
编译后的模组 JAR 文件位于 build/libs/ 目录下。
? 许可证
Distant Decorations 遵循 Mozilla Public License 2.0 (MPL-2.0) 许可证。
你是这个资源的作者?登录后可认领此资源。
相似资源
缓冲的原始输入和线程化的事件轮询
一个用于收集生物掉落物的多区块模组。
显示你正在注视的方块的信息。(适用于 Minecraft 1.16+ 的 Hwyla/Waila 分支)
原版世界生成优化模组
使用 JavaScript 编辑配方、添加自定义物品、编写世界事件!
查看物品与配方
评论 0
登录后参与评分
还没有评论,来抢沙发吧