RTStrucures Framework

RTStrucures Framework

一个专注于RTS建筑机制的库

基础库

该模组为 RTS 多方块结构提供功能支持,也可用作结构的复制/粘贴工具。

游戏内功能

  • 保存结构
  • 粘贴结构

要保存结构,你需要结构工具——使用 /give 或操作员选项卡获取;

右键点击 —— 设置位置 1;

左键点击 —— 设置位置 2;

Shift + 右键点击 —— 设置锚点位置

CTRL + 鼠标点击 —— 扩展区域(可在按键绑定中更改)

Shift + 左键点击 —— 设置放置锚点


/rtstrucutres save —— 保存结构

/rtstrucutres load —— 预加载结构 + 显示粘贴框

/rtstrucutres execute <build_type> —— 将预加载的结构粘贴到世界中

/rtstrucutres execload <build_type> —— 将结构粘贴到世界中

/rtstrucutres toggle_boxes <true/false> —— 始终显示工具选择区域


模组开发者功能

安装指南

repositories {
    maven {
        url = "https://api.modrinth.com/maven"
    }
}

dependencies {
    implementation "maven.modrinth:rtstrucures-framework:0.1.4"
}

模组指南

以下是 /execload 命令的示例

ServerLevel level = ctx.getSource().getLevel();
String filename = "house";

Path worldDir = level.getServer().getWorldPath(LevelResource.ROOT);
StructureTemplate template = StructureCache.get(worldDir, filename);

BlockPos anchorPos = StructureToolState.placeAnchor; // 放置位置
PlacementAnchor anchorMode = PlacementAnchor.CUSTOM; // 建议使用自定义锚点
StructureInstance instance = new StructureInstance(level, template, anchorPos, anchorMode);

StructureManager.add(instance);
instance.build(BuildType.FAST, 2.0f); // 在世界中执行;逐层建造

StructureInstance 类提供了更多用于结构管理的方法;


基本用法

保存结构

StructureTemplate template = StructureCapture.capture(level, pos1, pos2, customAnchor);
Path path = worldDir.resolve("generated/rtstructures/house.rtstructure");

StructureSerializer.save(template, path);

加载结构

Path path = worldDir.resolve("generated/rtstructures/house.rtstructure");

StructureTemplate template = StructureDeserializer.load(path);

注册结构

StructureManager.add(instance);

开始建造

instance.build(BuildType.FAST,10);
  • BuildType = 建造逻辑
  • speed = 每 tick 方块数

验证系统

检查损坏

boolean damaged = instance.isDamaged();

完成百分比

float percent = instance.getCompletionPercent();

损坏百分比

float percent = instance.getDamagePercent();

完整验证结果

ValidationResult result = instance.validate();

建造模式

警告!如果结构无法完成建造,它将无限 tick。请注意这一点(最大步数数量将在下个版本中添加)

FAST

即时分层建造

  • 快速
  • 无限制
  • 替换方块

最适合:

  • 调试
  • 电影化建造
  • RTS 即时建造

FAST_SAFE

分层建造且不替换现有方块

  • 保护世界
  • 更安全的放置
  • 完成较慢

最适合:

  • 生存玩法
  • 受保护的世界

CONNECT

仅建造相连的方块

  • 真实传播
  • 依赖支撑
  • 如果不相连可能会停滞

最适合:

  • RTS 模拟
  • 有机建造系统

SEPARATED

从锚点开始的生长式建造

  • 扩散建造效果
  • 定向扩展
  • 有机外观

最适合:

  • 异形结构
  • 植物状建造
  • 视觉效果

SEPARATED_DIAGONAL

与 SEPARATED 相同,但角方块也用作锚点

DEMOLISH

从上到下拆除结构


高级用法(0.1.4+)

注册结构

模组提供 DefferedRegistered 结构

public final class StructuresInit {
    private StructuresInit() {}

    public static final DeferredRegister<StructureType> STRUCTURES =
            DeferredRegister.create(RTSRegistries.STRUCTURES, RTStructureFramework.MOD_ID);

public static final Supplier<StructureType> SIMPLE_HOUSE = STRUCTURES.register("simple_house", SimpleHouseStructure::new);
    public static final Supplier<StructureType> AIRFIELD = STRUCTURES.register("airfield", AirfieldStructure::new);
    public static final Supplier<StructureType> CRYSTAL = STRUCTURES.register("crystal", CrystalStructure::new);
    public static final Supplier<StructureType> PROTECTED_STRUCTURE = STRUCTURES.register("protected_structure", ProtectedStructure::new);

public static void register(IEventBus bus) {
        STRUCTURES.register(bus);
    }
}

结构类

public class SimpleHouseStructure extends StructureType {

    public SimpleHouseStructure() {
        super("simple_house", StructureProperties.create()
                // 结构文件
                .modPath("basic/simple_house", RTStructureFramework.MOD_ID) // 位于你的 resources/data/mod_id/...

                // 默认放置
                .defaultAnchor(PlacementAnchor.CENTER)

                // 默认建造行为
                .defaultBuildType(BuildType.FAST)
                .defaultBuildSpeed(2f)

                // 验证
                .damagedThreshold(0.15f)
                .destroyedThreshold(0.5f)
        );
    }
}

库提供了一些用于管理的方法

    public void onCompleted(StructureInstance instance) {}

    public void onDamaged(StructureInstance instance) {}

    public void onDestroyed(StructureInstance instance) {}

    public void onDemolished(StructureInstance instance) {}

使用示例:

public class AirfieldStructure extends StructureType {
    private int productionTick;

    public AirfieldStructure() {
        super("airfield", StructureProperties.create()
                .modPath("basic/airfield", RTStructureFramework.MOD_ID)
                .defaultAnchor(PlacementAnchor.CENTER)
                .defaultBuildType(BuildType.FAST)

                .defaultBuildSpeed(3f)
                .damagedThreshold(0.2f)
                .destroyedThreshold(0.6f)
        );
    }

    @Override
    public void onCompleted(StructureInstance instance) {
        System.out.println("[RTS] Airfield completed");
    }

    @Override
    public void onTick(StructureInstance instance) {
        if (!instance.isCompleted()) return;

        productionTick++;
        if (productionTick >= 100) {
            productionTick = 0;

            System.out.println("[RTS] Kirov reporting...");
            // 执行你的操作。例如生成单位
        }
    }

    @Override
    public void onDestroyed(StructureInstance instance) {
        System.out.println("[RTS] Airfield destroyed!");
    }
}

生成结构

    StructureInstance instance = StructuresInit.AIRFIELD.get().create(level, anchorPos);
    StructureManager.add(instance);
    
    instance.build();

警告!

StructureManager.add(instance); 实际上会创建你的结构;

instance.build(); 只是建造你的结构;

如果你需要移除结构,请使用 instance.destroy();(警告! 在频繁调用时可能导致栈溢出。切勿将其放入 tick(); 中)

使用示例:

public class CrystalStructure extends StructureType {

    public CrystalStructure() {
        super("crystal", StructureProperties.create()
                .modPath("crystal", RTStructureFramework.MOD_ID)
                .defaultBuildType(BuildType.FAST)
                .defaultBuildSpeed(1f)
                .defaultAnchor(PlacementAnchor.CUSTOM)

                .damagedThreshold(0.05f)
                .destroyedThreshold(0.8f)
        );
    }

    @Override
    public void onTick(StructureInstance instance) {
        if (instance.isDamaged()) {
            if (!instance.isBuilding()) {
                instance.build(BuildType.FAST, 0.5f);
            }
        }
    }

    @Override
    public void onDestroyed(StructureInstance instance) {
        if (instance.getDamagePercent() >= 0.95f) {
            instance.destroy();
        }
    }

    @Override
    public void onCompleted(StructureInstance instance) {
        System.out.println(instance.debugInfo());
    }
}

本描述将被精简为正常的模组描述。文档请查看 github wiki