星火 2.0 开发文档

主题

GameUI.Device ​

DeviceInfo 仅客户端 ​

命名空间 GameUI.Device

csharp
public class DeviceInfo

构造函数 ​

DeviceInfo 仅客户端 ​

csharp
public DeviceInfo()

属性 ​

Platform 仅客户端 ​

csharp
public static Platform Platform { get; }

PrimaryViewport 仅客户端 ​

csharp
public static ScreenViewport PrimaryViewport { get; }

PrimaryInputManager 仅客户端 ​

csharp
public static InputManager PrimaryInputManager { get; }

InputManager 仅客户端 ​

命名空间 GameUI.Device

csharp
public class InputManager : IGameClass

属性 ​

Primary 仅客户端 ​

csharp
public static InputManager Primary { get; }

PointerType 仅客户端 ​

csharp
public PointerType PointerType { get; }

Gets the type of pointer input currently in use.

方法 ​

OnRegisterGameClass 仅客户端 ​

csharp
public static void OnRegisterGameClass()

事件 ​

OnKeyDown 仅客户端 ​

csharp
public event Action<EventGameKeyDown>? OnKeyDown

OnKeyUp 仅客户端 ​

csharp
public event Action<EventGameKeyUp>? OnKeyUp

OnPointerButtonDown 仅客户端 ​

csharp
public event Action<EventGamePointerButtonDown>? OnPointerButtonDown

OnPointerButtonUp 仅客户端 ​

csharp
public event Action<EventGamePointerButtonUp>? OnPointerButtonUp

OnPointerButtonMove 仅客户端 ​

csharp
public event Action<EventGamePointerButtonMove>? OnPointerButtonMove

OnPointerWheelChanged 仅客户端 ​

csharp
public event Action<EventGamePointerWheelChanged>? OnPointerWheelChanged

ScreenViewport 仅客户端 ​

命名空间 GameUI.Device

csharp
public class ScreenViewport : IGameClass

属性 ​

Primary 仅客户端 ​

csharp
public static ScreenViewport Primary { get; }

Main 仅客户端 ​

csharp
public static ScreenViewport Main { get; }

The main screen viewport. Alias for Primary.

Camera 仅客户端 ​

csharp
public Camera Camera { get; }

WidthPx 仅客户端 ​

csharp
public int WidthPx { get; }

In device pixels

HeightPx 仅客户端 ​

csharp
public int HeightPx { get; }

In device pixels

DesignResolutionLandscape 仅客户端 ​

csharp
public SizeF DesignResolutionLandscape { get; }

横屏设计分辨率（宽 > 高）。默认 1920x1080 (16:9)。 可通过 ScaleMode) 修改。

DesignResolutionPortrait 仅客户端 ​

csharp
public SizeF DesignResolutionPortrait { get; }

竖屏设计分辨率（高 > 宽）。默认 1080x1920 (9:16)。 可通过 ScaleMode) 修改。

ScaleMode 仅客户端 ​

csharp
public ScaleMode ScaleMode { get; }

当前使用的缩放策略。默认 Contain。 通过 ScaleMode) 修改。

Size 仅客户端 ​

csharp
public SizeF Size { get; }

视口的实际可见尺寸（设计坐标系）。在非标准宽高比的屏幕上会与 DesignResolution 不同： Contain: Size >= DesignResolution（多出的空间可用于布局扩展） Cover/CoverCentered: Size <= DesignResolution（超出屏幕的部分被裁切） MatchWidth: Width 相等，Height 可能不同 MatchHeight: Height 相等，Width 可能不同

DesignResolution 仅客户端 ​

csharp
public SizeF DesignResolution { get; }

当前屏幕方向对应的设计分辨率基准值。这是 UI 坐标系的参考尺寸， 在所有 ScaleMode 下都保证至少这么大的区域可见（Contain）或被填满（Cover）。 实际可见区域请用 Size。

DevicePixelRatio 仅客户端 ​

csharp
public float DevicePixelRatio { get; }

DisplayOrientations 仅客户端 ​

csharp
public DisplayOrientations DisplayOrientations { get; }

SafeZonePadding 仅客户端 ​

csharp
public Thickness SafeZonePadding { get; }

In device independent pixels

NativeSafeZonePadding 仅客户端 ​

csharp
public Thickness NativeSafeZonePadding { get; }

系统提供的实际安全区，单位为当前渲染像素，不受模拟覆盖影响。

GlobalOffsetPx 仅客户端 ​

csharp
public (int X, int Y) GlobalOffsetPx { get; }

CoverCentered 模式下 root 元素的像素偏移量。其他模式下为 (0, 0)。

SceneRendering 仅客户端 ​

csharp
public bool SceneRendering { get; set; }

Gets or sets a value indicating whether scene rendering is enabled.

备注

Setting this property to false will lock the scene render in the view, make it static.

GaussianBlurLevel 仅客户端 ​

csharp
public uint? GaussianBlurLevel { get; set; }

SaturationInput 仅客户端 ​

csharp
public float? SaturationInput { get; set; }

MultiplyInput 仅客户端 ​

csharp
public Color? MultiplyInput { get; set; }

方法 ​

SetDesignResolution 仅客户端 ​

csharp
public void SetDesignResolution(float width, float height, ScaleMode scaleMode = ScaleMode.Contain)

设置自定义的设计分辨率和缩放策略。传入的宽高会自动规范化： 较大值作为横屏宽度，较小值作为横屏高度，竖屏则反转。 设置后会立即重新计算 DevicePixelRatio 并触发相关事件。

  • width — 设计宽度
  • height — 设计高度
  • scaleMode — 缩放策略，默认 Contain

SetSafeZoneSimulation 仅客户端 ​

csharp
public void SetSafeZoneSimulation(Thickness? pixelInsets)

本局安全区模拟，单位为渲染像素。传 null 恢复系统值；尺寸变化后仍使用指定像素边距。

GetPointerInputPosition 仅客户端 ​

csharp
public UIPosition? GetPointerInputPosition(PointerButtons buttonIndex)

GetPointerInputPositionPx 仅客户端 ​

csharp
public (int? left, int? top) GetPointerInputPositionPx(PointerButtons button)

In device pixels

  • button —

返回：

OnRegisterGameClass 仅客户端 ​

csharp
public static void OnRegisterGameClass()

CreateDebugDraw 仅客户端 ​

csharp
public IDebugDraw? CreateDebugDraw()

RaycastWorldPanel 仅客户端 ​

csharp
public RaycastHitWorldPosition RaycastWorldPanel(UIPosition position, WorldPanel panel, float fixedAxisValue = 0f)

Performs a raycast on a specified world panel at a given UI position and fixed axis value.

  • position — The UI position, in logical pixels, where the raycast should be performed.
  • panel — The world panel to raycast against. This can be one of the following: XY, XZ, or YZ.
  • fixedAxisValue — The fixed axis value to use for the raycast. For example, if the panel is XY, this value represents the Z-coordinate.

返回： A RaycastHitWorldPosition object containing the result of the raycast. If the raycast hits the panel, the Position property will contain the world position of the hit, and IsHit will be true. Otherwise, IsHit will be false.

备注

This method calculates the screen position in device-dependent pixels (DPI) based on the provided UI position and performs a raycast on the specified world panel (XY, XZ, or YZ). The raycast determines whether the panel is hit and, if so, returns the world position of the hit.

RaycastWorldPanelPx 仅客户端 ​

csharp
public RaycastHitWorldPosition RaycastWorldPanelPx(float x, float y, WorldPanel panel, float fixedAxisValue = 0f)

Performs a raycast on a specified world panel at given screen coordinates and a fixed axis value.

  • x — The horizontal screen coordinate in device-dependent pixels.
  • y — The vertical screen coordinate in device-dependent pixels.
  • panel — The world panel to raycast against. This can be one of the following: XY, XZ, or YZ.
  • fixedAxisValue — The fixed axis value to use for the raycast. For example, if the panel is XY, this value represents the Z-coordinate.

返回： A RaycastHitWorldPosition object containing the result of the raycast. If the raycast hits the panel, the Position property will contain the world position of the hit, and IsHit will be true. Otherwise, IsHit will be false.

备注

This method directly operates on device-dependent coordinates to perform a raycast on the specified world panel (XY, XZ, or YZ). The raycast determines whether the panel is hit and, if so, returns the world position of the hit.

RaycastWorldToUI 仅客户端 ​

csharp
public RaycastHitUIPosition RaycastWorldToUI(ScenePoint scenePoint)

Converts a world position to a corresponding UI position and determines if the conversion is valid.

  • scenePoint — The world position represented as a ScenePoint to be converted to a UI position.

返回： A RaycastHitUIPosition object containing the converted UI position and a flag indicating whether the conversion was successful. If the conversion is invalid, the returned RaycastHitUIPosition will have IsHit set to false.

备注

The method maps a 3D world position to a 2D screen position and then to a UI position.

RaycastWorldToScreenPx 仅客户端 ​

csharp
public (bool success, float x, float y) RaycastWorldToScreenPx(ScenePoint scenePoint)

Converts a world position to a screen position in device dependent pixels.

  • scenePoint — The world position, represented as a ScenePoint, to be converted to screen coordinates.

返回： A tuple containing the result of the conversion: successtrue if the conversion was successful; otherwise, false. x The X-coordinate of the screen position.
y The Y-coordinate of the screen position.

备注

The method returns false for success if the world position cannot be mapped to a valid screen position.

RaycastWorldSpace 仅客户端 ​

csharp
public RaycastHitWorld RaycastWorldSpace(ScenePoint origin, Vector3 direction, float rayLength, RayCastMode mode = RayCastMode.AABB)

Performs a raycast in world space from a specified origin point in a given direction and length.

  • origin — The starting point of the ray in world space, represented as a ScenePoint.
  • direction — The direction of the ray, represented as a Vector3.
  • rayLength — The maximum length of the ray.
  • mode — The mode of the raycast, determining the type of collision detection to use. The default is AABB.

返回： A RaycastHitWorld object containing the result of the raycast. If the ray hits an object, the IsHit property will be true, and the Position and Normal properties will contain the hit position and surface normal, respectively. If no object is hit, IsHit will be false.

备注

This method casts a ray in the world space starting from the specified origin point, extending in the given direction for the specified length. It determines whether the ray intersects with any objects in the scene and, if so, provides details about the hit, including the hit position and surface normal.

RaycastTerrain 仅客户端 ​

csharp
public RaycastHitWorld RaycastTerrain(UIPosition position)

Performs a raycast on the terrain at the specified UI position.

  • position — The position on the UI, specified in logical pixels, where the raycast should be performed.

返回： A RaycastHitWorld object containing the result of the raycast, including information about the hit location and any intersected terrain features.

备注

The input position is automatically adjusted for the device's pixel density using the device pixel ratio.

RaycastTerrainOrWorldPanelXY 仅客户端 ​

csharp
public RaycastHitWorldPosition RaycastTerrainOrWorldPanelXY(UIPosition uiPosition, float zAxisValue = 0f)

Performs a raycast on the terrain or a world panel in the XY plane based on the specified UI position.

  • uiPosition — The UI position, in screen coordinates, used to determine the raycast origin.
  • zAxisValue — The Z-axis value to use when raycasting against the world panel. Defaults to 0f.

返回： A RaycastHitWorldPosition object containing the result of the raycast. If the raycast hits the terrain, the result includes the hit position. Otherwise, the result of the world panel raycast is returned.

备注

This method first attempts to perform a raycast against the terrain. If the terrain is hit, the resulting position is returned. If the terrain is not hit, the method performs a raycast against the world panel in the XY plane using the specified Z-axis value.

RaycastTerrainPx 仅客户端 ​

csharp
public RaycastHitWorld RaycastTerrainPx(float x, float y)

Retrieves the screen point for raycasting to terrain.

  • x — The x coordinate for the raycast.
  • y — The y coordinate for the raycast.

返回： A RaycastHitTerrain object containing the hit information.

RaycastActor 仅客户端 ​

csharp
public IEnumerable<IActor> RaycastActor(UIPosition position, RayCastMode mode = RayCastMode.AABB)

Retrieves actors at specified UIPosition using a raycast, optionally filtering results based on a condition.

  • position — The UI position, in device-independent pixels (DIPs), to perform the raycast operation.
  • mode — The mode of the raycast operation, determining the type of bounding box used for hit detection. The default is AABB, which provides the best compatibility for most game objects.

返回： An enumerable collection of IActor instances that are hit by the raycast at the specified position. The collection will be empty if no actors are hit.

备注

The is automatically scaled by the device pixel ratio to ensure accurate hit detection. ⚠️ 射线检测模式选择重要提示： 如果使用SimpleBoundingCylinder 或其他需要特定包围盒数据的模式， 请确保目标游戏对象的模型数据中已配置相应的包围盒。如果没有配置，射线检测将会失败。 配置位置：SimpleBoundingCylinder 数据需要在 SimpleBoundingCylinder 字段中配置。 建议：对于大多数游戏项目，使用默认的 AABB 模式， 因为它具有最好的兼容性且不需要特殊的模型配置。

RaycastActorPx 仅客户端 ​

csharp
public IEnumerable<IActor> RaycastActorPx(float x, float y, RayCastMode mode = RayCastMode.AABB)

Performs a raycast at specified screen coordinates and returns a collection of actors intersected by the ray, only works for model or particle actor that is not transient, and not destroyed or garbage collected. Entities and units are also included in the result.

  • x — Specifies the horizontal device-dependent coordinate for the raycast.
  • y — Specifies the vertical device-dependent coordinate for the raycast.
  • mode — Determines the method used for collision detection during the raycast. AABB is recommended for best compatibility.

返回： Yields a collection of actors that intersect with the raycast.

备注

⚠️ 射线检测模式选择重要提示： 某些射线检测模式（如 SimpleBoundingCylinder）需要游戏对象的模型数据中 预先配置相应的包围盒数据。如果模型没有配置这些数据，射线检测将会失败。 配置位置：SimpleBoundingCylinder 数据需要在 SimpleBoundingCylinder 字段中配置。 建议：对于大多数游戏项目，使用 AABB 模式 以获得最佳兼容性。

RaycastEntities 仅客户端 ​

csharp
public IEnumerable<Entity> RaycastEntities(UIPosition position, Func<Entity, bool>? filter = null, RayCastMode mode = RayCastMode.SimpleBoundingCylinder)

Retrieves entities at specified UIPosition using a raycast, optionally filtering results based on a condition.

  • position — Specifies the screen coordinates for the raycast, which are in device-independent pixels (DIPs).
  • filter — An optional function to determine which entities to include based on a condition.
  • mode — Defines the method of raycasting to be used for detecting entities. Note: The default SimpleBoundingCylinder requires model data configuration. Consider using AABB for better compatibility.

返回： An enumerable collection of entities that meet the specified criteria.

备注

⚠️ 重要注意事项： 默认使用 SimpleBoundingCylinder 模式，但这需要实体/单位的模型数据中 预先配置 SimpleBoundingCylinder 数据。如果模型没有配置这些数据，射线检测将会失败！ 配置位置：SimpleBoundingCylinder 数据需要在 SimpleBoundingCylinder 字段中配置。 建议：如果你的游戏项目中的单位模型没有配置 SimpleBoundingCylinder 数据， 请改用 AABB 模式以确保射线检测正常工作。

RaycastEntitiesPx 仅客户端 ​

csharp
public IEnumerable<Entity> RaycastEntitiesPx(float x, float y, Func<Entity, bool>? filter = null, RayCastMode mode = RayCastMode.SimpleBoundingCylinder)

Retrieves entities at specified screen coordinates using a raycast, optionally filtering results based on a condition.

  • x — Specifies the horizontal device-dependent screen coordinate for the raycast.
  • y — Specifies the vertical device-dependent screen coordinate for the raycast.
  • filter — An optional function to determine which entities to include based on a condition.
  • mode — Defines the method of raycasting to be used for detecting entities. Note: The default SimpleBoundingCylinder requires model data configuration. Consider using AABB for better compatibility.

返回： An enumerable collection of entities that meet the specified criteria.

备注

⚠️ 重要注意事项： 默认使用 SimpleBoundingCylinder 模式，但这需要实体/单位的模型数据中 预先配置 SimpleBoundingCylinder 数据。如果模型没有配置这些数据，射线检测将会失败！ 配置位置：SimpleBoundingCylinder 数据需要在 SimpleBoundingCylinder 字段中配置。 建议：如果你的游戏项目中的单位模型没有配置 SimpleBoundingCylinder 数据， 请改用 AABB 模式以确保射线检测正常工作。

事件 ​

OnSizeChanged 仅客户端 ​

csharp
public event Action<int, int>? OnSizeChanged

OnOrientationChanged 仅客户端 ​

csharp
public event Action<DisplayOrientations>? OnOrientationChanged

OnViewportChanged 仅客户端 ​

csharp
public event Action? OnViewportChanged

在屏幕尺寸、方向、设备像素比和安全区信息完成更新后触发。 订阅者应在回调中读取当前的 WidthPx, HeightPx, DisplayOrientations, DevicePixelRatio 和 SafeZonePadding。同尺寸的 Surface 重建也会触发此事件。 同尺寸 Surface 重建通知需要客户端能力版本 4；旧客户端仍保留实际尺寸变化的兼容路径。

OnDevicePixelRatioChanged 仅客户端 ​

csharp
public event Action<float>? OnDevicePixelRatioChanged

PointerType 仅客户端 ​

命名空间 GameUI.Device.Enum

csharp
public enum PointerType

表示指针输入设备的类型

枚举值 ​

  • Mouse — 鼠标指针输入
  • Touch — 触摸指针输入

RayCastMode 仅客户端 ​

命名空间 GameUI.Device.Enum

csharp
public enum RayCastMode

定义射线检测的碰撞检测模式

备注

⚠️ 重要提示： 不同的射线检测模式对游戏对象的模型数据有不同的要求。如果选择了需要特定包围盒数据的模式， 但游戏对象的模型没有配置相应的包围盒，射线检测将会失败。 配置位置：模型的包围盒数据需要在相应的 GameDataModel 字段中配置， 例如 GameDataModel.SimpleBoundingCylinder 字段用于配置简单包围圆柱体数据。 建议：对于大多数游戏，使用 AABB 模式是最安全的选择， 因为它不需要特殊的模型配置。

枚举值 ​

  • AABB — 轴对齐包围盒 (Axis-Aligned Bounding Box)
  • OBB — 有向包围盒 (Oriented Bounding Box)
  • Triangle — 三角形精确检测
  • TriangleUV — 三角形精确检测（包含UV坐标）
  • SimpleBoundingCylinder — 简单包围圆柱体

WorldPanel 仅客户端 ​

命名空间 GameUI.Device.Enum

csharp
public enum WorldPanel

枚举值 ​

  • XY
  • XZ
  • YZ

RaycastHitUIPosition 仅客户端 ​

命名空间 GameUI.Device.Struct

csharp
public struct RaycastHitUIPosition

属性 ​

UIPosition 仅客户端 ​

csharp
public UIPosition UIPosition { get; set; }

IsHit 仅客户端 ​

csharp
public bool IsHit { get; set; }

RaycastHitWorld 仅客户端 ​

命名空间 GameUI.Device.Struct

csharp
public struct RaycastHitWorld

属性 ​

Position 仅客户端 ​

csharp
public Vector3 Position { get; set; }

Normal 仅客户端 ​

csharp
public Vector3 Normal { get; set; }

IsHit 仅客户端 ​

csharp
public bool IsHit { get; set; }

RaycastHitWorldPosition 仅客户端 ​

命名空间 GameUI.Device.Struct

csharp
public struct RaycastHitWorldPosition

属性 ​

Position 仅客户端 ​

csharp
public Vector3 Position { get; set; }

IsHit 仅客户端 ​

csharp
public bool IsHit { get; set; }