SimpleExample

English | Chinese

简单的维度创建（Xmake）

MoreDimensions 提供了基础的世界生成类型，这些api在src/more_dimensions/api/dimension/SimpleCustomDimension.h

这里面提供了一个简单的维度类，可以生成原版的Void,Flat,Overworld,Nether,TheEnd这几种类型的维度。

使用起来也非常简单，下面一步步开始怎么使用

本教程只涉及了基础的C++知识

准备阶段

确保你有以下环境

安装了C++桌面开发的msbuild(v143)或者MS Studio
一个你熟悉的文件编辑器，本教程使用vscode
Git（建议vscode里也安装对应插件）
xmake（vscode需要安装对应插件，同名直接搜）
clangd（vscode需要安装对应插件，同名直接搜）
一个已经安装了levilamina的BDS

本教程全程使用xmake构建项目

插件模板下载

首先clone插件模板，在你任意文件夹内，使用以下指令clone插件模板到本地

git clone --depth 1 https://github.com/LiteLDev/levilamina-plugin-template.git

上面指令执行成功后，你可以在执行了clone的目录看到levilamina-plugin-template文件夹

（可选）重命名levilamina-plugin-template为simple-dimensions，利于辨认

进入simple-dimensions文件夹

左键空白处，选择Open with Code，在vs code里面打开这个文件夹

插件加载依赖配置

由于本插件是依赖more-dimensions的，得配置插件的加载顺序，让我们写的插件加载比more-dimensions晚

在插件的根目录下，你会看到manifest.json这个文件，里面的初始内容大概如下：

{
    "name": "${pluginName}",
    "entry": "${pluginFile}",
    "type": "native"
}

在type的下一行加入以下内容

"dependencies": [
    {
        "name": "more-dimensions"
    }
]

变成这样

{
    "name": "${pluginName}",
    "entry": "${pluginFile}",
    "type": "native",
    "dependencies": [
        {
            "name": "more-dimensions"
        }
    ]
}

配置xmake

如果你的vs code还没有安装xmake插件，请先安装

在文件列表里点击xmake.lua这个文件来，打开文件内容后，在里面添加more-dimensions依赖

add_requires("more-dimensions 0.2.1") -- 使用v0.2.1版本

在写本教程时最新发布是v0.2.1，结合看本教程的时候最新版本更改

把

target("my-plugin")

改成

target("simple-dimensions")

在target分层下面添加

add_packages("more-dimensions")

然后使用以下指令初次构建与下载依赖，等待时间可能会很长，可以先执行以下指令，让其后台跑，继续跟教程走

xmake -y

创建维度

在Vscode内打开MyPlugin.cpp文件

导入头文件

#include "ll/api/event/server/ServerStartedEvent.h"
#include "more_dimensions/api/dimension/CustomDimensionManager.h"
#include "more_dimensions/api/dimension/SimpleCustomDimension.h"

在文件的最后一行加入以下内容

static bool reg = [] {
    using namespace ll::event;
    // 使用ll提供的开服事件触发创建维度，你也可以使用指令在游戏内执行触发创建维度
    EventBus::getInstance().emplaceListener<ServerStartedEvent>([](ServerStartedEvent&) {

        // 使用345作为地形种子生成Overworld类型的维度
        more_dimensions::CustomDimensionManager::getInstance().addDimension<more_dimensions::SimpleCustomDimension>(
            "newDimension", 345
        );

        // 使用345作为地形种子生成Flat类型的维度
        more_dimensions::CustomDimensionManager::getInstance()
            .addDimension<more_dimensions::SimpleCustomDimension>("newFlatDimension", 345, GeneratorType::Flat);

        // 使用345作为地形种子生成Nether类型的维度
        more_dimensions::CustomDimensionManager::getInstance()
            .addDimension<more_dimensions::SimpleCustomDimension>("newNetherDimension", 345, GeneratorType::Nether);

        // 使用345作为地形种子生成TheEnd类型的维度
        more_dimensions::CustomDimensionManager::getInstance()
            .addDimension<more_dimensions::SimpleCustomDimension>("newTheEndDimension", 345, GeneratorType::TheEnd);

        // 使用345作为地形种子生成Void类型的维度，这里种子设置会是无效的，种子只对地形生效
        more_dimensions::CustomDimensionManager::getInstance()
            .addDimension<more_dimensions::SimpleCustomDimension>("newVoidDimension", 345, GeneratorType::Void);
    });
    return true;
}();

这个简单维度类注册接受三个参数，这个三个参数来自两个不同的函数组成，第一个name是SimpleCustomDimension构造函数的第一个参数，第二第三个参数是来自SimpleCustomDimension::generateNewData函数

这些查看CustomDimensionManager::addDimension(std::string const& dimName, Args&&... args)的实现即可明白

构建与使用

写好上面后，就已经完成创建新维度的步骤，现在我们可以放到有levilamina的BDS中体验

执行以下指令构建插件

xmake

如无意外在插件根目录下会有个bin文件夹，里面会有个simple-dimensions文件夹，这就是已经打包好的插件

直接复制simple-dimensions这个文件夹，放到BDS目录/plugins文件夹内，同时，也记得把more-dimensions也放进去

接下来启动BDS即可，关于ll的安装请看这里levilamina安装

启动BDS后，如果创建维度成功，会在存档目录里生成一个记录维度信息的json文件：

此文件不要更改，手动修改极有可能损失存档数据

进入游戏后，你可以直接使用tp指令传送到自定义的维度，在tp指令里的维度参数会有对应的参数补全，这里拿其中一个示例

tp ~ 100 ~ new_dimension

不出意外，你可以成功传送到对应的维度。

种子说明

在SimpleCustomeDimension的构建维度中传入了seed参数，但这个只对维度的地形生效，在后续教程中也有体现。

那么为什么不能对维度中的结构生效呢？因为结构生成时是用服务器配置文件server.properties或者存档创建时随机生成的种子判断生成的。

本教程示例文件

本教程过于简单，故不提供示例文件

Simple Dimension Creation (Xmake)

MoreDimensions provides basic world generation types, and these APIs can be found in src/more_dimensions/api/dimension/SimpleCustomDimension.h.

It offers a simple dimension class that can generate vanilla dimensions such as Void, Flat, Overworld, Nether, and TheEnd.

Using it is straightforward. Below are the steps to get started.

This tutorial only covers basic C++ knowledge.

Preparation

Ensure you have the following environment:

Installed msbuild(v143) or MS Studio for C++ desktop development.
A text editor you are familiar with; this tutorial uses vscode.
Git (it's recommended to install the corresponding plugin in vscode as well).
xmake (install the corresponding plugin in vscode, search for the same name).
clangd (install the corresponding plugin in vscode, search for the same name).
A BDS with levilamina installed.

This tutorial uses xmake to build the project.

Plugin Template Download

First, clone the plugin template. In any folder of your choice, use the following command to clone the plugin template locally:

git clone --depth 1 https://github.com/LiteLDev/levilamina-plugin-template.git

After successfully executing the command, you should see the levilamina-plugin-template folder in the directory where you executed the clone command.

(Optional) Rename levilamina-plugin-template to simple-dimensions for easier identification.

Enter the simple-dimensions folder.

Right-click on the blank space and select Open with Code to open this folder in vscode.

Plugin Load Dependency Configuration

Since this plugin depends on more-dimensions, we need to configure the plugin's load order so that the plugin we write loads after more-dimensions.

In the root directory of the plugin, you will see a file named manifest.json with initial content that looks something like this:

{
    "name": "${pluginName}",
    "entry": "${pluginFile}",
    "type": "native"
}

Add the following content after type:

"dependencies": [
    {
        "name": "more-dimensions"
    }
]

So it becomes:

{
    "name": "${pluginName}",
    "entry": "${pluginFile}",
    "type": "native",
    "dependencies": [
        {
            "name": "more-dimensions"
        }
    ]
}

Configuring xmake

If you haven't installed the xmake plugin in vscode yet, please do so first.

Click on the xmake.lua file in the file list. After opening the file, add the more-dimensions dependency:

add_requires("more-dimensions 0.2.1") -- Using version v0.2.1

At the time of writing this tutorial, the latest release is v0.2.1, adjust according to the latest version when following this tutorial.

Change:

target("my-plugin")

to:

target("simple-dimensions")

Under the target section, add:

add_packages("more-dimensions")

Then use the following command to initially build and download dependencies. The waiting time may be long, so you can let it run in the background while continuing with the tutorial:

xmake -y

Creating a Dimension

Open the MyPlugin.cpp file in Vscode.

Import the header files:

#include "ll/api/event/server/ServerStartedEvent.h"
#include "more_dimensions/api/dimension/CustomDimensionManager.h"
#include "more_dimensions/api/dimension/SimpleCustomDimension.h"

Add the following content at the end of the file:

static bool reg = [] {
    using namespace ll::event;
    // Use the server start event provided by ll to trigger dimension creation. You can also use commands in the game to trigger dimension creation.
    EventBus::getInstance().emplaceListener<ServerStartedEvent>([](ServerStartedEvent&) {

        // Use 345 as the terrain seed to generate an Overworld type dimension
        more_dimensions::CustomDimensionManager::getInstance().addDimension<more_dimensions::SimpleCustomDimension>(
            "newDimension", 345
        );

        // Use 345 as the terrain seed to generate a Flat type dimension
        more_dimensions::CustomDimensionManager::getInstance()
            .addDimension<more_dimensions::SimpleCustomDimension>("newFlatDimension", 345, GeneratorType::Flat);

        // Use 345 as the terrain seed to generate a Nether type dimension
        more_dimensions::CustomDimensionManager::getInstance()
            .addDimension<more_dimensions::SimpleCustomDimension>("newNetherDimension", 345, GeneratorType::Nether);

        // Use 345 as the terrain seed to generate a TheEnd type dimension
        more_dimensions::CustomDimensionManager::getInstance()
            .addDimension<more_dimensions::SimpleCustomDimension>("newTheEndDimension", 345, GeneratorType::TheEnd);

        // Use 345 as the terrain seed to generate a Void type dimension. The seed setting here will be invalid as the seed only affects terrain.
        more_dimensions::CustomDimensionManager::getInstance()
            .addDimension<more_dimensions::SimpleCustomDimension>("newVoidDimension", 345, GeneratorType::Void);
    });
    return true;
}();

The simple dimension class registration accepts three parameters. These three parameters come from two different functions. The first name is the first parameter of the SimpleCustomDimension constructor, and the second and third parameters come from the SimpleCustomDimension::generateNewData function.

You can understand this by looking at the implementation of CustomDimensionManager::addDimension(std::string const& dimName, Args&&... args).

Building and Using

After writing the above, you have completed the steps to create a new dimension. Now we can place it into a BDS with levilamina and experience it.

Execute the following command to build the plugin:

xmake

If successful, there will be a bin folder in the root directory of the plugin, containing a simple-dimensions folder, which is the packaged plugin.

Simply copy the simple-dimensions folder and place it into the BDS directory/plugins folder. Also, remember to put more-dimensions inside as well.

Next, start the BDS. For more details on ll installation, please refer to levilamina installation.

After starting the BDS, if the dimension is successfully created, a JSON file recording dimension information will be generated in the save directory:

Do not modify this file manually, as it might cause data loss in the save.

Once in the game, you can use the tp command to teleport to the custom dimension. The dimension parameter in the tp command will have corresponding parameter completions. Here is an example:

tp ~ 100 ~ new_dimension

If everything goes well, you should be able to teleport to the corresponding dimension successfully.

Seed Explanation

In the construction of the SimpleCustomDimension, a seed parameter is passed in, but this only affects the dimension's terrain, as will be demonstrated in subsequent tutorials.

Why does it not affect the structures in the dimension? Because structure generation is determined by the seed in the server configuration file server.properties or the seed randomly generated when the save was created.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly