Doc ID: SIRC-064

Oraxen API 知识文档

Oraxen 是一个 Minecraft 插件，允许使用自定义纹理和模型创建新物品和方块。它处理资源包生成、上传（使用 Polymath）并具有可扩展的 API。

Overview

Oraxen API 文档

概述

Oraxen 是一个 Minecraft 插件，允许使用自定义纹理和模型创建新物品和方块。它处理资源包生成、上传（使用 Polymath）并具有可扩展的 API。

包结构

  • 主包: io.th0rgal.oraxen.api
  • 核心类: OraxenItems, OraxenBlocks, OraxenFurniture, OraxenPack

API 类详解

OraxenItems 类

用于管理 Oraxen 物品的核心类。

主要方法

获取 ItemBuilder

// 从 Oraxen ID 获取 ItemBuilder
OraxenItems.getItemById(itemID); // itemID 是物品配置中的 section

// 可选方式获取
OraxenItems.getOptionalItemById(id);

检查物品存在性

// 检查 Oraxen ID 是否存在
OraxenItems.isAnItem(itemID);
OraxenItems.exists(itemID);

// 检查 ItemStack 是否为 Oraxen 物品
OraxenItems.exists(itemStack);

从 ItemStack 提取 Oraxen ID

// 从 ItemBuilder 获取 ID
OraxenItems.getIdByItem(itemBuilder);

// 从 ItemStack 获取 ID（如果不是 Oraxen 物品则返回 null）
OraxenItems.getIdByItem(itemStack);

获取 ItemBuilder

// 从 ItemStack 获取对应的 ItemBuilder
OraxenItems.getBuilderByItem(item);

物品流操作

// 获取所有未从库存排除的物品
OraxenItems.getUnexcludedItems();

// 获取特定文件中的未排除物品
OraxenItems.getUnexcludedItems(file);

// 获取所有物品
OraxenItems.getItems();

名称和条目操作

// 获取所有物品名称
OraxenItems.getNames();
OraxenItems.nameArray();
OraxenItems.nameStream();

// 获取所有条目
OraxenItems.getEntries();
OraxenItems.getEntriesAsMap();

// 获取物品流
OraxenItems.itemStream();
OraxenItems.entryStream();

检查机制

// 检查物品是否具有特定机制
OraxenItems.hasMechanic(itemID, mechanicID);

从名称列表获取物品堆栈

// 从名称列表获取 ItemStack 列表
OraxenItems.getItemStacksByName(List<List<String>> lists);
// 格式: [["type:item_id", "amount:1"], ...]

OraxenBlocks 类

用于管理自定义方块和家具的类。

方块类型检查

// 检查是否为 Oraxen 方块
OraxenBlocks.isOraxenBlock(block);
OraxenBlocks.isOraxenBlock(itemID);

// 检查特定类型
OraxenBlocks.isOraxenNoteBlock(block);
OraxenBlocks.isOraxenNoteBlock(itemID);
OraxenBlocks.isOraxenNoteBlock(item);

OraxenBlocks.isOraxenStringBlock(block);
OraxenBlocks.isOraxenStringBlock(itemID);

OraxenBlocks.isOraxenChorusBlock(block);
OraxenBlocks.isOraxenChorusBlock(itemID);

获取方块ID集合

// 获取所有方块ID
OraxenBlocks.getBlockIDs();

// 获取特定类型方块ID
OraxenBlocks.getNoteBlockIDs();
OraxenBlocks.getStringBlockIDs();
OraxenBlocks.getChorusBlockIDs();

放置方块

// 放置 Oraxen 方块
OraxenBlocks.place(itemID, location);

// 获取方块的 BlockData
OraxenBlocks.getOraxenBlockData(itemID);

移除方块

// 移除方块（可选玩家）
OraxenBlocks.remove(location, player);
OraxenBlocks.remove(location, player, forceDrop);
OraxenBlocks.remove(location, player, overrideDrop);

获取机制实例

// 获取位置上的 Oraxen 方块机制
OraxenBlocks.getOraxenBlock(location);
OraxenBlocks.getOraxenBlock(blockData);

// 获取特定类型机制
OraxenBlocks.getNoteBlockMechanic(block);
OraxenBlocks.getNoteBlockMechanic(blockData);
OraxenBlocks.getNoteBlockMechanic(itemID);

OraxenBlocks.getStringMechanic(block);
OraxenBlocks.getStringMechanic(blockData);
OraxenBlocks.getStringMechanic(itemID);

OraxenBlocks.getChorusMechanic(block);
OraxenBlocks.getChorusMechanic(blockData);
OraxenBlocks.getChorusMechanic(itemID);

OraxenBlocks.getBlockMechanic(block);

OraxenFurniture 类

用于管理自定义家具的类。

家具检查

// 检查是否为家具
OraxenFurniture.isFurniture(block);
OraxenFurniture.isFurniture(itemID);
OraxenFurniture.isFurniture(entity);

// 检查实体类型
OraxenFurniture.isBaseEntity(entity);
OraxenFurniture.isInteractionEntity(entity);

获取家具ID集合

// 获取所有家具ID
OraxenFurniture.getFurnitureIDs();

放置家具

// 放置家具（使用 Rotation）
OraxenFurniture.place(itemID, location, rotation, blockFace);

// 放置家具（使用 yaw）
OraxenFurniture.place(itemID, location, yaw, blockFace);

// 旧版方法（已弃用）
OraxenFurniture.place(location, itemID, rotation, blockFace);

移除家具

// 从位置移除家具
OraxenFurniture.remove(location, player);
OraxenFurniture.remove(location, player, drop);

// 从实体移除家具
OraxenFurniture.remove(baseEntity, player);
OraxenFurniture.remove(baseEntity, player, drop);

获取家具机制

// 从不同来源获取家具机制
OraxenFurniture.getFurnitureMechanic(block);
OraxenFurniture.getFurnitureMechanic(entity);
OraxenFurniture.getFurnitureMechanic(itemID);

更新家具

// 更新家具实体
OraxenFurniture.updateFurniture(entity);

OraxenPack 类

用于管理资源包的类。

资源包操作

// 添加文件到资源包
OraxenPack.addFilesToPack(files);

// 获取资源包文件
OraxenPack.getPack();

// 上传资源包
OraxenPack.uploadPack();

// 重新加载资源包
OraxenPack.reloadPack();

常量

OraxenItems 常量

// 物品ID的 NamespacedKey
OraxenItems.ITEM_ID = new NamespacedKey(OraxenPlugin.get(), "id");

OraxenFurniture 常量

// 家具键
FURNITURE_KEY
BARRIER_KEY
SEAT_KEY
EVOLUTION_KEY

存储机制常量

// 存储键
STORAGE_KEY
PERSONAL_STORAGE_KEY

使用示例

基本物品操作

// 创建 Oraxen 物品
ItemBuilder builder = OraxenItems.getItemById("my_custom_item");
ItemStack item = builder.build();

// 检查物品
if (OraxenItems.exists(item)) {
    String itemId = OraxenItems.getIdByItem(item);
    // 处理物品
}

// 获取所有物品
Collection<ItemBuilder> allItems = OraxenItems.getItems();

方块操作

// 放置自定义方块
Location location = player.getLocation();
OraxenBlocks.place("custom_block", location);

// 检查并移除方块
Block block = location.getBlock();
if (OraxenBlocks.isOraxenBlock(block)) {
    OraxenBlocks.remove(location, player);
}

// 获取方块机制
NoteBlockMechanic mechanic = OraxenBlocks.getNoteBlockMechanic(block);
if (mechanic != null) {
    // 使用机制
}

家具操作

// 放置家具
Location furnitureLoc = location.clone().add(0, 1, 0);
Entity furniture = OraxenFurniture.place("custom_chair", furnitureLoc, Rotation.NONE, BlockFace.UP);

// 移除家具
if (furniture != null) {
    OraxenFurniture.remove(furniture, player);
}

资源包操作

// 添加自定义文件到资源包
File customFile = new File("path/to/custom/texture.png");
OraxenPack.addFilesToPack(new File[]{customFile});

// 重新生成并上传资源包
OraxenPack.reloadPack();
OraxenPack.uploadPack();

注意事项

  1. 物品ID: 所有物品ID都对应配置文件中物品的 section 名称
  2. 空值处理: 许多方法可能返回 null，需要进行空值检查
  3. 玩家参数: 可选玩家参数可以为 null，表示由服务器执行操作
  4. 游戏模式: 创造模式玩家不会触发掉落物生成
  5. 版本兼容性: 某些功能可能仅在特定 Minecraft 版本中可用

依赖关系

  • 需要 Oraxen 插件作为依赖
  • 支持 Paper/Spigot 服务器
  • 需要 Minecraft 1.14+ 版本

扩展机制

Oraxen 支持自定义机制，可以通过 MechanicsManager 注册新的机制工厂。详细机制开发请参考官方文档的机制部分。

内容来自 SnowCutieOwO – Wiki