GameCore.SceneSystem

ClientSceneLoadState 双端

命名空间 GameCore.SceneSystem

public enum ClientSceneLoadState

Describes the client-side loading state of a registered scene.

枚举值

• NotLoaded — The client has not started loading this scene.
• Loading — The client is currently loading this scene.
• Loaded — The client finished loading this scene successfully.
• Failed — The client failed to load this scene.

HostedSceneTag 双端

命名空间 GameCore.SceneSystem

public readonly struct HostedSceneTag

框架和引擎交互时用于标识场景的结构体。

构造函数

HostedSceneTag 双端

public HostedSceneTag(UTF8String sceneTag, UTF8String assetTemplate)

Initializes a new instance of the HostedSceneTag class with the specified scene tag and asset template.

• sceneTag — The unique identifier for the scene, represented as a UTF-8 string. This value cannot be null.
• assetTemplate — The template associated with the scene, represented as a UTF-8 string. This value cannot be null.

HostedSceneTag 双端

public HostedSceneTag(UTF8String sceneTag)

属性

IsTemplate 双端

public bool IsTemplate { get; }

AssetTemplate 双端

public UTF8String AssetTemplate { get; }

方法

ToString 双端

public override string ToString()

implicit operator 双端

public static HostedSceneTag implicit operator(UTF8String tag)

implicit operator 双端

public static HostedSceneTag implicit operator(string tag)

implicit operator 双端

public static HostedSceneTag implicit operator(ReadOnlySpan<byte> tag)

字段

SceneTag 双端

public readonly UTF8String SceneTag

场景在引擎中的唯一标识符，每个场景都应该有一个唯一的标识符。 但不同场景可以共享相同的场景素材文件（通过AssetTemplate字段）。

Scene 双端

命名空间 GameCore.SceneSystem

public class Scene : ISyncIdOwner, IEventSender, IGameClass

Represents a game scene that contains entities, effects, and provides spatial operations for game world management.

备注

Scene is a fundamental container for all game objects within a defined game world area. It manages entity lifecycle, spatial queries, pathfinding, and scene loading/unloading operations. Each scene has a unique identifier and can be loaded or unloaded dynamically based on game needs. Scenes support advanced spatial operations like circular, rectangular, and cone-based searches for entities, making them essential for AI, combat, and interaction systems. The scene system integrates with the engine's view layer for rendering and physics, while providing game-logic abstractions for entity management and spatial relationships.

属性

IsEngineFallback 双端

public bool IsEngineFallback { get; }

Gets a value indicating whether this is the engine-provided fallback scene.

备注

The engine fallback is exposed when the native runtime has not associated the player with a scene defined in the active game mode's SceneList. If a configured scene is later registered for the same identifier, the same instance becomes that configured scene and this property changes to false. While this property is true, the scene has no GameDataScene and does not indicate that the client has started or completed loading a map. It only provides a non-null scene context for actors that do not depend on map data, such as sound actors. Terrain, navigation, scene collision, placed objects, and other map-backed features are unavailable.

RenderScenery 仅客户端

public bool RenderScenery { get; set; }

Gets or sets whether to render the persistent visual content in the scene (terrain, decorations, etc.).

备注

When set to false, the scene's static environment elements such as terrain, buildings, and decorations will not be rendered. This does not affect dynamically created objects like units and actors, which are recreated each time the scene loads. Useful for debugging, performance optimization, or creating custom visual modes where only gameplay elements should be visible.

Local 仅客户端

public static Scene Local { get; }

Gets the local player's current scene.

返回： The scene that the local player is currently in.

备注

This is a convenience method that provides easy access to the local player's scene. It's equivalent to calling Player.LocalPlayer.Scene but provides a more direct and semantic way to access the local scene. When the native runtime has not associated the local player with a configured scene, this returns the IsEngineFallback scene.

AllScenes 双端

public static IEnumerable<Scene> AllScenes { get; }

IsLogicScene 双端

public bool IsLogicScene { get; }

Indicates whether this scene is a logic scene, which means it is created with the asset of another template scene

IsDynamicCopy 双端

public bool IsDynamicCopy { get; }

指示该场景是否为运行时动态创建的 SCE 场景副本。

TemplateSceneName 双端

public UTF8String? TemplateSceneName { get; }

场景使用的素材模板。静态数编场景来自 HostedSceneTag，动态副本来自创建时的源场景。

Size 双端

public Vector2 Size { get; }

Gets the size dimensions of this scene.

备注

The scene size determines the valid coordinate space for entities and operations within the scene. Size is cached for performance and retrieved from either the game data configuration or the view scene.

LoadState 仅客户端

public ClientSceneLoadState LoadState { get; }

Gets the latest client-side loading state reported for this scene.

Loaded 双端

public bool Loaded { get; }

Gets whether the client finished loading this scene successfully.

Link 双端

public IGameLink<GameDataScene>? Link { get; }

Gets the game data link that defines this scene's configuration.

Cache 双端

public GameDataScene? Cache { get; }

Gets the cached game data configuration for this scene.

SyncId 双端

public int SyncId { get; }

Gets the unique synchronization identifier for this scene.

Name 双端

public string? Name { get; set; }

Gets the name of this scene.

SyncIdType 双端

public static SyncIdType SyncIdType { get; }

Gets the synchronization ID type for scenes.

AggregatorWeakReference 双端

public WeakReference<EventAggregator> AggregatorWeakReference { get; }

PlacedObjectsCreated 仅服务端

public bool PlacedObjectsCreated { get; }

Asset 仅服务端

public UTF8String? Asset { get; }

DefaultScene 仅服务端

public static Scene? DefaultScene { get; }

方法

LoadDefaultClientOnly 仅客户端

public static bool LoadDefaultClientOnly(bool randomMap = false, bool asyncLoadingBlock = false)

Loads and switches to the current game mode's default scene in client-only mode.

• randomMap — Whether the native map loader should randomize the map.
• asyncLoadingBlock — Whether the native map loader should use async loading block mode.

返回： true if the native load request was accepted; otherwise, false.

备注

This method reads DefaultScene from the active game mode, then calls Boolean) on that scene. It is intended for client-only previews and local presentation tests.

LoadClientOnly 仅客户端

public static bool LoadClientOnly(IGameLink<GameDataScene> sceneLink, bool randomMap = false, bool asyncLoadingBlock = false)

Loads and switches to a game-data scene in client-only mode.

• sceneLink — The scene data link to load.
• randomMap — Whether the native map loader should randomize the map.
• asyncLoadingBlock — Whether the native map loader should use async loading block mode.

返回： true if the native load request was accepted; otherwise, false.

备注

This API is intended for pure client-side presentation flows. In normal client/server games, scene switching is server-authoritative and this method returns false.

LoadClientOnly 仅客户端

public bool LoadClientOnly(bool randomMap = false, bool asyncLoadingBlock = false)

Loads and switches to this game-data scene in client-only mode.

• randomMap — Whether the native map loader should randomize the map.
• asyncLoadingBlock — Whether the native map loader should use async loading block mode.

返回： true if the native load request was accepted; otherwise, false.

备注

The scene's SceneTag becomes the native current scene, and AssetTemplate selects the map asset to load. Completion is reported through OnLoadEnd.

Get 双端

public static Scene? Get(ReadOnlySpan<byte> sceneName)

Retrieves a scene by its name.

• sceneName — The name of the scene as a byte span.

返回： The scene with the specified name, or null if not found.

GetOrCreate 双端

public static Scene GetOrCreate(ReadOnlySpan<byte> sceneName)

Retrieves an existing scene or creates a new one with the specified name.

• sceneName — The name of the scene as a byte span.

返回： The existing scene or a newly created scene with the specified name.

Get 双端

public static Scene? Get(int sceneHash)

Retrieves a scene by its hash identifier.

• sceneHash — The hash identifier of the scene.

返回： The scene with the specified hash, or null if not found.

GetOrCreate 双端

public static Scene GetOrCreate(int sceneHash, string? name = null)

Retrieves an existing scene or creates a new one with the specified hash and name.

• sceneHash — The hash identifier of the scene.
• name — The optional name for the scene if it needs to be created.

返回： The existing scene or a newly created scene with the specified parameters.

Get 双端

public static Scene? Get(IGameLink<GameDataScene> link)

Retrieves a scene by its game data link.

• link — The game data link for the scene.

返回： The scene associated with the data link, or null if not found.

GetOrCreate 双端

public static Scene GetOrCreate(IGameLink<GameDataScene> link)

Retrieves an existing scene or creates a new one from the specified game data link.

• link — The game data link for the scene.

返回： The existing scene or a newly created scene from the data link.

GetHashCode 双端

public override int GetHashCode()

ToString 双端

public override string ToString()

Returns a string representation of this scene.

返回： The scene name or sync ID as a string.

EnsureStaticMeshColliders 双端

public SceneColliderLoadResult EnsureStaticMeshColliders()

Ensures the loaded Volumetric3D scene has its static mesh colliders attached to the authoritative physics world.

GetEntity 双端

public Entity? GetEntity(int entityId)

Gets an entity in this scene by its synchronization id.

GetUnit 双端

public Unit? GetUnit(int unitId)

Gets a unit in this scene by its synchronization id.

GetEntities 双端

public IEnumerable<Entity> GetEntities(Func<Entity, bool>? filter = null)

Gets all entities in this scene, optionally filtered by a predicate.

• filter — An optional filter function to apply to entities.

返回： An enumerable collection of entities that match the filter criteria.

备注

This method provides access to all entities in the scene with optional filtering. It's useful for systems that need to process specific types of entities or entities meeting certain criteria without spatial constraints.

GetMorphs 双端

public IEnumerable<TMorph> GetMorphs<TMorph>(Func<Entity, TMorph?> morph) where TMorph : notnull

Gets entities in this scene transformed through a morph function, filtering out null results.

• morph — A function that transforms entities to the desired type or returns null.

返回： An enumerable collection of successfully transformed entities.

备注

This method is useful for type-safe entity processing where you want to extract specific types or aspects of entities. For example, getting all units, or all entities with a specific component type.

SearchCircle 双端

public IEnumerable<Entity>? SearchCircle(ScenePoint center, float radius, Func<Entity, bool>? filter = null)

Searches for entities within a circular area around a center point.

• center — The center point of the search circle.
• radius — The radius of the search circle.
• filter — An optional filter to apply to found entities.

返回： An enumerable collection of entities within the search area, or null if no entities are found.

备注

This method performs efficient spatial queries using the engine's optimized search algorithms. It's commonly used for area-of-effect abilities, proximity detection, and AI awareness systems.

SearchCircle 双端

public IEnumerable<TMorph>? SearchCircle<TMorph>(ScenePoint center, float radius, Func<Entity, TMorph?> morph) where TMorph : notnull

SearchRectangle 双端

public IEnumerable<Entity>? SearchRectangle(ScenePoint position, Angle facing, float width, float height, Func<Entity, bool>? filter = null)

Searches for entities within a rectangular area centered at the specified position.

• position — The center position of the rectangle.
• facing — The facing direction that determines rectangle orientation.
• width — The width of the rectangle (perpendicular to facing direction).
• height — The height of the rectangle (along facing direction).
• filter — An optional filter to apply to found entities.

返回： An enumerable collection of entities within the search area, or null if no entities are found.

备注

This method treats position as the true center of the rectangle. The rectangle extends equally in all directions from this center point, oriented by the facing direction. Useful for centered area effects, area selection tools, or symmetric area queries.

SearchRectangle 双端

public IEnumerable<TMorph>? SearchRectangle<TMorph>(ScenePoint position, Angle facing, float width, float height, Func<Entity, TMorph?> morph) where TMorph : notnull

SearchLine 双端

public IEnumerable<Entity>? SearchLine(ScenePoint position, Angle facing, float width, float length, Func<Entity, bool>? filter = null)

Searches for entities within a line-shaped rectangular area extending forward from the specified position.

• position — The base center position from which the line extends forward.
• facing — The facing direction that determines the line's direction.
• width — The width of the line (perpendicular to facing direction).
• length — The length of the line (along facing direction).
• filter — An optional filter to apply to found entities.

返回： An enumerable collection of entities within the search area, or null if no entities are found.

备注

This method creates a rectangular search area that extends forward from the position, similar to Boolean}) but with a rectangular shape instead of a cone. The position represents the center of the base edge, and the rectangle extends in the facing direction. This is useful for directional line attacks, beam weapons, charge paths, or forward-facing area effects.

SearchLine 双端

public IEnumerable<TMorph>? SearchLine<TMorph>(ScenePoint position, Angle facing, float width, float length, Func<Entity, TMorph?> morph) where TMorph : notnull

SearchCone 双端

public IEnumerable<Entity>? SearchCone(ScenePoint position, Angle facing, float radius, Angle centralAngle, Func<Entity, bool>? filter = null)

Searches for entities within a cone-shaped area.

• position — The apex position of the cone.
• facing — The central direction of the cone.
• radius — The maximum distance from the apex.
• centralAngle — The total angle of the cone spread.
• filter — An optional filter to apply to found entities.

返回： An enumerable collection of entities within the search area, or null if no entities are found.

备注

Cone searches are perfect for implementing vision cones, spell effects with directional spread, or weapon attacks with angular coverage. The cone extends from the position in the facing direction.

SearchCone 双端

public IEnumerable<TMorph>? SearchCone<TMorph>(ScenePoint position, Angle facing, float radius, Angle centralAngle, Func<Entity, TMorph?> morph) where TMorph : notnull

GetPlacedUnit 双端

public PlacedUnit? GetPlacedUnit(int placeId)

Retrieves a placed unit configuration by its placement identifier.

• placeId — The unique identifier of the placed unit.

返回： The placed unit configuration, or null if not found.

备注

Placed units are predefined entity configurations stored in the scene data that can be instantiated at specific locations. This method accesses the placement definitions.

GetPlacedItem 双端

public PlacedItem? GetPlacedItem(int placeId)

Retrieves a placed item configuration by its placement identifier.

• placeId — The unique identifier of the placed item.

返回： The placed item configuration, or null if not found.

备注

Placed items are predefined item configurations stored in the scene data that can be instantiated at specific locations. This method accesses the placement definitions.

GetPlacedLine 双端

public PlacedLine? GetPlacedLine(int placeId)

GetPlacedPoint 双端

public PlacedPoint? GetPlacedPoint(int placeId)

GetPlacedRegionCircle 双端

public PlacedRegionCircle? GetPlacedRegionCircle(int placeId)

GetPlacedRegionRectangle 双端

public PlacedRegionRectangle? GetPlacedRegionRectangle(int placeId)

Publish 双端

public virtual void Publish<TEvent>(TEvent eventToPublish)

GetPublisher 双端

public Action<TEvent>? GetPublisher<TEvent>()

OnRegisterGameClass 双端

public static void OnRegisterGameClass()

CreateCopy 仅服务端

public static Scene CreateCopy(Scene template, string? sceneName = null)

基于一个已注册场景创建动态 SCE 场景副本。

• template — 源场景；若源场景本身是副本，将使用其原始素材模板。
• sceneName — 副本名。省略时由框架生成不重复名称。

返回： 已注册的动态场景副本。

CreateCopy 仅服务端

public static Scene CreateCopy(IGameLink<GameDataScene> template, string? sceneName = null)

基于数编场景 Link 创建动态 SCE 场景副本。

CreateCopy 仅服务端

public static Scene CreateCopy(GameDataScene template, string? sceneName = null)

基于数编场景数据对象创建动态 SCE 场景副本。

CreateCopy 仅服务端

public Scene CreateCopy(string? sceneName = null)

基于当前场景创建动态 SCE 场景副本。

Load 仅服务端

public bool Load()

Loads this scene and all its content.

返回： True if the scene was successfully loaded; otherwise, false.

备注

This method initiates the scene loading process, which includes loading the underlying view scene and triggering all associated loading events and placed object creation.

EnsureTerrainCollider 仅服务端

public SceneColliderLoadResult EnsureTerrainCollider()

Ensures the loaded scene has its native heightfield terrain collider attached to the authoritative physics world.

TryFindPlacementPoint 仅服务端

public ScenePlacementPointResult TryFindPlacementPoint(ScenePoint center, float collisionRadius, float radius, bool ignoreUnit, out ScenePoint point)

Finds a nearby valid placement point for the supplied center position.

TryFindNearestWalkablePoint 仅服务端

public ScenePlacementPointResult TryFindNearestWalkablePoint(ScenePoint center, float radius, out ScenePoint point, float collisionRadius = 0f, bool ignoreUnit = true)

Finds the nearest walkable point around a requested position.

TryFindSpawnablePoint 仅服务端

public ScenePlacementPointResult TryFindSpawnablePoint(ScenePoint center, float collisionRadius, float radius, out ScenePoint point, bool ignoreUnit = false)

Finds a valid spawn point around a requested position.

Unload 仅服务端

public bool Unload()

Unloads this scene and cleans up all its content.

返回： True if the scene was successfully unloaded; otherwise, false.

备注

This method destroys all entities and effect persists in the scene, then unloads the underlying view scene. It ensures proper cleanup of all scene resources.

事件

OnLoadStart 双端

public event Action? OnLoadStart

Occurs when the scene starts loading.

备注

This event is fired at the beginning of the scene loading process, before any entities or placed objects are created. It's useful for systems that need to prepare for scene content.

OnLoadEnd 双端

public event Action? OnLoadEnd

Occurs when the scene finishes loading.

备注

This event is fired after the scene and all its content have been fully loaded and initialized. It indicates that the scene is ready for gameplay and all placed objects are available.

OnReplicated 仅客户端

public event Action? OnReplicated

动态场景副本完成客户端复制时触发。

OnLoadPlacedObjects 仅服务端

public event Action? OnLoadPlacedObjects

ScenePoint 双端

命名空间 GameCore.SceneSystem

public struct ScenePoint : ITarget, ICommandTarget, IScenePoint, IApproachableTarget, IActorScopeContext

Represents a three-dimensional point within a specific game scene, implementing targeting and positioning interfaces.

备注

ScenePoint is a fundamental structure for representing positions in the game world. It combines 3D coordinates with a scene reference, ensuring that all position operations are scene-aware. The structure implements ITarget to participate in the targeting system and provides comprehensive spatial operations including distance calculations, angle computations, and coordinate transformations. ScenePoint supports pathfinding integration on the server side and ground height queries on the client side. It serves as the primary position representation throughout the game systems for entities, effects, and spatial queries.

构造函数

ScenePoint 双端

public ScenePoint(Vector2 point, Scene scene)

Initializes a new ScenePoint with the specified 2D coordinates and scene.

• point — The 2D position in the scene.
• scene — The scene that contains this point.

ScenePoint 双端

public ScenePoint(Vector3 point, Scene scene)

Initializes a new ScenePoint with the specified 3D coordinates and scene.

• point — The 3D position in the scene. Format: Vector3(x, y, z) where XY is ground position and Z is height.
• scene — The scene that contains this point.

备注

⚠️ Coordinate System: This framework uses Z-axis as height axis.

• X and Y represent ground plane coordinates
• Z represents height/elevation (jumping axis) The Z coordinate is extracted and stored separately while X and Y are used for the 2D vector.

ScenePoint 双端

public ScenePoint(float x, float y, Scene scene)

Initializes a new ScenePoint with the specified X, Y coordinates and scene.

• x — The X coordinate in the scene.
• y — The Y coordinate in the scene.
• scene — The scene that contains this point.

ScenePoint 双端

public ScenePoint(IScenePoint scenePoint)

Initializes a new ScenePoint by copying from another scene point interface.

• scenePoint — The scene point to copy from.

ScenePoint 双端

public ScenePoint(ScenePoint scenePoint)

属性

X 双端

public float X { get; init; }

Gets the X coordinate of this point.

Y 双端

public float Y { get; init; }

Gets the Y coordinate of this point.

Z 双端

public float Z { get; set; }

Gets or sets the Z coordinate (height) of this point.

备注

⚠️ Important: Z-axis is the height axis in this framework. Use this for jumping, flying, falling, and vertical positioning.

Vector 双端

public readonly Vector2 Vector { get; }

Gets the 2D vector representation of this point.

Vector3 双端

public readonly Vector3 Vector3 { get; }

Gets the 3D vector representation of this point.

Constrained 双端

public readonly ScenePoint Constrained { get; }

Gets a constrained version of this point that is clamped within the scene boundaries.

备注

This property ensures that the coordinates are within the valid range of the scene, preventing out-of-bounds positions. The X and Y coordinates are clamped to [0, Size-1].

ApproachableTarget 双端

public readonly IApproachableTarget ApproachableTarget { get; }

Gets the approachable target interface for this scene point.

方法

operator + 双端

public static ScenePoint operator +(ScenePoint x, ScenePoint? y)

Adds two scene points together, combining their coordinates.

• x — The first scene point.
• y — The second scene point, or null.

返回： A new scene point with combined coordinates.

备注

If y is null, returns x unchanged. Otherwise, both points must be in the same scene. The resulting point has the sum of coordinates and Z values.

GetGroundHeight 仅客户端

public readonly float GetGroundHeight()

Gets the ground height at this scene point's X and Y coordinates.

返回： The ground height at this position.

备注

This method queries the client-side terrain system to determine the ground height at the specified coordinates. It's useful for positioning objects on terrain surfaces and for visual effects that need to align with the ground.

Distance 双端

public readonly float Distance(ScenePoint otherPoint)

Calculates the 3D distance to another scene point.

• otherPoint — The other scene point to calculate distance to.

返回： The 3D distance between points, or float.MaxValue if in different scenes.

备注

This method calculates the Euclidean distance in 3D space including the Z coordinate. Points in different scenes are considered infinitely far apart.

Distance2D 双端

public readonly float? Distance2D(ScenePoint otherPoint)

Calculates the 2D distance to another scene point (ignoring Z coordinate).

• otherPoint — The other scene point to calculate distance to.

返回： The 2D distance between points, or null if in different scenes.

备注

This method calculates the Euclidean distance using only X and Y coordinates, which is useful for ground-based movement and area calculations.

Distance2DSquared 双端

public readonly float? Distance2DSquared(ScenePoint otherPoint)

Calculates the squared 2D distance to another scene point for performance optimization.

• otherPoint — The other scene point to calculate distance to.

返回： The squared 2D distance between points, or null if in different scenes.

备注

Squared distance is computationally cheaper as it avoids the square root operation. This is useful for distance comparisons where the actual distance value isn't needed.

Offset 双端

public readonly ScenePoint Offset(Vector2 offset)

Creates a new scene point offset by the specified 2D vector.

• offset — The 2D offset to apply.

返回： A new scene point with the applied offset.

备注

This method creates a new instance with modified X and Y coordinates. The Z coordinate and scene reference remain unchanged.

Offset 双端

public readonly ScenePoint Offset(float x, float y)

Creates a new scene point offset by the specified X and Y amounts.

• x — The X offset to apply.
• y — The Y offset to apply.

返回： A new scene point with the applied offset.

Lerp 双端

public readonly ScenePoint Lerp(ScenePoint target, float amount)

Creates a new scene point interpolated between this point and a target point.

• target — The target scene point to interpolate towards.
• amount — The interpolation factor between 0.0 and 1.0.

返回： A new scene point at the interpolated position.

备注

Linear interpolation creates smooth movement between two points. An amount of 0.0 returns this point, 1.0 returns the target, and 0.5 returns the midpoint.

PolarTo 双端

public readonly ScenePoint PolarTo(Angle angle, double distance)

Creates a new scene point at the specified angle and distance from this point.

• angle — The angle to move in.
• distance — The distance to move.

返回： A new scene point at the calculated position.

备注

This method uses polar coordinates to calculate a new position relative to this point. If distance is zero, returns this point unchanged. The calculation is performed in 2D space.

PolarToRadian 双端

public readonly ScenePoint PolarToRadian(double radian, double distance)

Creates a new scene point at the specified radian angle and distance from this point.

• radian — The angle in radians to move in.
• distance — The distance to move.

返回： A new scene point at the calculated position.

备注

This method performs the polar coordinate calculation using radian angle representation for precise mathematical operations. It's used internally by the Angle-based method.

AngleTo 双端

public readonly Angle? AngleTo(ScenePoint target)

Calculates the angle from this point to the target point.

• target — The target scene point to calculate angle to.

返回： The angle to the target, or null if points are identical or in different scenes.

备注

The angle is calculated using the arctangent of the Y and X coordinate differences. If the points are at the same position, no meaningful angle can be calculated.

Equals 双端

public override readonly bool Equals(object? obj)

GetHashCode 双端

public override readonly int GetHashCode()

ToString 双端

public override readonly string ToString()

Returns a string representation of this scene point.

返回： A formatted string containing coordinates and scene information.

SameScene 双端

public readonly bool SameScene(ITarget target)

CanBeSeen 双端

public readonly bool CanBeSeen(Entity caster)

GetStaticCollisionMask 双端

public readonly StaticCollisionMask GetStaticCollisionMask(bool checkDynamicApplied)

Gets the static collision mask at this scene point.

• checkDynamicApplied — Whether to include runtime dynamic collision changes when supported.

返回： The collision mask at this point.

备注

This method preserves the point's X/Y/Z coordinates and is the preferred collision-mask query for gameplay code. In 3D scenes, querying by X/Y only may test the wrong height layer.

IsBlocked 双端

public readonly bool IsBlocked()

Determines whether this point is blocked for ground movement.

返回： true if the point is unwalkable; otherwise, false.

备注

In 3D scenes this uses the point's full X/Y/Z position. Server gameplay code that needs a corrected spawn or nearest walkable point should use the placement helper APIs instead of probing a blocked point directly.

operator + 双端

public static ScenePoint operator +(ScenePoint point, Vector2 offset)

Adds a 2D vector offset to a scene point.

• point — The scene point to offset.
• offset — The 2D offset vector to add.

返回： A new scene point with the applied offset.

operator == 双端

public static bool operator ==(ScenePoint left, ScenePoint right)

Compares two scene points for equality.

• left — The first scene point to compare.
• right — The second scene point to compare.

返回： True if the scene points are equal; otherwise, false.

operator != 双端

public static bool operator !=(ScenePoint left, ScenePoint right)

Compares two scene points for inequality.

• left — The first scene point to compare.
• right — The second scene point to compare.

返回： True if the scene points are not equal; otherwise, false.

SearchInRange 双端

public readonly IEnumerable<Entity>? SearchInRange(float range, Func<Entity, bool>? filter = null)

Searches for entities within the specified range of this scene point.

• range — The search radius around this point.
• filter — An optional filter to apply to found entities.

返回： An enumerable of entities within range, or null if the scene is invalid or no entities are found.

备注

This method provides a convenient way to perform circular area searches centered on this point. It delegates to the scene's search functionality with proper error handling.

SearchInRange 双端

public readonly IEnumerable<TMorph>? SearchInRange<TMorph>(float range, Func<Entity, TMorph?> morph) where TMorph : notnull

Searches for entities within the specified range and transforms them using a morph function.

• range — The search radius around this point.
• morph — A function that transforms entities to the desired type or returns null.

返回： An enumerable of transformed entities within range, or null if the scene is invalid or no entities are found.

备注

This method combines spatial searching with type transformation, providing a convenient way to find and process specific types of entities within a given area.

PathWayPointsTo 仅服务端

public readonly IEnumerable<ScenePoint>? PathWayPointsTo(ScenePoint end)

Calculates the pathway points from this scene point to the specified destination for ground unit pathfinding.

• end — The destination scene point to calculate the path to.

返回： An enumerable of scene points representing the pathway, or null if no path exists or scenes differ.

备注

This method returns pathway points only if the current scene and the destination scene are identical. If the scenes differ, the method returns null. If no pathway can be found, the method also returns null. The pathfinding is optimized for ground units and considers terrain obstacles and navigation constraints.

PathDistance 仅服务端

public readonly float? PathDistance(ScenePoint end)

Calculates the total path distance from this point to the destination using pathfinding. Unlike ScenePoint) which gives straight-line distance, this follows the actual navigable path around obstacles.

• end — The destination scene point.

返回： The total path distance, or null if no path exists or scenes differ.

TryFindNearestWalkablePoint 仅服务端

public readonly ScenePlacementPointResult TryFindNearestWalkablePoint(float radius, out ScenePoint point, float collisionRadius = 0f, bool ignoreUnit = true)

Finds the nearest walkable point around this position.

TryFindSpawnablePoint 仅服务端

public readonly ScenePlacementPointResult TryFindSpawnablePoint(float collisionRadius, float radius, out ScenePoint point, bool ignoreUnit = false)

Finds a valid spawn point around this position.

CanBeSeen 仅服务端

public readonly bool CanBeSeen(Player player)

Determines whether this scene point can be seen by the specified player.

• player — The player to check visibility for.

返回： True if the point is visible to the player; otherwise, false.

备注

This method checks server-side visibility rules including fog of war and vision systems.

事件

OnPositionChangingStart 仅服务端

public event Action<ITarget>? OnPositionChangingStart

Occurs when position changing starts (not applicable for scene points).

备注

Scene points don't change position, so this event is never fired. The event handlers are implemented as no-ops for interface compliance.

OnPositionChangingEnd 仅服务端

public event Action<ITarget>? OnPositionChangingEnd

Occurs when position changing ends (not applicable for scene points).

备注

Scene points don't change position, so this event is never fired. The event handlers are implemented as no-ops for interface compliance.

字段

Scene 双端

public Scene Scene

Gets the scene that contains this point.

ScenePointContext 双端

命名空间 GameCore.SceneSystem

public struct ScenePointContext : IActorEndPointContext

Represents a context for a scene point, including the scene point itself and a flag indicating whether to use the ground's Z coordinate.

构造函数

ScenePointContext 双端

public ScenePointContext(ScenePoint scenePoint, bool offsetByGroundZ)

Represents a context for a scene point, including the scene point itself and a flag indicating whether to use the ground's Z coordinate.

属性

ScenePoint 双端

public ScenePoint ScenePoint { get; set; }

OffsetByGroundZ 双端

public bool OffsetByGroundZ { get; set; }

IsAbsoluteHeight 双端

public readonly bool IsAbsoluteHeight { get; }

WorldPosition 仅客户端

public ScenePoint WorldPosition { get; }

方法

ToScenePointWithGroundZOffset 仅客户端

public ScenePoint ToScenePointWithGroundZOffset()

ToScenePointWithAbsoluteHeight 仅客户端

public ScenePoint ToScenePointWithAbsoluteHeight()

AsLaunchSiteFor 仅客户端

public bool AsLaunchSiteFor(IActorDualEndPoints actor)

GameDataScene 双端

命名空间 GameCore.SceneSystem.Data

public class GameDataScene : GameDataCategory<GameDataScene>, IGameDataCategory<GameDataScene>, IGameData<GameDataScene>, IGameData

场景数据。定义场景尺寸、相机、地形与预放置对象。

构造函数

GameDataScene 双端

public GameDataScene(GameLink<GameDataScene, GameDataScene> link)

GameDataScene 双端

public GameDataScene(IGameLink<GameDataScene> link)

属性

HostedSceneTag 双端

public required HostedSceneTag HostedSceneTag { get; set; }

场景资产标识。多场景可共用同一资产。由地形编辑器生成，不可在代码中创建。

Size 双端

public Vector2 Size { get; set; }

场景尺寸（世界单位）。离散瓦片地形按瓦片网格边界表达，连续高度场地形按实际 heightmap 覆盖范围表达；两者都必须与地形资产一致。

DefaultCamera 双端

public IGameLink<GameDataCamera> DefaultCamera { get; set; }

场景默认相机。客户端加载场景时使用此相机渲染。

RenderScenery 双端

public bool RenderScenery { get; set; }

是否渲染地形、装饰等静态环境。设为 false 时仅显示游戏对象，不渲染地形建筑，用于调试或性能优化。

SpaceModel 双端

public SceneSpaceModel SpaceModel { get; set; }

场景空间模型，决定本场景按 2.5D 单层地表还是真 3D 多层空间处理寻路、单位高度与碰撞。默认 2.5D 地表；Surface2D 不是无高度的 2D 场景，SCE 场景仍可包含地形高度和 Z 坐标。

NavigationBake 双端

public SceneNavigationBakeConfig? NavigationBake { get; set; }

场景导航网格的显式烘焙尺寸。为 null 时，编辑器沿用已有 map.nav 导航产物中的历史配置； 如果场景尚无 map.nav，使用 SceneNavigationBakeConfig 的默认值：半径 60、 高度 200、最大可跨越高度 90、最大坡度 45 度。修改后需要重新生成场景导航产物。

TerrainModel 双端

public SceneTerrainModel TerrainModel { get; set; }

场景地形模型，决定地表几何/高度数据按离散瓦片还是连续高度场表达。 与 SpaceModel 正交；不会把 map.acmap 的内部 MapVersion 暴露给用户。 旧场景缺少该字段时，编辑器从已加载 map.acmap 推断，显式保存时再回填。

EnableRuntimeTerrainTextureEditing 双端

public bool EnableRuntimeTerrainTextureEditing { get; set; }

启用离散瓦片地形的运行时地表纹理编辑。默认关闭；开启后客户端保留纹理权重及地形重建数据，供运行时修改纹理索引和混合权重。

备注

在场景加载前配置，加载后修改此值不会补回已释放的数据。增加客户端内存占用，数据随场景实例或显式场景缓存释放。不包含高度、拓扑编辑，也不自动同步或保存修改。需要支持此功能的客户端。

ContinuousTerrainConfiguredMaxHeight 双端

public float? ContinuousTerrainConfiguredMaxHeight { get; set; }

连续高度场 Landscape 的配置最大高度，对应地形目录 landscape.xml 的 MaxHeight。 该值用于 Landscape 配置、随机生成归一化以及水体/小地图材质参数，不会直接改写已有 heightmap 的几何高度；离散瓦片地形不使用此字段。

TerrainBoundaryCollisionWidth 双端

public Thickness? TerrainBoundaryCollisionWidth { get; set; }

地形边界静态碰撞宽度（世界单位，左/上/右/下）。由地形编辑器保存时同步；为 null 表示没有生成边界碰撞。

TerrainBoundaryCollisionWidthInTiles 双端

public int TerrainBoundaryCollisionWidthInTiles { get; set; }

地形边界静态碰撞宽度（地形瓦片层数）。用于追溯编辑器设置；0 表示没有生成边界碰撞。

TerrainEdgeStyle 双端

public SceneTerrainEdgeStyle TerrainEdgeStyle { get; set; }

地形边缘包边样式。该字段描述地形视觉/几何包边，不等同于相机 SceneBounds。

Vision 双端

public SceneVisionConfig? Vision { get; set; }

场景视野配置。按 scene 生效；未配置时使用地图或工程默认视野设置。

PlacedSceneShapes 双端

public QuickDictionary<int, PlacedSceneShape> PlacedSceneShapes { get; set; }

预放置的场景形状（线、点、区域等）。键为放置 ID。

PlacedPlayerObjects 双端

public QuickDictionary<int, PlacedPlayerObject> PlacedPlayerObjects { get; set; }

预放置的玩家对象（单位、物品等）。键为放置 ID。

方法

GetPlacedUnit 双端

public PlacedUnit? GetPlacedUnit(int id)

GetPlacedItem 双端

public PlacedItem? GetPlacedItem(int id)

字段

OnLoaded 双端

public Action<Scene>? OnLoaded

SceneNavigationBakeConfig 双端

命名空间 GameCore.SceneSystem.Data

public sealed class SceneNavigationBakeConfig

场景导航网格的烘焙尺寸。该配置描述本场景生成导航产物时采用的最小可通行角色， 不代表某个运行时单位独立的导航代理尺寸。新场景默认使用半径 60、 高度 200、最大可跨越高度 90、最大坡度 45 度。

构造函数

SceneNavigationBakeConfig 双端

public SceneNavigationBakeConfig()

属性

AgentRadius 双端

public float AgentRadius { get; set; }

最小可通行角色半径（世界单位）。

AgentHeight 双端

public float AgentHeight { get; set; }

最小可通行角色高度（世界单位）。

MaxClimb 双端

public float MaxClimb { get; set; }

角色可直接跨越的最大高度（世界单位）。

MaxSlope 双端

public float MaxSlope { get; set; }

可行走表面的最大坡度（角度）。

SceneSpaceModel 双端

命名空间 GameCore.SceneSystem.Data

public enum SceneSpaceModel

场景空间模型：决定寻路、单位高度与碰撞如何解释场景空间，不决定场景是否有 3D 高度或是否渲染 3D 资产。 Surface2D 表示 2.5D 单层可走面寻路；SCE 场景仍可有起伏地形、高台和 Z 高度。 Volumetric3D 才表示同一 XY 位置可存在多层可走面的真 3D 导航/碰撞。

枚举值

• Surface2D — 2.5D 单层地表寻路：导航在 XY 平面上按单层可走面处理，Z 仍表示场景高度/离地高度。它不是 2D 场景或无高度场景；适合平面、坡地、高台等单层地表，不支持同一 XY 的桥、隧道、上下叠层。
• Volumetric3D — 真 3D 体积多层：单位在三维空间中移动，坐标 Z 为真实世界高度。支持立体多层结构（如桥、隧道、上下楼层）。

SceneTerrainEdgeStyle 双端

命名空间 GameCore.SceneSystem.Data

public enum SceneTerrainEdgeStyle

地形边缘包边样式。用于记录地形编辑器的包边选择，不参与相机边界计算。

枚举值

• None — 无额外包边。
• CrackBorder — 使用地形裂隙包边。

SceneTerrainModel 双端

命名空间 GameCore.SceneSystem.Data

public enum SceneTerrainModel

场景地形模型：描述地表几何和高度数据如何存储、编辑，不决定导航/碰撞如何解释空间。

枚举值

• DiscreteTileTerrain — 离散瓦片地形：高度按瓦片顶点/层级表达，并受当前 TileSet 的局部拓扑约束。
• ContinuousHeightfieldTerrain — 连续高度场地形：高度由实际 heightmap 和采样间距表达。

IPlacedRegion 双端

命名空间 GameCore.SceneSystem.Data.Struct

public interface IPlacedRegion

属性

Region 双端

public Region Region { get; }

IsValid 双端

public bool IsValid { get; }

方法

Create 双端

void Create(Scene scene)

PlacedItem 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedItem : PlacedPlayerObject<GameDataItem>

构造函数

PlacedItem 双端

public PlacedItem()

属性

TriggerGetterInstance 双端

public Item? TriggerGetterInstance { get; set; }

The instance of the item placed in the scene. Ignore cloned scenes.

方法

ToString 双端

public override string? ToString()

Create 仅服务端

public override void Create(Scene scene)

PlacedItemReference 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedItemReference : PlacedObjectReference

构造函数

PlacedItemReference 双端

public PlacedItemReference()

属性

Item 双端

public Item? Item { get; }

PlacedItem 双端

public PlacedItem? PlacedItem { get; }

PlacedLine 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedLine : PlacedSceneShape

构造函数

PlacedLine 双端

public PlacedLine()

PlacedLine 双端

public PlacedLine(IEnumerable<Vector2> points)

属性

Points 双端

public required List<Vector2> Points { get; set; }

Line 双端

public SceneLine Line { get; set; }

The runtime scene line instance created from this placed line. This is lazily created when accessed through Int32).

IsValid 双端

public bool IsValid { get; set; }

方法

implicit operator 双端

public static List<Vector2> implicit operator(PlacedLine line)

implicit operator 双端

public static PlacedLine implicit operator(List<Vector2> points)

implicit operator 双端

public static PlacedLine implicit operator(Vector2[] points)

Create 双端

protected internal override void Create(Scene scene)

PlacedLineReference 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedLineReference : PlacedObjectReference

构造函数

PlacedLineReference 双端

public PlacedLineReference()

属性

Line 双端

public SceneLine? Line { get; }

PlacedLine 双端

public PlacedLine? PlacedLine { get; }

PlacedObject 双端

命名空间 GameCore.SceneSystem.Data.Struct

public abstract class PlacedObject

构造函数

PlacedObject 双端

protected PlacedObject()

属性

UniqueId 双端

public int UniqueId { get; set; }

HiddenInEditor 双端

public bool HiddenInEditor { get; set; }

LockedInEditor 双端

public bool LockedInEditor { get; set; }

Position 双端

public Vector3 Position { get; set; }

Facing 双端

public Angle? Facing { get; set; }

SyncedScale 双端

public float? SyncedScale { get; set; }

CustomTag 双端

public string? CustomTag { get; set; }

FolderTag 双端

public string? FolderTag { get; set; }

GroupTag 双端

public string? GroupTag { get; set; }

SyncedRandomIndex 双端

public int? SyncedRandomIndex { get; set; }

PlacedObjectReference 双端

命名空间 GameCore.SceneSystem.Data.Struct

public abstract class PlacedObjectReference

Represents a reference to an object that has been placed within a scene.

备注

This abstract base class provides common properties for referencing objects within a game scene. Derived types should specify additional details relevant to specific object types or placement scenarios.

构造函数

PlacedObjectReference 双端

protected PlacedObjectReference()

属性

SceneObject 双端

public Scene? SceneObject { get; }

Scene 双端

public required IGameLink<GameDataScene> Scene { get; set; }

UniqueId 双端

public int UniqueId { get; set; }

Gets or sets the unique identifier for the object.

PlacedPlayerObject 双端

命名空间 GameCore.SceneSystem.Data.Struct

public abstract class PlacedPlayerObject<TGameData> : PlacedPlayerObject where TGameData : IGameData<TGameData>

构造函数

PlacedPlayerObject 双端

protected PlacedPlayerObject()

属性

Link 双端

public required IGameLink<TGameData> Link { get; set; }

方法

ToString 双端

public override string? ToString()

PlacedPoint 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedPoint : PlacedSceneShape

构造函数

PlacedPoint 双端

public PlacedPoint()

PlacedPoint 双端

public PlacedPoint(Vector3 position)

属性

Point 双端

public ScenePoint Point { get; set; }

The runtime scene point instance created from this placed point. This is lazily created when accessed through Scene.GetPlacedPoint.

IsValid 双端

public bool IsValid { get; set; }

方法

implicit operator 双端

public static Vector3 implicit operator(PlacedPoint point)

implicit operator 双端

public static PlacedPoint implicit operator(Vector3 position)

Create 双端

protected internal override void Create(Scene scene)

PlacedPointReference 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedPointReference : PlacedObjectReference

构造函数

PlacedPointReference 双端

public PlacedPointReference()

属性

Point 双端

public ScenePoint Point { get; }

PlacedPoint 双端

public PlacedPoint? PlacedPoint { get; }

PlacedRegionCircle 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedRegionCircle : PlacedSceneShape, IPlacedRegion

构造函数

PlacedRegionCircle 双端

public PlacedRegionCircle()

PlacedRegionCircle 双端

public PlacedRegionCircle(Vector3 center, float radius)

属性

Center 双端

public Vector3 Center { get; set; }

Gets the center point of the circle.

Radius 双端

public float Radius { get; }

Gets the radius of the circle.

Region 双端

public RegionCircle Region { get; set; }

The runtime region instance created from this placed region. This is lazily created when accessed through Int32).

IsValid 双端

public bool IsValid { get; set; }

方法

Create 双端

protected internal override void Create(Scene scene)

PlacedRegionCircleReference 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedRegionCircleReference : PlacedObjectReference

构造函数

PlacedRegionCircleReference 双端

public PlacedRegionCircleReference()

属性

RegionCircle 双端

public RegionCircle? RegionCircle { get; }

PlacedRegionCircle 双端

public PlacedRegionCircle? PlacedRegionCircle { get; }

PlacedRegionRectangle 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedRegionRectangle : PlacedSceneShape, IPlacedRegion

构造函数

PlacedRegionRectangle 双端

public PlacedRegionRectangle()

PlacedRegionRectangle 双端

public PlacedRegionRectangle(Vector3 position, Vector2 size)

PlacedRegionRectangle 双端

public PlacedRegionRectangle(Vector3 position, float width, float height)

属性

Size 双端

public Vector2 Size { get; set; }

Gets the size of the rectangle as a Vector2 (X: width, Y: height).

Region 双端

public RegionRectangle Region { get; set; }

The runtime region instance created from this placed region. This is lazily created when accessed through Int32).

IsValid 双端

public bool IsValid { get; set; }

方法

Create 双端

protected internal override void Create(Scene scene)

PlacedRegionRectangleReference 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedRegionRectangleReference : PlacedObjectReference

构造函数

PlacedRegionRectangleReference 双端

public PlacedRegionRectangleReference()

属性

RegionRectangle 双端

public RegionRectangle? RegionRectangle { get; }

PlacedRegionRectangle 双端

public PlacedRegionRectangle? PlacedRegionRectangle { get; }

PlacedSceneShape 双端

命名空间 GameCore.SceneSystem.Data.Struct

public abstract class PlacedSceneShape : PlacedObject

构造函数

PlacedSceneShape 双端

protected PlacedSceneShape()

属性

TriggerGetter 双端

public bool TriggerGetter { get; set; }

是否被触发编辑器所使用。 触发编辑器只要获取了一次就为 true，不再重置。 为真时，在场景加载时，会自动创建对应的场景形状对象。

方法

Create 双端

protected internal abstract void Create(Scene scene)

Creates the runtime scene shape object from this placed shape configuration. This method is called lazily when the shape is first accessed through Scene.GetPlacedXXX methods. Since these are static configuration objects, this method works identically on both client and server.

• scene — The scene that contains this shape.

PlacedUnit 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedUnit : PlacedPlayerObject<GameDataUnit>

构造函数

PlacedUnit 双端

public PlacedUnit()

属性

IsMainUnit 双端

public bool IsMainUnit { get; set; }

UseDefaultAI 双端

public bool UseDefaultAI { get; set; }

CustomProperties 双端

public UnitPropertyInitialData? CustomProperties { get; set; }

TriggerGetterInstance 双端

public Unit? TriggerGetterInstance { get; set; }

The instance of the unit placed in the scene. Ignore cloned scenes.

方法

ToString 双端

public override string? ToString()

Create 仅服务端

public override void Create(Scene scene)

PlacedUnitReference 双端

命名空间 GameCore.SceneSystem.Data.Struct

public class PlacedUnitReference : PlacedObjectReference

构造函数

PlacedUnitReference 双端

public PlacedUnitReference()

属性

Unit 双端

public Unit? Unit { get; }

PlacedUnit 双端

public PlacedUnit? PlacedUnit { get; }

PropertySceneRuntime 双端

命名空间 GameCore.SceneSystem.Enum

public readonly struct PropertySceneRuntime : IGameClass, IExtendableEnum<PropertySceneRuntime>, IExtendableEnum, IExtendedEnum, ISyncIdOwner

方法

ToString 双端

public override string? ToString()

operator == 双端

public static bool operator ==(PropertySceneRuntime left, PropertySceneRuntime right)

operator != 双端

public static bool operator !=(PropertySceneRuntime left, PropertySceneRuntime right)

Equals 双端

public override bool Equals(object? obj)

GetHashCode 双端

public override int GetHashCode()

OnRegisterGameClass 双端

public static void OnRegisterGameClass()

字段

InnerValue 双端

public readonly System.Enum InnerValue

Kind 双端

public static readonly PropertySceneRuntime Kind

SceneHash 双端

public static readonly PropertySceneRuntime SceneHash

SceneName 双端

public static readonly PropertySceneRuntime SceneName

TemplateSceneName 双端

public static readonly PropertySceneRuntime TemplateSceneName

SourceSceneLinkHash 双端

public static readonly PropertySceneRuntime SourceSceneLinkHash