制图渲染器（Cartography Renderers）

基本信息

属性 值
包路径 journeymap.client.cartography.render
渲染器总数 5 个具体实现 + 1 个抽象基类
抽象基类 BaseRenderer（render/BaseRenderer.java:36）
统一接口 journeymap.client.cartography.IChunkRenderer（IChunkRenderer.java:10）
着色工具 ColorManager / ColorPalette / PixelPaint / RGB
分层工具 Strata / Stratum（洞穴逐层下挖用）

功能

JourneyMap 的地图不是贴图拼接，而是逐区块重新绘制：读取区块的方块列信息，按材质/生物群系/光照算出每个像素的颜色，再写进缓存的 RegionImageSet。这一层就是"制图渲染器"。

5 个渲染器与继承链

IChunkRenderer (interface)
  └─ BaseRenderer (abstract, implements RemovalListener<ChunkCoordIntPair, ChunkMD>)
       ├─ SurfaceRenderer
       │    └─ EndRenderer
       └─ CaveRenderer
            └─ NetherRenderer
  TopoRenderer (独立, extends BaseRenderer)
渲染器 文件 继承 对应地图类型
SurfaceRenderer render/SurfaceRenderer.java:19 BaseRenderer day / night / surface
CaveRenderer render/CaveRenderer.java:22 BaseRenderer underground
NetherRenderer render/NetherRenderer.java:21 CaveRenderer 下界地图（复用洞穴逻辑）
EndRenderer render/EndRenderer.java:21 SurfaceRenderer 末地地图（复用地表逻辑）
TopoRenderer render/TopoRenderer.java:28 BaseRenderer topo

两个下层渲染器直接继承上层而非 BaseRenderer，是为了复用其区块遍历与着色逻辑再覆写差异部分。CaveRenderer 的构造器额外接收一个 SurfaceRenderer 实例（CaveRenderer.java:38）——洞穴图需要叠加地表层时使用。

IChunkRenderer 的 3 个方法

方法 签名 语义
render boolean render(ChunkPainter, ChunkMD chunkStub, Integer vSlice) 渲染一个区块，返回是否有产出（IChunkRenderer.java:12）
setStratumColors void setStratumColors(Stratum, int lightAttenuation, Integer waterColor, boolean waterAbove, boolean underground, boolean mapCaveLighting) 为某一地层设置颜色（:14）
getAmbientColor int getAmbientColor() 环境光基色（:16）

BaseRenderer 还实现 RemovalListener<ChunkCoordIntPair, ChunkMD>，在区块从缓存移除时做清理。

BaseRenderer 持有的配置

BaseRenderer 把 7 个 CoreProperties 制图开关缓存为字段（BaseRenderer.java:48-55），渲染时直接读字段而非反复查配置对象：

字段 对应配置项 默认
mapBathymetry jm.common.map_style_bathymetry false
mapTransparency jm.common.map_style_transparency true
mapCaveLighting jm.common.map_style_cavelighting true
mapAntialiasing jm.common.map_style_antialiasing true
mapCrops jm.common.map_style_crops true
mapPlants jm.common.map_style_plants false
mapPlantShadows jm.common.map_style_plantshadows false

地形着色（山体阴影）

BaseRenderer 用一组坡度乘数做山体阴影（BaseRenderer.java:23-32）：

  • primarySlopeOffsets（初始容量 3）与 secondarySlopeOffsets（初始容量 4）——对相邻像素做偏移采样比较高度差
  • 6 个浮点乘数：shadingSlopeMin、shadingSlopeMax、shadingPrimaryDownslopeMultiplier、shadingPrimaryUpslopeMultiplier、shadingSecondaryDownslopeMultiplier 等；注释给出范围约束（下坡 0-1、上坡 1-?）
  • shadingPrimaryUpslopeMultiplier 初值 1.20f（:90）

颜色常量

常量 值 用途 源码
COLOR_BLACK Color.black.getRGB() 纯黑 :42
COLOR_VOID RGB.toInteger(17, 12, 25) 虚空/未加载区（深紫黑） :43
DEFAULT_FOG RGB.toInteger(0, 0, .1f) 默认雾色 :44
ALPHA_OPAQUE AlphaComposite.SRC_OVER, 1F 不透明合成 :41

DEFAULT_FOG 的第三个分量为 .1f（蓝色分量），与前两个 0 不同——是刻意的淡蓝雾色。

Strata / Stratum：洞穴逐层

洞穴图不能用"取最上面的非空气方块"这种方式渲染（那只会画到地表），而是自上而下逐层剥离：

  • Strata（cartography/Strata.java:19）是一个对象池：Strata(String name, int initialPoolSize, int poolGrowthIncrement, boolean underground)（:40）
  • push(ChunkMD, BlockMD, int, int, int) / push(..., Integer lightLevel)（:106、:111）把区块中的方块按 Y 压入地层
  • nextUp(IChunkRenderer, boolean ignoreMiddleWater)（:150）取当前层之上的一层
  • release(Stratum)（:92）归还对象池
  • isEmpty()（:184）、isMapCaveLighting()（:221）、isUnderground()（:226）、getTopY()（:231）
  • Stratum（cartography/Stratum.java:18）表示单个地层，持有 ChunkMD、BlockMD、x、y、z 及各自 getter/setter（:137-172）

数值

数值名 值
具体渲染器数 5
抽象基类数 1（BaseRenderer）
接口方法数 3
BaseRenderer 缓存的配置开关数 7
颜色常量数 3（COLOR_BLACK、COLOR_VOID、DEFAULT_FOG）
山体阴影偏移采样器 2 组（primary 容量 3 / secondary 容量 4）
shadingPrimaryUpslopeMultiplier 初值 1.20f

交互

触发 行为
制图任务处理区块 按 MapType 选择渲染器，逐区块写像素到 RegionImageSet
区块离开缓存 BaseRenderer 作为 RemovalListener 收到回调并清理
修改制图开关 需重开世界或触发重绘；BaseRenderer 在构造时读取一次配置
玩家在地下 underground 类型经 Strata 逐层下挖绘制
mapTransparency 开启 半透明方块按 ALPHA_OPAQUE 之外的合成方式叠加

相关条目