Distant Decorations

模组

· 作者 awkwardusername

Distant Decorations 是一个高性能的 Fabric 框架,允许参与的模组在远超原版区块距离的地方持久化并渲染装饰性方块实体的视觉效果。

0 本站下载 0 关注 更新于 1 个月前

需要前置:Fabric API

最新 2.0.0 · 26.3 · Fabric

一键开服(送7天)

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 global 0.10 px, configurable down to 0.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 px visual footprint (e.g. clamped up to 16x without altering physical world AABBs.
  • Flicker-Free Live Handoff:
    • Dynamic distance threshold (64 x entityDistanceScaling blocks) 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.
  • 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 ByteBuf allocation in the render loop.

? 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), and Culled (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) 许可证。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源