hytale-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hytale UI & HUD

Hytale UI与HUD

Create custom user interfaces and HUD elements for your Hytale mods.

为你的Hytale模组创建自定义用户界面与HUD元素。

UI Framework

UI框架

Hytale uses NoesisGUI - a powerful XAML-based UI framework.

Hytale使用NoesisGUI——一个强大的基于XAML的UI框架。

UI Types

UI类型

Type	Use For	Examples
HUD	Always-on-screen	Health, mana, minimap
Overlay	Temporary display	Notifications, titles
Screen	Full interface	Inventory, menus
Dialog	Popups	Confirmations, NPC chat
Widget	Reusable components	Buttons, bars, icons

类型	适用场景	示例
HUD	始终显示在屏幕上	生命值、魔力值、小地图
Overlay（覆盖层）	临时显示内容	通知、标题
Screen（全屏界面）	完整界面	物品栏、菜单
Dialog（对话框）	弹窗	确认提示、NPC对话
Widget（组件）	可复用组件	按钮、进度条、图标

Folder Structure

文件夹结构

MyPack/
└── Common/
    └── UI/
        ├── hud/
        │   ├── my_hud.xaml
        │   └── my_hud.xaml.cs
        ├── screens/
        │   ├── custom_menu.xaml
        │   └── custom_inventory.xaml
        └── textures/
            ├── button_bg.png
            └── icons/

MyPack/
└── Common/
    └── UI/
        ├── hud/
        │   ├── my_hud.xaml
        │   └── my_hud.xaml.cs
        ├── screens/
        │   ├── custom_menu.xaml
        │   └── custom_inventory.xaml
        └── textures/
            ├── button_bg.png
            └── icons/

Basic HUD Element

基础HUD元素

XAML Definition

XAML定义

xml

<!-- my_hud.xaml -->
<UserControl 
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    
    <Grid HorizontalAlignment="Left" VerticalAlignment="Top" Margin="10">
        <!-- Mana Bar -->
        <Border Background="#333" CornerRadius="5" Padding="2">
            <Grid Width="200" Height="20">
                <Rectangle Fill="#224" RadiusX="3" RadiusY="3"/>
                <Rectangle x:Name="ManaFill" Fill="#48F" RadiusX="3" RadiusY="3"
                           HorizontalAlignment="Left" Width="150"/>
                <TextBlock Text="150/200" Foreground="White" 
                           HorizontalAlignment="Center" VerticalAlignment="Center"/>
            </Grid>
        </Border>
    </Grid>
</UserControl>

xml

<!-- my_hud.xaml -->
<UserControl 
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    
    <Grid HorizontalAlignment="Left" VerticalAlignment="Top" Margin="10">
        <!-- Mana Bar -->
        <Border Background="#333" CornerRadius="5" Padding="2">
            <Grid Width="200" Height="20">
                <Rectangle Fill="#224" RadiusX="3" RadiusY="3"/>
                <Rectangle x:Name="ManaFill" Fill="#48F" RadiusX="3" RadiusY="3"
                           HorizontalAlignment="Left" Width="150"/>
                <TextBlock Text="150/200" Foreground="White" 
                           HorizontalAlignment="Center" VerticalAlignment="Center"/>
            </Grid>
        </Border>
    </Grid>
</UserControl>

JSON Registration

JSON注册

json

{
  "hudId": "mymod:mana_bar",
  "xaml": "ui/hud/mana_bar.xaml",
  "position": "top-left",
  "offset": { "x": 10, "y": 50 }
}

json

{
  "hudId": "mymod:mana_bar",
  "xaml": "ui/hud/mana_bar.xaml",
  "position": "top-left",
  "offset": { "x": 10, "y": 50 }
}

HUD Positions

HUD位置

Position	Description
`top-left`	Upper left corner
`top-center`	Upper center
`top-right`	Upper right corner
`center`	Screen center
`bottom-left`	Lower left
`bottom-center`	Lower center
`bottom-right`	Lower right

位置	说明
`top-left`	左上角
`top-center`	顶部中央
`top-right`	右上角
`center`	屏幕中央
`bottom-left`	左下角
`bottom-center`	底部中央
`bottom-right`	右下角

Common UI Components

常用UI组件

Progress Bar

进度条

xml

<Grid Width="200" Height="20">
    <Rectangle Fill="#333" RadiusX="3" RadiusY="3"/>
    <Rectangle x:Name="ProgressFill" Fill="#4A4" RadiusX="3" RadiusY="3"
               HorizontalAlignment="Left" Width="{Binding Progress}"/>
    <TextBlock Text="{Binding ProgressText}" Foreground="White"
               HorizontalAlignment="Center" VerticalAlignment="Center"/>
</Grid>

xml

<Grid Width="200" Height="20">
    <Rectangle Fill="#333" RadiusX="3" RadiusY="3"/>
    <Rectangle x:Name="ProgressFill" Fill="#4A4" RadiusX="3" RadiusY="3"
               HorizontalAlignment="Left" Width="{Binding Progress}"/>
    <TextBlock Text="{Binding ProgressText}" Foreground="White"
               HorizontalAlignment="Center" VerticalAlignment="Center"/>
</Grid>

Icon Button

图标按钮

xml

<Button Width="48" Height="48" Style="{StaticResource IconButton}">
    <Image Source="textures/icons/sword.png" Width="32" Height="32"/>
</Button>

xml

<Button Width="48" Height="48" Style="{StaticResource IconButton}">
    <Image Source="textures/icons/sword.png" Width="32" Height="32"/>
</Button>

Tooltip

提示框

xml

<Border Background="#222" CornerRadius="5" Padding="10">
    <StackPanel>
        <TextBlock Text="{Binding ItemName}" FontWeight="Bold" Foreground="#FF0"/>
        <TextBlock Text="{Binding ItemDesc}" Foreground="#AAA" TextWrapping="Wrap"/>
    </StackPanel>
</Border>

xml

<Border Background="#222" CornerRadius="5" Padding="10">
    <StackPanel>
        <TextBlock Text="{Binding ItemName}" FontWeight="Bold" Foreground="#FF0"/>
        <TextBlock Text="{Binding ItemDesc}" Foreground="#AAA" TextWrapping="Wrap"/>
    </StackPanel>
</Border>

Custom Screens

自定义全屏界面

Menu Screen

菜单界面

xml

<UserControl>
    <Grid Background="#88000000">
        <Border Background="#333" CornerRadius="10" Padding="20"
                HorizontalAlignment="Center" VerticalAlignment="Center">
            <StackPanel Width="300">
                <TextBlock Text="My Custom Menu" FontSize="24" 
                           Foreground="White" HorizontalAlignment="Center"/>
                
                <Button Content="Option 1" Margin="0,20,0,0" Height="40"/>
                <Button Content="Option 2" Margin="0,10,0,0" Height="40"/>
                <Button Content="Close" Margin="0,20,0,0" Height="40"
                        Click="OnClose"/>
            </StackPanel>
        </Border>
    </Grid>
</UserControl>

xml

<UserControl>
    <Grid Background="#88000000">
        <Border Background="#333" CornerRadius="10" Padding="20"
                HorizontalAlignment="Center" VerticalAlignment="Center">
            <StackPanel Width="300">
                <TextBlock Text="My Custom Menu" FontSize="24" 
                           Foreground="White" HorizontalAlignment="Center"/>
                
                <Button Content="Option 1" Margin="0,20,0,0" Height="40"/>
                <Button Content="Option 2" Margin="0,10,0,0" Height="40"/>
                <Button Content="Close" Margin="0,20,0,0" Height="40"
                        Click="OnClose"/>
            </StackPanel>
        </Border>
    </Grid>
</UserControl>

Inventory Grid

物品栏网格

xml

<ItemsControl ItemsSource="{Binding InventorySlots}">
    <ItemsControl.ItemsPanel>
        <ItemsPanelTemplate>
            <UniformGrid Columns="9" Rows="4"/>
        </ItemsPanelTemplate>
    </ItemsControl.ItemsPanel>
    <ItemsControl.ItemTemplate>
        <DataTemplate>
            <Border Width="48" Height="48" Background="#444" 
                    BorderBrush="#666" BorderThickness="1" Margin="2">
                <Image Source="{Binding Icon}" Stretch="Uniform"/>
            </Border>
        </DataTemplate>
    </ItemsControl.ItemTemplate>
</ItemsControl>

xml

<ItemsControl ItemsSource="{Binding InventorySlots}">
    <ItemsControl.ItemsPanel>
        <ItemsPanelTemplate>
            <UniformGrid Columns="9" Rows="4"/>
        </ItemsPanelTemplate>
    </ItemsControl.ItemsPanel>
    <ItemsControl.ItemTemplate>
        <DataTemplate>
            <Border Width="48" Height="48" Background="#444" 
                    BorderBrush="#666" BorderThickness="1" Margin="2">
                <Image Source="{Binding Icon}" Stretch="Uniform"/>
            </Border>
        </DataTemplate>
    </ItemsControl.ItemTemplate>
</ItemsControl>

Plugin Integration

插件集成

Show/Hide HUD

显示/隐藏HUD

java

// Show custom HUD
player.showHUD("mymod:mana_bar");

// Hide HUD
player.hideHUD("mymod:mana_bar");

// Check if visible
boolean visible = player.isHUDVisible("mymod:mana_bar");

java

// Show custom HUD
player.showHUD("mymod:mana_bar");

// Hide HUD
player.hideHUD("mymod:mana_bar");

// Check if visible
boolean visible = player.isHUDVisible("mymod:mana_bar");

Update HUD Data

更新HUD数据

java

// Update bound data
player.setHUDData("mymod:mana_bar", "mana", currentMana);
player.setHUDData("mymod:mana_bar", "maxMana", maxMana);

// Or with object
ManaData data = new ManaData(currentMana, maxMana);
player.setHUDData("mymod:mana_bar", data);

java

// Update bound data
player.setHUDData("mymod:mana_bar", "mana", currentMana);
player.setHUDData("mymod:mana_bar", "maxMana", maxMana);

// Or with object
ManaData data = new ManaData(currentMana, maxMana);
player.setHUDData("mymod:mana_bar", data);

Open Screens

打开界面

java

// Open custom screen
player.openScreen("mymod:custom_menu");

// Open with data
player.openScreen("mymod:shop", shopInventory);

// Close current screen
player.closeScreen();

java

// Open custom screen
player.openScreen("mymod:custom_menu");

// Open with data
player.openScreen("mymod:shop", shopInventory);

// Close current screen
player.closeScreen();

Notifications

通知

java

// Show toast notification
player.showNotification("Achievement Unlocked!", 5.0f);

// Show title
player.showTitle("Boss Defeated!", "You earned 500 XP", 3.0f);

// Show action bar message
player.showActionBar("Press E to interact");

java

// Show toast notification
player.showNotification("Achievement Unlocked!", 5.0f);

// Show title
player.showTitle("Boss Defeated!", "You earned 500 XP", 3.0f);

// Show action bar message
player.showActionBar("Press E to interact");

Data Binding

数据绑定

ViewModel Pattern

视图模型模式

java

public class ManaViewModel {
    private int mana;
    private int maxMana;
    
    public int getMana() { return mana; }
    public void setMana(int value) {
        this.mana = value;
        notifyPropertyChanged("mana");
        notifyPropertyChanged("manaPercent");
    }
    
    public double getManaPercent() {
        return (double) mana / maxMana * 100;
    }
}

java

public class ManaViewModel {
    private int mana;
    private int maxMana;
    
    public int getMana() { return mana; }
    public void setMana(int value) {
        this.mana = value;
        notifyPropertyChanged("mana");
        notifyPropertyChanged("manaPercent");
    }
    
    public double getManaPercent() {
        return (double) mana / maxMana * 100;
    }
}

In XAML

在XAML中使用

xml

<Rectangle Width="{Binding ManaPercent, Converter={StaticResource PercentToWidth}}"/>
<TextBlock Text="{Binding Mana, StringFormat='{}{0} MP'}"/>

xml

<Rectangle Width="{Binding ManaPercent, Converter={StaticResource PercentToWidth}}"/>
<TextBlock Text="{Binding Mana, StringFormat='{}{0} MP'}"/>

Styling

样式定制

Custom Button Style

自定义按钮样式

xml

<Style x:Key="GameButton" TargetType="Button">
    <Setter Property="Background" Value="#444"/>
    <Setter Property="Foreground" Value="White"/>
    <Setter Property="BorderBrush" Value="#666"/>
    <Setter Property="BorderThickness" Value="2"/>
    <Setter Property="Padding" Value="15,8"/>
    <Setter Property="FontSize" Value="14"/>
    <Style.Triggers>
        <Trigger Property="IsMouseOver" Value="True">
            <Setter Property="Background" Value="#555"/>
            <Setter Property="BorderBrush" Value="#888"/>
        </Trigger>
        <Trigger Property="IsPressed" Value="True">
            <Setter Property="Background" Value="#333"/>
        </Trigger>
    </Style.Triggers>
</Style>

xml

<Style x:Key="GameButton" TargetType="Button">
    <Setter Property="Background" Value="#444"/>
    <Setter Property="Foreground" Value="White"/>
    <Setter Property="BorderBrush" Value="#666"/>
    <Setter Property="BorderThickness" Value="2"/>
    <Setter Property="Padding" Value="15,8"/>
    <Setter Property="FontSize" Value="14"/>
    <Style.Triggers>
        <Trigger Property="IsMouseOver" Value="True">
            <Setter Property="Background" Value="#555"/>
            <Setter Property="BorderBrush" Value="#888"/>
        </Trigger>
        <Trigger Property="IsPressed" Value="True">
            <Setter Property="Background" Value="#333"/>
        </Trigger>
    </Style.Triggers>
</Style>

Color Palette

调色板

xml

<Color x:Key="PrimaryColor">#4A90D9</Color>
<Color x:Key="SecondaryColor">#2ECC71</Color>
<Color x:Key="DangerColor">#E74C3C</Color>
<Color x:Key="BackgroundColor">#2C3E50</Color>
<Color x:Key="TextColor">#ECF0F1</Color>

xml

<Color x:Key="PrimaryColor">#4A90D9</Color>
<Color x:Key="SecondaryColor">#2ECC71</Color>
<Color x:Key="DangerColor">#E74C3C</Color>
<Color x:Key="BackgroundColor">#2C3E50</Color>
<Color x:Key="TextColor">#ECF0F1</Color>

Best Practices

最佳实践

Do

Practice	Why
Use data binding	Automatic updates
Consistent styling	Professional look
Test all resolutions	Accessibility
Provide feedback	User understands

实践	原因
使用数据绑定	自动更新内容
保持样式一致	呈现专业外观
测试所有分辨率	提升可访问性
提供操作反馈	让用户清晰了解状态

Don't

避免做法

Mistake	Why Bad
Too many HUDs	Screen clutter
Tiny text	Hard to read
No close button	Frustrating
Block gameplay	Annoying

错误做法	弊端
HUD数量过多	造成屏幕杂乱
文字过小	难以阅读
无关闭按钮	引起用户不满
遮挡游戏内容	影响游戏体验

Quick Reference

快速参考

Task	How
Create HUD	Define XAML + register JSON
Show HUD	`player.showHUD("id")`
Update data	`player.setHUDData(...)`
Open screen	`player.openScreen("id")`
Show notification	`player.showNotification(...)`

任务	实现方式
创建HUD	定义XAML + 注册JSON
显示HUD	`player.showHUD("id")`
更新数据	`player.setHUDData(...)`
打开界面	`player.openScreen("id")`
显示通知	`player.showNotification(...)`

Resources

资源

NoesisGUI Docs: noesisengine.com
Plugin Development: See
```
hytale-plugin-dev
```
skill
NPC Dialogue: See
```
hytale-npc-ai
```
skill

NoesisGUI文档：noesisengine.com
插件开发：参考
```
hytale-plugin-dev
```
技能
NPC对话：参考
```
hytale-npc-ai
```
技能

hytale-ui

Original

Translation

Hytale UI & HUD

Hytale UI与HUD

UI Framework

UI框架

UI Types

UI类型

Folder Structure

文件夹结构

Basic HUD Element

基础HUD元素

XAML Definition

XAML定义

JSON Registration

JSON注册

HUD Positions

HUD位置

Common UI Components

常用UI组件

Progress Bar

进度条

Icon Button

图标按钮

Tooltip

提示框

Custom Screens

自定义全屏界面

Menu Screen

菜单界面

Inventory Grid

物品栏网格

Plugin Integration

插件集成

Show/Hide HUD

显示/隐藏HUD

Update HUD Data

更新HUD数据

Open Screens

打开界面

Notifications

通知

Data Binding

数据绑定

ViewModel Pattern

视图模型模式

In XAML

在XAML中使用

Styling

样式定制

Custom Button Style

自定义按钮样式

Color Palette

调色板

Best Practices

最佳实践

Do

推荐做法

Don't

避免做法

Quick Reference

快速参考

Resources

资源