xray16 1.3.4 → 1.5.0

package/types/xr_ai/xr_graph.d.ts

@@ -1,47 +1,135 @@
-declare module "xray16" {
-  /**
-   * @source C++ class GameGraph__CVertex
-   * @customConstructor GameGraph__CVertex
-   * @group xr_graph
-   */
-  export class GameGraph__CVertex extends EngineBinding {
-    protected constructor();
-
-    public level_vertex_id(): u32;
-
-    public level_id(): u8;
-
-    public game_point(): vector;
-
-    public level_point(): vector;
-  }
-
-  /**
-   * @source C++ class CGameGraph
-   * @customConstructor CGameGraph
-   * @group xr_graph
-   */
-  export class CGameGraph {
-    public valid_vertex_id(value: u32): boolean;
-
-    public vertex(vertexId: u32): GameGraph__CVertex;
-
-    public vertex_id(graph: CGameGraph): u16;
-
-    public accessible(value: u32): boolean;
-
-    public accessible(value1: u32, value2: boolean): void;
-
-    /**
-     * Method to iterate over game levels registered in `all.spawn`.
-     *
-     * @returns level abstract object with every iteration
-     */
-    public levels(): LuaIterable<cse_abstract>;
-  }
-
-  /**
-   * @group xr_graph
-   */
-  export function game_graph(this: void): CGameGraph;
-}
+declare module "xray16" {
+  /**
+   * Game graph vertex binding.
+   *
+   * @source C++ class GameGraph__CVertex
+   * @customConstructor GameGraph__CVertex
+   * @group xr_graph
+   *
+   * @remarks
+   * Engine-owned descriptor returned by {@link CGameGraph.vertex}. Keep it as a short-lived view of graph data,
+   * not as persistent game state.
+   */
+  export class GameGraph__CVertex extends EngineBinding {
+    /**
+     * Engine-created game-graph vertex descriptor.
+     */
+    protected constructor();
+
+    /**
+     * Get the level-graph vertex this game-graph point maps to.
+     *
+     * @returns Level vertex id inside the owning level.
+     */
+    public level_vertex_id(): u32;
+
+    /**
+     * Get the id of the level that owns this graph point.
+     *
+     * @returns Level id.
+     */
+    public level_id(): u8;
+
+    /**
+     * Get this point position in global game space.
+     *
+     * @returns Game-space position.
+     */
+    public game_point(): vector;
+
+    /**
+     * Get this point position in its level.
+     *
+     * @returns Level-space position.
+     */
+    public level_point(): vector;
+  }
+
+  /**
+   * Game graph access binding.
+   *
+   * @source C++ class CGameGraph
+   * @customConstructor CGameGraph
+   * @group xr_graph
+   *
+   * @remarks
+   * Represents the global AI game graph. Validate ids before resolving vertices, and restore accessibility changes
+   * when they are only needed temporarily.
+   */
+  export class CGameGraph {
+    /**
+     * Check whether a game-graph vertex id exists.
+     *
+     * @param vertexId - Game-graph vertex id.
+     * @returns Whether the id can be used with graph methods.
+     */
+    public valid_vertex_id(vertexId: u32): boolean;
+
+    /**
+     * Get a game-graph vertex by id.
+     *
+     * @remarks
+     * Call {@link CGameGraph.valid_vertex_id} first. Native code expects a valid id and can fail hard on invalid
+     * graph references.
+     *
+     * @param vertexId - Game-graph vertex id.
+     * @returns Graph vertex descriptor.
+     */
+    public vertex(vertexId: u32): GameGraph__CVertex;
+
+    /**
+     * Resolve a graph vertex back to its id.
+     *
+     * @remarks
+     * Pass only vertices returned by this graph instance.
+     *
+     * @param vertex - Vertex returned by {@link CGameGraph.vertex}.
+     * @returns Game-graph vertex id.
+     */
+    public vertex_id(vertex: GameGraph__CVertex): u16;
+
+    /**
+     * Check whether a game-graph vertex can be used for AI travel.
+     *
+     * @remarks
+     * This is pathing accessibility, not whether the vertex exists.
+     *
+     * @param vertexId - Game-graph vertex id.
+     * @returns Whether the vertex is currently accessible.
+     */
+    public accessible(vertexId: u32): boolean;
+
+    /**
+     * Mark a game-graph vertex as accessible or blocked.
+     *
+     * @remarks
+     * Blocking vertices affects AI travel through the game graph. Prefer narrow, reversible changes.
+     *
+     * @param vertexId - Game-graph vertex id.
+     * @param value - New accessibility state.
+     */
+    public accessible(vertexId: u32, value: boolean): void;
+
+    /**
+     * Iterate over game levels registered in `all.spawn`.
+     *
+     * @remarks
+     * Iterates graph-level descriptors, not currently loaded level objects.
+     *
+     * @returns Level object on every iteration.
+     */
+    public levels(): LuaIterable<cse_abstract>;
+  }
+
+  /**
+   * Get the global game graph used by AI navigation.
+   *
+   * @group xr_graph
+   *
+   * @remarks
+   * Available after the engine has loaded AI graph data.
+   *
+   * @returns Game graph singleton.
+   */
+  export function game_graph(this: void): CGameGraph;
+}