Skip to content

API Reference(中文)

Jump to bottom
Qiuzhizhe edited this page Aug 9, 2024 · 2 revisions

English

API List

API

CustomDimensionManager.h(more_dimensions::CustomDimensionManager)

创建维度相关的API

addDimension

template <std::derived_from<Dimension> D, class... Args>
DimensionType addDimension(std::string const& dimName, Args&&... args)

添加一个维度，维度名为dimName，如果成功会返回此维度的DimensionType，失败返回一个id为-1的DimensionType

调用此函数，在维度类中必须存在一个叫generateNewData并且返回类型为CompoundTag的静态函数，generateNewData的作用是为你自定义的维度类传输初始化时需要的参数。

比如MoreDimensions提供的简单维度类SimpleCustomDimension需要知道生成维度的类型与种子，我们就通过generateNewData来传递。

我们这样包装的初衷是不暴露维度的ID，避免开发者自定义ID造成ID出现混乱与冲突，让维度的ID完全由CustomDimensionManager来管理。开发者只需提供维度名，不必去考虑ID的冲突

args的参数则是依据维度类中的generateNewData来定

例如MoreDimensions中的SimpleCustomDimension::generateNewData接受一个uint的seed参数和一个GeneratorType的生成类型参数，那么这里这么调用：

more_dimensions::CustomDimensionManager::getInstance()
    .addDimension<more_dimensions::SimpleCustomDimension>("Dimensin Name", 12345678, GeneratorType::Flat);

getDimensionIdFromName(Deprecated)

static DimensionType getDimensionIdFromName(std::string const& dimName);

注意，我们不建议使用此API，建议直接使用VanillaDimensions::fromString获取

获取维度ID，使用维度名dimName获取对应的DimensionType。

SimpleCustomDimension.h(more_dimensions::SimpleCustomDimension)

一个由MoreDimensions提供的简单维度类，可以创建原版的Void，Flat，Overworld，Nether，TheEnd这五种类型的维度

这也是一个示例维度类，以下主要是说明这些函数的作用，以便开发者参考

generateNewData

static CompoundTag generateNewData('自定义的参数');

这是一个必须提供的静态函数，其接受的参数由开发者自定义，作用是传输一些在初始化维度时需要用到的参数。

这个函数只是把这些自定义参数打包成了CompoundTag，这个CompoundTag会最后传给维度类的实例化函数。

SimpleCustomDimension

SimpleCustomDimension(std::string const& name, DimensionFactoryInfo const& info);

维度类的实例化函数，其接受的参数固定，如果需要传输更多实例化时需要的参数，需在generateNewData中自定义。

此函数的实现必须调用父类函数Dimension的实例化函数，参考本示例类的写法：

SimpleCustomDimension::SimpleCustomDimension(std::string const& name, DimensionFactoryInfo const& info)
: Dimension(info.level, info.dimId, {-64, 320}, info.scheduler, name) {
...code...
}

这里说明一下Dimension实例化函数接受的参数：

Dimension(
    info.level,     /*这是Level的基类指针ILevel*/
    info.dimId,     /*维度id，不要更改*/
    {-64, 320},     /*维度高度，这样设置即可*/
    info.scheduler, /*不知道什么作用，也用不上，忽略*/
    name            /*维度名称*/
    )

这个实例化函数中，参数info里面包含了调用父类实例化函数所需的剩余参数，其中generateNewData自定义的参数在info.data：

SimpleCustomDimension::SimpleCustomDimension(std::string const& name, DimensionFactoryInfo const& info)
: Dimension(info.level, info.dimId, {-64, 320}, info.scheduler, name) {
    loggerMoreDim.debug("{} dimension name:{}", __FUNCTION__, name);
    mDefaultBrightness.sky = Brightness::MAX;
    generatorType          = *magic_enum::enum_cast<GeneratorType>((std::string_view)info.data["generatorType"]);
    seed                   = info.data["seed"];
...code...
}

实例化函数内，最小程度初始化的成员变量有：mDefaultBrightness，mSeaLevel，mHasWeather，mDimensionBrightnessRamp

如果你有自定义的变量，最好也初始化它们

SimpleCustomDimension::SimpleCustomDimension(std::string const& name, DimensionFactoryInfo const& info)
: Dimension(info.level, info.dimId, {-64, 320}, info.scheduler, name) {
    loggerMoreDim.debug("{} dimension name:{}", __FUNCTION__, name);
    mDefaultBrightness.sky = Brightness::MAX;
    generatorType          = *magic_enum::enum_cast<GeneratorType>((std::string_view)info.data["generatorType"]);
    seed                   = info.data["seed"];
    switch (generatorType) {
    case GeneratorType::TheEnd: {
        mSeaLevel                = 63;
        mHasWeather              = false;
        mDimensionBrightnessRamp = std::make_unique<OverworldBrightnessRamp>();
    }
    case GeneratorType::Nether: {
        mSeaLevel                = 32;
        mHasWeather              = false;
        mDimensionBrightnessRamp = std::make_unique<NetherBrightnessRamp>();
    }
    default:
        mSeaLevel                = 63;
        mHasWeather              = true;
        mDimensionBrightnessRamp = std::make_unique<OverworldBrightnessRamp>();
    }
    mDimensionBrightnessRamp->buildBrightnessRamp();
}

查看示例代码你会发现，最后后调用了buildBrightnessRamp()，这也是必须的

对于mDimensionBrightnessRamp的赋值，如果你不知道有什么用或者用不上，使用OverworldBrightnessRamp构建一个即可

init

void init(br::worldgen::StructureSetRegistry const& structureSetRegistry)

这是一个覆写函数

维度初始化时会调用，必须调用父类Dimension的init函数。

除了有特别需要之外，直接调用父类的init函数即可：

void SimpleCustomDimension::init(br::worldgen::StructureSetRegistry const& structureSetRegistry) {
    setSkylight(false);
    Dimension::init(structureSetRegistry);
}

createGenerator

std::unique_ptr<WorldGenerator> createGenerator(br::worldgen::StructureSetRegistry const&)

这是一个覆写函数

创建一个这个维度地形结构生成的WorldGenerator对象

如果你需要自定义维度的地形，从这个WorldGenerator入手即可，本示例代码则是根据选择的地形类型，选择原版不同的地形生成器

其详细说明可以查看Wiki的示例插件FlatGeneratedVillages的WorldGenerator部分

另有以Flat世界类型的地皮系统地形generator-terrain

本示例类展示了如何去创建一个BDS可用的WorldGenerator对象，内容较长，请查看源码

upgradeLevelChunk

这是一个覆写函数

void upgradeLevelChunk(ChunkSource& chunkSource, LevelChunk& oldLc, LevelChunk& newLc)

对旧区块的更新

此函数主要针对旧版本区块的更新，例如1.18时的洞穴更新，对旧区块y0附近基岩进行替换，y0以下高度的空间填充

如果没有特别需要，按照本示例类写即可：

void SimpleCustomDimension::upgradeLevelChunk(ChunkSource& cs, LevelChunk& lc, LevelChunk& generatedChunk) {
    auto blockSource = BlockSource(getLevel(), *this, cs, false, true, false);
    VanillaLevelChunkUpgrade::_upgradeLevelChunkViaMetaData(lc, generatedChunk, blockSource);
    VanillaLevelChunkUpgrade::_upgradeLevelChunkLegacy(lc, blockSource);
}

fixWallChunk

这是一个覆写函数

目前尚未研究其作用

levelChunkNeedsUpgrade

这是一个覆写函数

目前尚未研究其作用

_upgradeOldLimboEntity

这是一个覆写函数

目前尚未研究其作用

translatePosAcrossDimension

这是一个覆写函数

不同维度之间坐标的转换

在原版中，Nether的坐标是Overworld坐标的八倍，就是由此函数进行转换

_wrapStorageForVersionCompatibility

这是一个覆写函数

目前尚未研究其作用

getBrightnessDependentFogColor

这是一个覆写函数

目前尚未研究其作用

getCloudHeight

这是一个覆写函数

获取云的高度，在BDS中的作用未知

hasPrecipitationFog

这是一个覆写函数

目前尚未研究其作用

Home

Getting Start

Example

Clone this wiki locally