FancyMenu Wiki/自定义元素
关于
你可以通过FancyMenu API为FancyMenu编写拓展模组实现自定义元素。
准备开发环境
请参阅 准备工作区。
添加新元素
每个自定义元素（或item，因为元素在内部被称为此）都需要封装到CustomizationItemContainer中。
在模组初始化时，这个容器需要注册到CustomizationItemRegistry。
创建Item
实际上item的类是CustomizationItem。这个类是渲染它并存储其所有属性的项。
给你的项创建一个CustomizationItem的新子类，自己的孩子好好起名嗷。
在这里，我会将我的演示用项类命名为ExampleCustomizationItem。
在这个类中有两个很重要的东西。
构造方法(Constructor)
第一个就是这个类的构造方法。
在这里，你需要反序列化 已保存/序列化 的项实例的属性。并需要把它设置为新的真实例。
保存到布局时，项会被序列化为PropertiesSections。
你只关心（你自己）你的自定义项的值就行。每一项的基本的长宽高坐标部分啥的都默认让超类整完了。
//The constuctor is used to de-serialize the PropertiesSection and set all of its values to the new real item instance.
//构造方法用于反序列化PropertiesSection并将其所有值设置为新的真项实例。
public ExampleCustomizationItem(CustomizationItemContainer parentContainer, PropertiesSection item) {
//The superclass will automatically get values like orientation, x pos, y pos, width and height and will set it to the real item instance.
//超类会自动获取长宽高位置坐标等将它们设置到真项实例中。
super(parentContainer, item);
//Getting a custom property from the serialized item instance and set it to the real instance
//从序列化的项实例中获取自定义属性并将其设置为真实例。
String someProperty = item.getEntryValue("saved_property");
if (someProperty != null) {
this.someField = someProperty;
}
}
render()
还有一件事，你得渲染你的项。
这个方法是你的项的灵魂，使用这个方法来改变你的项的可视部分，就那个一会你可以在菜单看见的。
所以就在这里做你的事，知道吗？
这里唯一真正必要的部分是将此方法中的所有内容封装到shouldRender()中。
这个方法检查可视化需求和其他重要内容，所以请别把这里忘了捏。
@Override
public void render(PoseStack matrix, Screen menu) throws IOException {
//This is really important and should be in every item render method, to check for visibility requirements and more.
//为了检查可视化需求这应该在所有的项渲染方法中。
if (this.shouldRender()) {
//Always use getPosX() and getPosY() to get the X and Y positions of the item.
//就用getPosX()和getPosY()方法获取项的X、Y位置就行。
//The fields posX and posY aren't the final position, just the base pos without the orientation!
//这里的posX和posY字段不是指最终位置，而只是没有方向的基本pos！
int x = this.getPosX(menu);
int y = this.getPosY(menu);
//We want to use placeholder text values for our 'someField' string, so we use the DynamicValueHelper to convert them,
//我们想为我们的"someField"字符串使用占位符文本值，使用DynamicValueHelper来转换即可，
//but they should look like placeholders in the editor, so we only convert them when not in the editor.
//但在编辑器中它们应该看着像占位符，所以我们不在编辑器中时转换它们。
String text;
if (!isEditorActive()) {
text = DynamicValueHelper.convertFromRaw(this.someField);
} else {
text = StringUtils.convertFormatCodes(this.someField, "&", "§");
}
//Always try to make your items' opacity changeable by setting the 'opacity' field!
//你可以尝试设置"opacity"来改变项的不透明度。
//This field is set by the "delay appearance" feature to control the fade-in opacity.
//该字段由"delay appearance"功能设置以控制淡入不透明度。
drawString(matrix, Minecraft.getInstance().font, text, x + 10, y + 10, -1 | Mth.ceil(this.opacity * 255.0F) << 24);
}
}
完整示例
这里是完整的自定义项示例。
package de.keksuccino.fancymenu.api.item.example;
import com.mojang.blaze3d.systems.RenderSystem;
import com.mojang.blaze3d.vertex.PoseStack;
import de.keksuccino.fancymenu.api.item.CustomizationItem;
import de.keksuccino.fancymenu.api.item.CustomizationItemContainer;
import de.keksuccino.fancymenu.menu.fancy.DynamicValueHelper;
import de.keksuccino.konkrete.input.StringUtils;
import de.keksuccino.konkrete.properties.PropertiesSection;
import de.keksuccino.konkrete.rendering.RenderUtils;
import net.minecraft.client.Minecraft;
import net.minecraft.client.gui.screens.Screen;
import net.minecraft.util.Mth;
import java.awt.*;
import java.io.IOException;
public class ExampleCustomizationItem extends CustomizationItem {
public String displayText = "placeholder";
public String backgroundColorString = "#38ff38";
public Color backgroundColor = new Color(56, 255, 56);
//The constuctor is used to de-serialize the PropertiesSection and set all of its values to the new real item instance.
//构造方法用于反序列化PropertiesSection并将其所有值设置为新的真项实例。
public ExampleCustomizationItem(CustomizationItemContainer parentContainer, PropertiesSection item) {
//The superclass will automatically get values like orientation, x pos, y pos, width and height and will set it to the real item instance.
//超类会自动获取长宽高位置坐标等将它们设置到真项实例中。
super(parentContainer, item);
//Getting the background HEX color from the serialized item
//从序列化项中获取背景HEX颜色。
String backColorHex = item.getEntryValue("background_color");
if (backColorHex != null) {
Color c = RenderUtils.getColorFromHexString(backColorHex);
if (c != null) {
this.backgroundColor = c;
this.backgroundColorString = backColorHex;
}
}
//Getting the display text string from the serialized item
//从序列化项中获取显示文本字符串。
String dText = item.getEntryValue("display_text");
if (dText != null) {
this.displayText = dText;
}
}
@Override
public void render(PoseStack matrix, Screen menu) throws IOException {
//This is really important and should be in every item render method, to check for visibility requirements and more.
//为了检查可视化需求这应该在所有的项渲染方法中。
if (this.shouldRender()) {
//Always use getPosX() and getPosY() to get the X and Y positions of the item.
//就用getPosX()和getPosY()方法获取项的X、Y位置就行。
//The fields posX and posY aren't the final position, just the base pos without the orientation!
//这里的posX和posY字段不是指最终位置，而只是没有方向的基本pos！
int x = this.getPosX(menu);
int y = this.getPosY(menu);
RenderSystem.enableBlend();
//Rendering the background color as background of the item.
//将背景颜色渲染为项的背景。
fill(matrix, x, y, x + this.getWidth(), y + this.getHeight(), this.backgroundColor.getRGB() | Mth.ceil(this.opacity * 255.0F) << 24);
//Rendering the display text to the upper-left side of the item
//将显示文本渲染到项的左上角。
if (this.displayText != null) {
//We want to use placeholder text values for the display text, so we use the DynamicValueHelper to convert them,
//我们想使用占位符文本值作为显示文本，使用DynamicValueHelper来转换即可，
//but they should look like placeholders in the editor, so we only convert them when not in the editor.
//但在编辑器中它们应该看着像占位符，所以我们不在编辑器中时转换它们。
String text;
if (!isEditorActive()) {
text = DynamicValueHelper.convertFromRaw(this.displayText);
} else {
text = StringUtils.convertFormatCodes(this.displayText, "&", "§");
}
//The 'opacity' field is used to set the fade-in opacity of the item when the "delay appearance" option is enabled for it.
//'opacity'字段用于设置项在启用“delay appearance”选项时的淡入不透明度。
//Always try to make your items' opacity changeable by setting the 'opacity' field! (I also used it in the fill method for the background)
////你可以尝试设置"opacity"来改变项的不透明度。(我还在背景的填充方法中使用了它)
drawString(matrix, Minecraft.getInstance().font, text, x + 10, y + 10, -1 | Mth.ceil(this.opacity * 255.0F) << 24);
}
}
}
}
创建编辑器元素
LayoutEditorElements包含在布局编辑器中对你的项重要的所有内容。
这包括与你的项相关的所有UI部分，例如说在编辑器中右键单击项时的右键菜单。
给你的项起个合适的名字并创建一个LayoutEditorElement的新子类。
接下来，我会将我的样例编辑器元素类命名为ExampleLayoutEditorElement。
在这个类中有两种重要方法需要你留意一下。
init()
第一个，由编辑器调用以初始化你的编辑器元素(主要用于初始化UI)。
每一个编辑器元素都有rightclickMenu(右键菜单)字段。这是元素的右键右键菜单。
这里的右键菜单已包含所有的默认内容，比如设置方向、删除元素等。
要是你想在这编辑你的项的自定义值，那需要在添加一个新的entries到那个右键菜单并链接到你的项。
编辑器元素类的对象字段是你的实际CustomizationItem实例，只需将其转换为你的项的子类(在本例中为ExampleCustomizationItem)即可使用其自定义字段和方法。
@Override
public void init() {
//The superclass adds basic stuff to the right-click context menu, like visibility requirement controls, delete controls, orientation, etc.
//这里的超类为右键菜单添加了些基础功能，比如可视化需求控件，删除控件，方向等。
super.init();
//The 'object' field holds the CustomizationItem instance of this element.
//"object"字段包含这个元素的CustomizationItem实例。
//Cast it to your own item class, to get and set your own fields.
//把他转换成你自己的项类，以便于获取/设置你自己的字段。
ExampleCustomizationItem i = ((ExampleCustomizationItem)this.object);
//This button will be part of the right-click context menu of the element and is used to change the 'someField' field of the CustomizationItem subclass.
//这个按钮将会成为元素右键菜单的一部分，以便于更改CustomizationItem子类的'someField'字段。
AdvancedButton someFieldButton = new AdvancedButton(0, 0, 0, 0, "Set Some Field", (press) -> {
//This is the basic input popup for text content, used in many parts of FancyMenu.
//这是文本内容的基本输入弹出框，在FancyMenu的很多部分都有使用。
FMTextInputPopup pop = new FMTextInputPopup(new Color(0, 0, 0, 0), "Set Some Field Content", null, 240, (callback) -> {
//The callback of popups will be null, when pressing ESC in it to force-close it.
//当按下ESC强制关闭窗口时，窗口回调值为空。
if (callback != null) {
if (!callback.equals(i.someField)) {
//Create a snapshot before every change, so you can undo the change in the editor (using CTRL + Z)
//在每次更改前生成一个快照，顺便你也可以回退在编辑器中的更改(Ctrl+Z)
this.handler.history.saveSnapshot(this.handler.history.createSnapshot());
//Now set the new value to the item instance
//现在捏，给项实例设置新值。
i.someField = callback;
}
}
});
//Set the current value as default text of the text input popup
//设置现有的值为文本输入框的默认文本。
if (i.someField != null) {
pop.setText(i.someField);
}
//Open the popup
PopupHandler.displayPopup(pop);
});
someFieldButton.setDescription("This is just an example button tooltip.");
//Add the button to the right-click context menu content
//添加按钮到右键菜单内容中。
this.rightclickMenu.addContent(someFieldButton);
}
serializeItem()
简单但也重要，第二个重要方法在保存布局时被调用。
在这里，你的项实例(对象字段)被序列化为SimplePropertiesSection以将其属性保存在布局文件中。
你只关心（你自己）你的自定义项的值就行。每一项的基本的长宽高坐标部分啥的都默认添加到了序列化实例中。
@Override
public SimplePropertiesSection serializeItem() {
ExampleCustomizationItem i = ((ExampleCustomizationItem)this.object);
SimplePropertiesSection sec = new SimplePropertiesSection();
//Add your custom item values here, so they get saved and can later be de-serialized again.
//在这添加你的自定义项的值，以至于它们被保存后可以再次反序列化。
sec.addEntry("saved_property", i.someField);
return sec;
}
完整样例
这里是LayoutEditorElement的完整样例。
package de.keksuccino.fancymenu.api.item.example;
import de.keksuccino.fancymenu.api.item.LayoutEditorElement;
import de.keksuccino.fancymenu.menu.fancy.helper.DynamicValueInputPopup;
import de.keksuccino.fancymenu.menu.fancy.helper.layoutcreator.LayoutEditorScreen;
import de.keksuccino.fancymenu.menu.fancy.helper.ui.popup.FMTextInputPopup;
import de.keksuccino.konkrete.gui.content.AdvancedButton;
import de.keksuccino.konkrete.gui.screens.popup.PopupHandler;
import de.keksuccino.konkrete.rendering.RenderUtils;
import java.awt.*;
public class ExampleLayoutEditorElement extends LayoutEditorElement {
public ExampleLayoutEditorElement(ExampleCustomizationItemContainer parentContainer, ExampleCustomizationItem customizationItemInstance, LayoutEditorScreen handler) {
super(parentContainer, customizationItemInstance, true, handler, true);
}
@Override
public void init() {
//The superclass adds basic stuff to the right-click context menu, like visibility requirement controls, delete controls, orientation, etc.
//这里的超类为右键菜单添加了些基础功能，比如可视化需求控件，删除控件，方向等。
super.init();
//The 'object' field holds the CustomizationItem instance of this element.
//"object"字段包含这个元素的CustomizationItem实例。
//Cast it to your own item class, to get and set your own fields.
//把他转换成你自己的项类，以便于获取/设置你自己的字段。
ExampleCustomizationItem i = ((ExampleCustomizationItem)this.object);
//This button will be part of the right-click context menu of the element and is uses to change the background color value of the item.
//这个按钮将成为元素右键菜单的一部分，用于更改项的背景颜色值。
AdvancedButton backgroundColorButton = new AdvancedButton(0, 0, 0, 0, "Background Color", (press) -> {
//This is the basic input popup for text content, used in many parts of FancyMenu.
//这是文本内容的基本输入弹出框，在FancyMenu的很多部分都有使用。
FMTextInputPopup pop = new FMTextInputPopup(new Color(0, 0, 0, 0), "Background Color HEX", null, 240, (callback) -> {
//The callback of popups will be null, when pressing ESC in it to force-close it.
//当按下ESC强制关闭窗口时，窗口回调值为空。
if (callback != null) {
if (!callback.equals(i.backgroundColorString)) {
Color c = RenderUtils.getColorFromHexString(callback);
if (c != null) {
//Create a snapshot before every change, so you can undo the change in the editor (using CTRL + Z)
//在每次更改前生成一个快照，顺便你也可以回退在编辑器中的更改(Ctrl+Z)
this.handler.history.saveSnapshot(this.handler.history.createSnapshot());
//Now set the new values to the item instance
//现在捏，给项实例设置新值。
i.backgroundColorString = callback;
i.backgroundColor = c;
}
}
}
});
//Set the current value as default text of the text input popup
//设置现有的值为文本输入框的默认文本。
if (i.backgroundColorString != null) {
pop.setText(i.backgroundColorString);
}
//Open the popup
//打开弹出框。
PopupHandler.displayPopup(pop);
});
backgroundColorButton.setDescription("This is just an example button tooltip.");
//Add the button to the right-click context menu content
//添加按钮到右键菜单内容中。
this.rightclickMenu.addContent(backgroundColorButton);
//This is the button to change the display text of the item. Will also be part of the right-click context menu.
//这个是更改项显示的文本的按钮，也会成为右键菜单的一部分。
AdvancedButton displayTextButton = new AdvancedButton(0, 0, 0, 0, "Display Text", (press) -> {
//This is also a text input popup, but with placeholder text value support (the little icon at the right side of the input field)
//这也是文本弹出框，但是支持占位符文本值。
DynamicValueInputPopup pop = new DynamicValueInputPopup(new Color(0, 0, 0, 0), "Set Display Text", null, 240, (callback) -> {
if (callback != null) {
if (!callback.equals(i.displayText)) {
//Again, save a snapshot before changing something!
//再来一次，在改变之前保存快照。
this.handler.history.saveSnapshot(this.handler.history.createSnapshot());
//Setting the new display text value
//设置新的显示文本值。
i.displayText = callback;
}
}
});
if (i.displayText != null) {
pop.setText(i.displayText);
}
PopupHandler.displayPopup(pop);
});
this.rightclickMenu.addContent(displayTextButton);
}
@Override
public SimplePropertiesSection serializeItem() {
ExampleCustomizationItem i = ((ExampleCustomizationItem)this.object);
SimplePropertiesSection sec = new SimplePropertiesSection();
//Add your custom item values here, so they get saved and can later be de-serialized again.
sec.addEntry("background_color", i.backgroundColorString);
sec.addEntry("display_text", i.displayText);
return sec;
}
}
创建Container
我们需要的最后的类是CustomizationItemContainer的子类。
这个容器是CustomizationItems和LayoutEditorElements的基础实例Builder。
给你的项创建CustomizationItemContainer子类并起合适的名字。
接下来，我会将我的示例容器类命名为ExampleCustomizationItemContainer。
Item Identifier
项容器的构造方法需要唯一的标识符。(像是sfz)
至于怎么让你的标识符唯一，我也不赘述了。
你应该在子类构造方法里直接设置标识符。
public ExampleCustomizationItemContainer() {
super("example_item_identifier");
}
Instance Builders
项容器用于构建你的CustomizationItem子类和LayoutEditorElement子类的实例。
你需要设置Builder的方法，以便容器可以构建子类的实例。
//This will construct a default instance of your CustomizationItem without any customizations made to it.
//这里将会构造一个你的CustomizationItem默认实例，而且不对其进行任何自定义。
@Override
public CustomizationItem constructDefaultItemInstance() {
//Just use an empty properties section here.
//这里只是用了空属性section。
//Make sure that your CustomizationItem accepts empty sections without throwing errors!
//请确保你的CustomizationItem能接受空section还不报错。
ExampleCustomizationItem i = new ExampleCustomizationItem(this, new PropertiesSection("dummy"));
//The default size of 10x10 would be a bit too small for the item, so I set a new default size of 100x100 to the default instance.
//默认10*10的大小可能对于项来说有点过小了，所以我把10*10拉到了100*100。
//This means that now every new item of this type will have a size of 100x100 by default.
//就是说，咱现在所有这类型的新项默认大小都是100*100了。
i.width = 100;
i.height = 100;
return i;
}
//This will construct a customized instance of your CustomizationItem, using the given PropertiesSection (serialized item) to set all customizations.
//这将构造您的CustomizationItem 的自定义实例，使用给定的PropertiesSection（序列化项）来设置所有自定义项。
@Override
public CustomizationItem constructCustomizedItemInstance(PropertiesSection serializedItem) {
return new ExampleCustomizationItem(this, serializedItem);
}
//This will construct a new instance of your LayoutEditorElement, used in the layout editor.
//这里将会为你的LayoutEditorElement构建用在布局编辑器的实例。
@Override
public LayoutEditorElement constructEditorElementInstance(CustomizationItem item, LayoutEditorScreen handler) {
return new ExampleLayoutEditorElement(this, (ExampleCustomizationItem) item, handler);
}
Display Name
你应该为你的项设置显示名称。
这个显示名会用在布局编辑器中。
这个方法允许你填入本地化键作为显示名称。
@Override
public String getDisplayName() {
return "Example Item";
}
描述
将鼠标悬停在按钮上以在布局编辑器中添加此类型的新项时，会显示项的描述。
@Override
public String[] getDescription() {
return new String[] {
"This is a description",
"with 2 lines of text."
};
}
完整示例
这里是CustomizationItemContainer的一个完整样例。
package de.keksuccino.fancymenu.api.item.example;
import de.keksuccino.fancymenu.api.item.CustomizationItem;
import de.keksuccino.fancymenu.api.item.CustomizationItemContainer;
import de.keksuccino.fancymenu.api.item.LayoutEditorElement;
import de.keksuccino.fancymenu.menu.fancy.helper.layoutcreator.LayoutEditorScreen;
import de.keksuccino.konkrete.properties.PropertiesSection;
//This needs to be registered to the CustomizationItemRegistry at mod init
//在模组初始化这里需要被注册到CustomizationItemRegistry。
public class ExampleCustomizationItemContainer extends CustomizationItemContainer {
public ExampleCustomizationItemContainer() {
super("example_item_identifier");
}
@Override
public CustomizationItem constructDefaultItemInstance() {
ExampleCustomizationItem i = new ExampleCustomizationItem(this, new PropertiesSection("dummy"));
//The default size of 10x10 would be a bit too small for the item, so I set a new default size of 100x100 to the default instance.
//默认10*10的大小可能对于项来说有点过小了，所以我把10*10拉到了100*100。
//This means that now every new item of this type will have a size of 100x100 by default.
//就是说，咱现在所有这类型的新项默认大小都是100*100了。
i.width = 100;
i.height = 100;
return i;
}
@Override
public CustomizationItem constructCustomizedItemInstance(PropertiesSection serializedItem) {
return new ExampleCustomizationItem(this, serializedItem);
}
@Override
public LayoutEditorElement constructEditorElementInstance(CustomizationItem item, LayoutEditorScreen handler) {
return new ExampleLayoutEditorElement(this, (ExampleCustomizationItem) item, handler);
}
@Override
public String getDisplayName() {
return "Example Item";
}
@Override
public String[] getDescription() {
return new String[] {
"This is a description",
"with 2 lines of text."
};
}
}
注册Container
你就快完成了，嗯...最后一步，人类的一大步。
FancyMenu需要认识你的自定义项，所以你需要让你的拓展模组初始化时注册你的CustomizationItemContainer到CustomizationItemRegistery。
package de.keksuccino.fancymenu;
import net.minecraftforge.fml.common.Mod;
import de.keksuccino.fancymenu.api.item.CustomizationItemRegistry;
@Mod("modid")
public class ExampleModMainClass {
public ExampleModMainClass() {
try {
//Register your CustomizationItemContainer to the CustomizationItemRegistry at mod init.
//初始化时注册你的CustomizationItemContainer到CustomizationItemRegistery。
CustomizationItemRegistry.registerItem(new ExampleCustomizationItemContainer());
} catch (Exception e) {
e.printStackTrace();
}
}
}
现在你可以使用你自己的布局元素了！