Doc ID: SIRC-119

Slimefun4 API 文档

Slimefun4(粘液科技) 是一个 Minecraft 插件，提供丰富的科技魔法系统。本文档重点介绍其 API 用法、包结构和核心类，供 AI 开发参考。

Overview

Slimefun4 API 文档

概述

Slimefun4 是一个 Minecraft 插件，提供丰富的科技魔法系统。本文档重点介绍其 API 用法、包结构和核心类，供 AI 开发参考。

核心包结构

API 包 (io.github.thebusybiscuit.slimefun4.api)

Slimefun 的主要 API 包，包含与 Slimefun 交互的类和子包。

主要类：

  1. SlimefunAddon – 附属插件接口

    • 用于标识注册 SlimefunItem 的插件
    • 提供实用方法如 getBugTrackerURL()
    • 方法：
      • getJavaPlugin() – 返回 JavaPlugin 实例
      • getBugTrackerURL() – 返回 Bug Tracker URL
      • getName() – 返回附属名称
      • getPluginVersion() – 返回版本
      • getLogger() – 返回日志记录器
      • hasDependency(String) – 检查依赖

  2. SlimefunBranch – 构建分支枚举

  3. MinecraftVersion – 支持的 Minecraft 版本枚举

  4. ErrorReport – 错误报告类

事件包 (io.github.thebusybiscuit.slimefun4.api.events)

包含 Slimefun 提供的所有事件扩展，允许监听各种事件。

主要事件：

  • AncientAltarCraftEvent – 远古祭坛物品掉落前触发
  • AndroidFarmEvent – 农夫机器人收获方块前触发
  • AndroidMineEvent – 矿工机器人挖掘方块前触发
  • AsyncAutoEnchanterProcessEvent – 自动附魔器处理时触发
  • AsyncMachineOperationFinishEvent – 机器操作完成时触发
  • AsyncProfileLoadEvent – 玩家配置文件加载时触发
  • AutoDisenchantEvent – 自动祛魔器祛魔时触发
  • AutoEnchantEvent – 自动附魔器尝试附魔时触发
  • BlockPlacerPlaceEvent – 方块放置器放置方块时触发
  • ClimbingPickLaunchEvent – 攀爬镐使用时触发
  • CoolerFeedPlayerEvent – 冷却器喂食玩家时触发
  • ExplosiveToolBreakBlocksEvent – 爆炸工具破坏方块时触发
  • GEOResourceGenerationEvent – GEO资源生成时触发
  • MultiBlockCraftEvent – 多方块机器合成物品时触发
  • MultiBlockInteractEvent – 与多方块交互时触发
  • PlayerLanguageChangeEvent – 玩家切换语言时触发
  • PlayerPreResearchEvent – 玩家点击解锁研究时触发
  • PlayerRightClickEvent – 自定义右键点击事件
  • RadiationDamageEvent – 玩家受到辐射伤害时触发
  • ReactorExplodeEvent – 反应堆爆炸时触发
  • ResearchUnlockEvent – 玩家解锁研究时触发
  • SlimefunBlockBreakEvent – Slimefun方块被破坏时触发
  • SlimefunBlockPlaceEvent – Slimefun方块被放置时触发
  • SlimefunGuideOpenEvent – 打开Slimefun指南时触发
  • SlimefunItemRegistryFinalizedEvent – Slimefun物品注册完成时触发
  • SlimefunItemSpawnEvent – Slimefun掉落物品时触发
  • TalismanActivateEvent – 护身符激活时触发
  • WaypointCreateEvent – 创建路径点时触发

物品包 (io.github.thebusybiscuit.slimefun4.api.items)

包含 SlimefunItem 相关的 API 类，如 ItemSetting。

主要类：

  1. SlimefunItem – 核心物品类

    • 由 SlimefunAddon 注册的自定义物品
    • 定义物品行为，可分配 ItemHandler 提供功能
    • 必须调用 register(SlimefunAddon) 才能在 SlimefunGuide 中显示

    构造函数：

    SlimefunItem(ItemGroup itemGroup, SlimefunItemStack item)
SlimefunItem(ItemGroup itemGroup, SlimefunItemStack item, RecipeType recipeType, ItemStack[] recipe)
SlimefunItem(ItemGroup itemGroup, SlimefunItemStack item, RecipeType recipeType, ItemStack[] recipe, ItemStack recipeOutput)

    主要方法：

    • register(SlimefunAddon addon) – 注册物品
    • addItemHandler(ItemHandler... handlers) – 添加物品处理器
    • addItemSetting(ItemSetting<?>... settings) – 添加物品设置
    • getById(String id) – 通过ID获取物品
    • getByItem(ItemStack item) – 通过物品堆获取物品
    • isItem(ItemStack item) – 检查物品堆是否代表此物品
    • canUse(Player p, boolean sendMessage) – 检查玩家能否使用
    • setRecipe(ItemStack[] recipe) – 设置配方
    • setRecipeType(RecipeType type) – 设置配方类型
    • setItemGroup(ItemGroup itemGroup) – 设置物品组
    • setResearch(Research research) – 设置研究
    • setHidden(boolean hidden) – 设置是否隐藏
    • addOfficialWikipage(String page) – 添加官方Wiki页面

  2. SlimefunItemStack – Slimefun物品堆基类

  3. ItemGroup – 物品组，在SlimefunGuide中组织多个SlimefunItem

  4. ItemHandler – 物品处理器，表示SlimefunItem可以执行的操作

  5. ItemSetting – 物品设置，可通过Items.yml配置文件修改

  6. ItemSpawnReason – 物品生成原因枚举

  7. ItemState – 物品状态枚举（启用、禁用、回退到原版行为）

  8. HashedArmorpiece – 检查玩家是否在tick之间更换了护甲

物品组包 (io.github.thebusybiscuit.slimefun4.api.items.groups)

包含 ItemGroup 变体。

物品设置包 (io.github.thebusybiscuit.slimefun4.api.items.settings)

包含 ItemSetting 的各种子类。

网络包 (io.github.thebusybiscuit.slimefun4.api.network)

提供网络API基础设施，如货运网络或能源网络。

玩家包 (io.github.thebusybiscuit.slimefun4.api.player)

存储与玩家相关的API类，如PlayerProfile。

配方包 (io.github.thebusybiscuit.slimefun4.api.recipes)

包含所有与配方系统相关的类。

研究包 (io.github.thebusybiscuit.slimefun4.api.researches)

包含与Research类相关的所有内容。

地理资源包 (io.github.thebusybiscuit.slimefun4.api.geo)

包含围绕GEOResource API的类。

GPS包 (io.github.thebusybiscuit.slimefun4.api.gps)

存储与GPSNetwork相关的API类。

异常包 (io.github.thebusybiscuit.slimefun4.api.exceptions)

包含Slimefun内部使用的所有Exception扩展。

核心包 (io.github.thebusybiscuit.slimefun4.core)

包含Slimefun的核心系统，不一定用作API，而是提供插件的核心功能。

属性包 (io.github.thebusybiscuit.slimefun4.core.attributes)

包含可分配给SlimefunItem的所有ItemAttribute变体。

交互包 (io.github.thebusybiscuit.slimefun4.core.attributes.interactions)

包含ExternallyInteractable对象可以返回的各种InteractionResult。

命令包 (io.github.thebusybiscuit.slimefun4.core.commands)

包含与Slimefun游戏内命令相关的所有内容。

子命令包 (io.github.thebusybiscuit.slimefun4.core.commands.subcommands)

包含SubCommand的所有实现。

调试包 (io.github.thebusybiscuit.slimefun4.core.debug)

包含Slimefun的调试功能。

指南包 (io.github.thebusybiscuit.slimefun4.core.guide)

包含SlimefunGuide的核心系统。

指南选项包 (io.github.thebusybiscuit.slimefun4.core.guide.options)

包含SlimefunGuide的设置菜单以及添加自定义选项的SlimefunGuideOption接口。

处理器包 (io.github.thebusybiscuit.slimefun4.core.handlers)

包含可分配给SlimefunItem的所有ItemHandler变体。

机器包 (io.github.thebusybiscuit.slimefun4.core.machines)

包含与MachineProcessor和任何MachineOperation相关的源。

多方块包 (io.github.thebusybiscuit.slimefun4.core.multiblocks)

包含与MultiBlock相关的所有核心机制。

网络包 (io.github.thebusybiscuit.slimefun4.core.networks)

提供Network类的核心功能，如NetworkManager以及实际Network实现的子包。

货运网络包 (io.github.thebusybiscuit.slimefun4.core.networks.cargo)

包含负责物品运输的Network实现。

能源网络包 (io.github.thebusybiscuit.slimefun4.core.networks.energy)

包含负责能量传输的Network实现。

服务包 (io.github.thebusybiscuit.slimefun4.core.services)

提供Slimefun使用的一些"服务"。

GitHub服务包 (io.github.thebusybiscuit.slimefun4.core.services.github)

包含与GitHub和贡献者相关的一切。

全息图服务包 (io.github.thebusybiscuit.slimefun4.core.services.holograms)

包含与HologramsService相关的一切。

本地化服务包 (io.github.thebusybiscuit.slimefun4.core.services.localization)

包含与翻译和本地化相关的一切。

性能分析器服务包 (io.github.thebusybiscuit.slimefun4.core.services.profiler)

包含与SlimefunProfiler相关的类。

性能检查器包 (io.github.thebusybiscuit.slimefun4.core.services.profiler.inspectors)

包含PerformanceInspector的不同实现。

声音服务包 (io.github.thebusybiscuit.slimefun4.core.services.sounds)

包含与SoundService相关的类。

实现包 (io.github.thebusybiscuit.slimefun4.implementation)

包含与此插件实际实现相关的所有类。

指南实现包 (io.github.thebusybiscuit.slimefun4.implementation.guide)

提供SlimefunGuide的不同实现。

处理器实现包 (io.github.thebusybiscuit.slimefun4.implementation.handlers)

包含ItemHandler的简单实现。

物品实现包 (io.github.thebusybiscuit.slimefun4.implementation.items)

包含每个SlimefunItem的不同类。

子包：

  • altar – 与远古祭坛相关的SlimefunItem实现
  • androids – 与可编程机器人相关的SlimefunItem实现
  • armor – 与护甲相关的SlimefunItem实现
  • autocrafters – 与自动合成台相关的电动机器
  • backpacks – 与Slimefun背包相关的类
  • blocks – 一些杂项的SlimefunItem块实现
  • cargo – 与货运网络相关的SlimefunItem实现
  • electric – 实现EnergyNetComponent接口的SlimefunItem
  • electric.gadgets – 与电力结合使用的SlimefunItem实现
  • electric.generators – AGenerator的不同实现
  • electric.machines – 类型为CONSUMER的EnergyNetComponent的SlimefunItem实现
  • electric.machines.accelerators – 与生长加速相关的电动机器
  • electric.machines.enchanting – 与附魔相关的电动机器
  • electric.machines.entities – 与实体交互相关的电动机器
  • electric.reactors – Reactor的不同实现
  • elevator – 电梯板及相关类
  • food – 与食物相关的SlimefunItem实现
  • geo – 处理GEOResource API的任何SlimefunItem实现
  • gps – 与GPS网络相关的SlimefunItem实现
  • magical – 被认为是魔法物品的SlimefunItem实现
  • magical.runes – 具有功能的古代符文实现
  • magical.staves – 被认为是"魔法法杖"的SlimefunItem实现
  • magical.talismans – 与护身符相关的SlimefunItem
  • medical – 与治疗自己相关的SlimefunItem实现
  • misc – 任何杂项的SlimefunItem实现
  • multiblocks – MultiBlockMachine的所有不同实现
  • multiblocks.miner – 与工业矿机相关的类
  • seasonal – 可以在SeasonalItemGroup中遇到的SlimefunItem实现
  • teleporter – 与传送器相关的SlimefunItem实现
  • tools – 是工具的SlimefunItem实现
  • weapons – 是武器的SlimefunItem实现

监听器包 (io.github.thebusybiscuit.slimefun4.implementation.listeners)

包含Slimefun使用的所有Listener实现。

操作包 (io.github.thebusybiscuit.slimefun4.implementation.operations)

包含MachineOperation的实现。

资源包 (io.github.thebusybiscuit.slimefun4.implementation.resources)

包含GEOResource的所有实现。

设置包 (io.github.thebusybiscuit.slimefun4.implementation.settings)

包含用于非常特定的SlimefunItems的ItemSetting实现。

设置包 (io.github.thebusybiscuit.slimefun4.implementation.setup)

在此包中初始化物品、研究等。

任务包 (io.github.thebusybiscuit.slimefun4.implementation.tasks)

包含Slimefun定期运行的几个任务。

集成包 (io.github.thebusybiscuit.slimefun4.integrations)

包含与Slimefun和第三方插件集成相关的类。

工具包 (io.github.thebusybiscuit.slimefun4.utils)

包含一些提供便捷方式的工具类。

生物群系包 (io.github.thebusybiscuit.slimefun4.utils.biomes)

包含围绕BiomeMap工具的类。

兼容性包 (io.github.thebusybiscuit.slimefun4.utils.compatibility)

包含兼容性相关工具。

物品堆包 (io.github.thebusybiscuit.slimefun4.utils.itemstack)

包含围绕ItemStack创建或处理的一些工具类。

标签包 (io.github.thebusybiscuit.slimefun4.utils.tags)

包含与SlimefunTag枚举相关的工具。

旧包 (me.mrCookieSlime)

旧包，尚未重写的过去版本的残余。

使用示例

创建自定义物品

public class MyCustomItem extends SlimefunItem {
    
    public MyCustomItem(ItemGroup itemGroup, SlimefunItemStack item, RecipeType recipeType, ItemStack[] recipe) {
        super(itemGroup, item, recipeType, recipe);
    }
    
    @Override
    public void preRegister() {
        // 添加物品处理器
        addItemHandler(new ItemHandler() {
            @Override
            public void onRightClick(PlayerRightClickEvent event) {
                // 右键点击逻辑
                event.getPlayer().sendMessage("你点击了自定义物品！");
            }
        });
    }
}

// 注册物品
MyCustomItem myItem = new MyCustomItem(
    itemGroup,
    new SlimefunItemStack("MY_CUSTOM_ITEM", Material.DIAMOND, "&b自定义物品"),
    RecipeType.ENHANCED_CRAFTING_TABLE,
    new ItemStack[] {
        new ItemStack(Material.DIAMOND), null, new ItemStack(Material.DIAMOND),
        null, new ItemStack(Material.EMERALD), null,
        new ItemStack(Material.DIAMOND), null, new ItemStack(Material.DIAMOND)
    }
);
myItem.register(myAddon);

监听事件

@EventHandler
public void onResearchUnlock(ResearchUnlockEvent event) {
    Player player = event.getPlayer();
    Research research = event.getResearch();
    
    player.sendMessage("你解锁了研究: " + research.getName());
}

创建附属插件

public class MyAddon extends JavaPlugin implements SlimefunAddon {
    
    @Override
    public JavaPlugin getJavaPlugin() {
        return this;
    }
    
    @Override
    public String getBugTrackerURL() {
        return "https://github.com/yourname/myaddon/issues";
    }
    
    @Override
    public void onEnable() {
        // 初始化你的附属
        setupItems();
    }
    
    private void setupItems() {
        // 创建和注册物品
    }
}

重要注意事项

  1. 物品注册：必须调用 register(SlimefunAddon) 方法才能让物品出现在SlimefunGuide中
  2. 物品处理器：通过 addItemHandler() 为物品添加功能
  3. 物品设置：通过 addItemSetting() 添加可配置的设置
  4. 研究关联：使用 setResearch() 或将物品添加到研究中
  5. Wiki页面：使用 addOfficialWikipage() 添加官方Wiki链接
  6. 错误处理：使用 error(), warn(), info() 方法记录日志

最佳实践

  1. 始终在 preRegister() 方法中添加物品处理器和设置
  2. 使用 SlimefunItemStack 而不是普通 ItemStack 来创建Slimefun物品
  3. 检查玩家是否可以使用物品：canUse(Player, boolean)
  4. 为物品添加适当的权限和研究要求
  5. 使用事件系统而不是直接修改Slimefun内部状态
  6. 遵循Slimefun的命名约定和代码风格

此文档提供了Slimefun4 API的核心概述，重点关注开发附属插件所需的关键类和用法。