Odventure Core

A Minecraft mod that adds two kinds of display blocks: the Trophy Base and the Medal. Put a block, item, or spawn egg (Trophy) or an item (Medal) on display and give it a custom name. Finished displays can be retrieved as items; their data is saved on the item and restored when placed again.

Platform: Minecraft 1.20.1 / Forge 47.x
Mod ID: odventure_core
Version: 1.0.0
Author: liluo23

Features

Trophy Base

A short smooth-stone pedestal that faces the player when placed.
Right-click with a block, item, or spawn egg to display it:
- Block: the block is rendered above the pedestal
- Item: the item is rendered as a 3D model
- Spawn egg: the adult form of the entity is rendered, auto-scaled to a uniform size
Once content is set, the pedestal becomes a full-cube collision.
In creative mode, the display scale, rotation, and height offset can be adjusted.

Medal

A wall-mounted medal that attaches to the clicked face.
Mounts on full blocks, all kinds of glass, and glowstone. Slabs, stairs, fences, walls, flower pots and other partial blocks are rejected.
Drops automatically when its supporting block is removed.
Right-click with an item to embed it; the item is shown in the center of the medal.

Shared behavior

Content and name lock independently. Setting content locks the content; naming locks the name.
Sneak right-click or break the block to retrieve the finished item. The item carries its data and restores the display (and lock state) when placed again.
Finished items render their actual content in the inventory, in hand, on the ground, and in item frames (an angled 3D preview), so you can tell what is inside at a glance.
When looked at, a floating name tag is shown above the block. § color codes are supported.
Hovering the item shows the custom name and the displayed content name.
Anvils cannot rename finished items. Names are set only through the in-game naming screen.

How to use

Take an empty Trophy Base or empty Medal from the "Odventure" creative tab.
Place it in the world.
Right-click with the content to display; the content locks immediately.
Empty-hand right-click to open the naming screen, enter a name and confirm; the name locks.
Sneak right-click or break to retrieve the finished item; place it again to restore.

Configuration

Two config files are generated.

odventure_core-client.toml

[render]
    # Whether finished items dynamically render their display content (off = plain icon).
    renderFinishedItems = true
    # Show a floating name when looking at a trophy/medal.
    showFloatingName = true

[entities]
    # Entity render blacklist (registry names). Not rendered anywhere, prevents crashes.
    renderBlacklist = ["minecraft:area_effect_cloud", "minecraft:lightning_bolt", "minecraft:falling_block", "minecraft:item", "minecraft:player"]

odventure_core-common.toml

[gameplay]
    # Whether to block anvil renaming of finished items.
    enableAnvilBlock = true
    # Whether sneak right-click retrieves the item (off = break only).
    enableSneakRetrieve = true

If rendering finished items in the inventory causes lag (many entity trophies stacked), turn off renderFinishedItems, or add the heavy entity to renderBlacklist.

Giving finished items (commands)

A finished item is just an item with data under BlockEntityTag.

Trophy displaying a diamond:

/give @p odventure_core:trophy_base{BlockEntityTag:{ContentType:"ITEM",ContentId:"minecraft:diamond",ContentLocked:1b,CustomName:"§6Champion Trophy",NameLocked:1b,DisplayScale:1.0f,DisplayYaw:0.0f,DisplayY:0.0f}}

Trophy displaying a creeper:

/give @p odventure_core:trophy_base{BlockEntityTag:{ContentType:"ENTITY",ContentId:"minecraft:creeper",ContentLocked:1b,CustomName:"§aBoss Slayer",NameLocked:1b,DisplayScale:0.8f,DisplayYaw:0.0f,DisplayY:0.0f}}

Medal embedding a nether star:

/give @p odventure_core:medal{BlockEntityTag:{EmbeddedItem:{id:"minecraft:nether_star",Count:1b},ContentLocked:1b,CustomName:"§bGreatest Hero",NameLocked:1b}}

FTB Quests rewards

Compatible out of the box, because all data lives in standard item NBT (BlockEntityTag), which the quest reward serializer preserves.

In-game capture: obtain the finished item, then in the FTB Quests editor add an Item reward and pick it from your inventory.
Via the API in a script (e.g. KubeJS): build the exact item with OdventureCoreAPI, then use it as the reward stack.

KubeJS example:

// kubejs/server_scripts/odventure_reward.js
const API = Java.loadClass('com.odventure.core.api.OdventureCoreAPI')
const ContentType = Java.loadClass('com.odventure.core.data.TrophyData$ContentType')
const ResourceLocation = Java.loadClass('net.minecraft.resources.ResourceLocation')

global.makeChampionTrophy = () => {
    return API.createTrophy(
        ContentType.ITEM,
        new ResourceLocation('minecraft', 'diamond'),
        '§6Champion Trophy',
        1.0, 0.0, 0.0
    )
}

API

Facade class: com.odventure.core.api.OdventureCoreAPI

// Build finished items
ItemStack createTrophy(TrophyData.ContentType type, ResourceLocation contentId, String name)
ItemStack createTrophy(TrophyData.ContentType type, ResourceLocation contentId, String name,
                       float displayScale, float displayYaw, float displayY)
ItemStack createMedal(ItemStack embedded, String name)

// Write into an existing display block in the world
boolean writeTrophy(Level level, BlockPos pos, TrophyData data)
boolean writeMedal(Level level, BlockPos pos, MedalData data)

// Read
TrophyData readTrophy(ItemStack stack)
TrophyData readTrophy(Level level, BlockPos pos)
MedalData readMedal(ItemStack stack)
MedalData readMedal(Level level, BlockPos pos)

TrophyData exposes display parameters via getDisplayScale()/setDisplayScale(float), getDisplayYaw()/setDisplayYaw(float), and getDisplayY()/setDisplayY(float). MedalData has no display parameters. Both classes are public; see the in-class comments for field semantics.

Compatibility notes

Some entities (Ender Dragon, Wither, etc.) are complex or need special context. They are handled with size clamping and exception guards; a few may render imperfectly but will not crash the game.
Entities that fail to render are skipped automatically.

License

Odventure Core（中文）

为 Minecraft 添加两类展示型方块：奖杯基座与奖章。把方块、物品、刷怪蛋（奖杯）或物品（奖章）放进去展示并自定义名称。成品可作为物品取回，数据随物品保存，重新放置即可还原。

平台：Minecraft 1.20.1 / Forge 47.x
Mod ID：odventure_core
版本：1.0.0
作者：liluo23

功能

奖杯基座

平滑石材质的矮台座，放置时朝向玩家。
手持方块、物品或刷怪蛋右键放入展示：
- 方块：在台座上方渲染该方块
- 物品：渲染物品 3D 模型
- 刷怪蛋：渲染对应实体的成体，按体型自动缩放到统一大小
放入内容后台座变为整格碰撞。
创造模式下可调整展示物的缩放、旋转角度与高度偏移。

奖章

贴墙的金牌，放置时贴向被点击的墙面。
可挂载在完整方块、各类玻璃、萤石上；台阶、楼梯、栅栏、墙、花盆等不完整方块无法挂载。
支撑方块被移除时自动掉落。
手持物品右键嵌入展示，物品显示在金牌中央。

通用行为

内容与名称各自独立上锁。放入内容后锁定内容，命名后锁定名称。
潜行右键或破坏方块取回成品。成品为带数据的物品，重新放置还原展示并保持锁定状态。
成品物品会在背包、手持、地面、物品展示框中渲染出实际展示内容（斜置 3D 预览），一眼就能看出里面装了什么。
准心指向时，方块上方显示悬浮名牌，支持 § 颜色代码。
物品悬停显示自定义名与展示内容名。
铁砧无法对成品改名，名称统一通过游戏内命名界面设置。

使用方法

从创造栏「Odventure」取出空奖杯基座或空奖章。
放置到世界中。
手持要展示的内容右键放入，内容随即锁定。
空手右键打开命名界面，输入名称后确认，名称随即锁定。
潜行右键或破坏方块取回成品；重新放置可还原。

配置

会生成两个配置文件。

odventure_core-client.toml

[render]
    # 成品物品是否动态渲染展示内容（关闭则使用普通图标，省性能）。
    renderFinishedItems = true
    # 准心指向奖杯/奖章时是否悬浮显示名字。
    showFloatingName = true

[entities]
    # 实体渲染黑名单（注册名）。名单内实体在世界与物品中都不渲染，避免崩溃。
    renderBlacklist = ["minecraft:area_effect_cloud", "minecraft:lightning_bolt", "minecraft:falling_block", "minecraft:item", "minecraft:player"]

odventure_core-common.toml

[gameplay]
    # 是否屏蔽铁砧对成品改名。
    enableAnvilBlock = true
    # 是否支持潜行右键取回（关闭则只能破坏取回）。
    enableSneakRetrieve = true

如果背包里动态渲染成品导致卡顿（堆叠了大量展示实体的奖杯），关闭 renderFinishedItems，或把对应的高开销实体加入 renderBlacklist。

发放成品（指令）

成品就是一个数据存在 BlockEntityTag 下的物品。

展示钻石的奖杯：

/give @p odventure_core:trophy_base{BlockEntityTag:{ContentType:"ITEM",ContentId:"minecraft:diamond",ContentLocked:1b,CustomName:"§6冠军奖杯",NameLocked:1b,DisplayScale:1.0f,DisplayYaw:0.0f,DisplayY:0.0f}}

展示苦力怕的奖杯：

/give @p odventure_core:trophy_base{BlockEntityTag:{ContentType:"ENTITY",ContentId:"minecraft:creeper",ContentLocked:1b,CustomName:"§aBoss终结者",NameLocked:1b,DisplayScale:0.8f,DisplayYaw:0.0f,DisplayY:0.0f}}

嵌入下界之星的奖章：

/give @p odventure_core:medal{BlockEntityTag:{EmbeddedItem:{id:"minecraft:nether_star",Count:1b},ContentLocked:1b,CustomName:"§b最佳勇士",NameLocked:1b}}

FTB 任务奖励

开箱兼容，因为所有数据都存在标准物品 NBT（BlockEntityTag）里，任务奖励的序列化会原样保留。

游戏内捕获：先拿到成品，在 FTB Quests 编辑器里添加物品奖励并从背包选取。
用脚本调 API（如 KubeJS）：用 OdventureCoreAPI 构造出精确的物品，作为奖励物品使用。

KubeJS 示例：

// kubejs/server_scripts/odventure_reward.js
const API = Java.loadClass('com.odventure.core.api.OdventureCoreAPI')
const ContentType = Java.loadClass('com.odventure.core.data.TrophyData$ContentType')
const ResourceLocation = Java.loadClass('net.minecraft.resources.ResourceLocation')

global.makeChampionTrophy = () => {
    return API.createTrophy(
        ContentType.ITEM,
        new ResourceLocation('minecraft', 'diamond'),
        '§6冠军奖杯',
        1.0, 0.0, 0.0
    )
}

API

门面类：com.odventure.core.api.OdventureCoreAPI

// 构造成品
ItemStack createTrophy(TrophyData.ContentType type, ResourceLocation contentId, String name)
ItemStack createTrophy(TrophyData.ContentType type, ResourceLocation contentId, String name,
                       float displayScale, float displayYaw, float displayY)
ItemStack createMedal(ItemStack embedded, String name)

// 写入世界中已存在的展示方块
boolean writeTrophy(Level level, BlockPos pos, TrophyData data)
boolean writeMedal(Level level, BlockPos pos, MedalData data)

// 读取
TrophyData readTrophy(ItemStack stack)
TrophyData readTrophy(Level level, BlockPos pos)
MedalData readMedal(ItemStack stack)
MedalData readMedal(Level level, BlockPos pos)

TrophyData 通过 getDisplayScale()/setDisplayScale(float)、getDisplayYaw()/setDisplayYaw(float)、getDisplayY()/setDisplayY(float) 暴露展示参数。MedalData 没有展示参数。两个类均为 public，字段语义见类内注释。

兼容性说明

部分实体（末影龙、凋灵等）模型复杂或需要特殊上下文，渲染时受体型缩放与异常保护处理；个别实体可能显示效果有限，但不会导致游戏崩溃。
渲染异常的实体会被自动跳过。

odventure-core