Clairvoyant

Graph Search Documentation

This documentation refers to the Graph Search problem. Your solution class will automatically extend GraphSearchSolution, and must override the following functions:

Your script should evaluate to the prototype of your defined class.

At present, your code is run as-is on your web client. Long-running or infinite loops will therefore crash your web client. Take appropriate actions to mitigate this issue when writing custom code.

c
class
GraphSearchSolution

f
function
constructor(graph : Graph)

The constructor of the GraphSearchSolution class provides the graph to you, you can use it to do preprocessing or simply store it as an instance variable.

f
function
solve(start : GraphNode, goal : GraphNode) : void

This will be called when you request a run of the algorithm. The function provides the start of the search and the target as parameters.

You can return success() or failure() as a shorthand.

f
function
success(debugValue : any = null) : void

This function declares the successful completion of the algorithm.

f
function
failure(debugValue : any = null) : void

This function declares the unsuccessful completion of the algorithm.

f
function
expand(node : GraphNode, debugValue : any = null) : void

This will mark a node as expanded in the graphical interface

f
function
visit(node : GraphNode, debugValue : any = null) : void

This will mark a node as visited in the graphical interface

f
function
log(debugValue : any = null) : void

This allows you to display some value without advancing the algorithm

f
function
highlight(components : GraphNode | GraphEdge[], debugValue : any = null) : void

This will highlight the given components in the graphical interface

f
function
alter(changes : ItemPropertySet[], debugValue : any = null) : void

This is an advanced way to interact with the properties of components

It allows you to alter any settable property of a component as part of the algorithm.

c
class
Graph
implements EditableComponent

f
function
*getAdjacentNodes(node : GraphNode) : Generator<GraphNode>

This allows you to iterate over all nodes which are accessible from one given node.

Note: if multiple traversable edges connect the nodes, the generator will generate duplicate entries.

f
function
*getAdjacentEdges(node : GraphNode, includeUntraversable : boolean = false) : Generator<GraphEdge>

This allows you to iterate over all edges that originate from a given node.

Note: if multiple traversable edges connect the nodes, the generator will generate duplicate entries, with potentially differing weights.

If includeUntraversable is set to true, the result will include edges (including virtual edges) which cannot be traversed.

f
function
*getIncomingNodes(node : GraphNode) : Generator<GraphNode>

Functions just like getAdjacentNodes, but uses reversed edges.

In practice, this means one obtains the nodes that can directly reach the given node, as opposed to the reciprocal case.

f
function
*getIncomingEdges(node : GraphNode, includeUntraversable : boolean = false) : Generator<GraphEdge>

Functions just like getAdjacentEdges, but uses reversed edges.

In practice, this means one obtains the edges whose target is the given node, as opposed to the source.

f
function
getNodeById(nodeId : string) : GraphNode | undefined

This allows you to get a reference to any node in the graph by its string ID.

f
function
getEdgeById(edgeId : number) : GraphEdge | undefined

This allows you to get a reference to any edge in the graph by its numeric ID.

f
function
getEdge(source : GraphNode, target : GraphNode, includeUntraversable : boolean = false) : GraphEdge | undefined

This function will return the first edge found that goes from the source to the target, and which is traversable (unless includeUntraversable is true).

If no such edge exists, it will return undefined instead.

f
function
*getEdges(source : GraphNode, target : GraphNode, includeUntraversable : boolean = false) : Generator<GraphEdge>

This function will yield all edges that go from the source to the target, and which are traversable (unless includeUntraversable is true).

f
function
getAllNodes() : GraphNode[]

This function returns all nodes in the graph.

f
function
getAllEdges() : GraphEdge[]

This function returns all edges in the graph, note that this includes edges which may be virtual or untraversable.

You can use the edge's isRef property or its traversable() function to check if it is a virtual edge or untraversable respectively.

c
class
GraphNode
implements EditableComponent

The Node is the most basic element in the graph, every node has an id which uniquely identifies it.

p
property
id : string

The unique identifier of this node in the graph.

p
property
graph : Graph

A reference to the graph that contains this node.

p
property
heuristic : Graph

This is either the automatically calculated heuristic based on x and y and its graph's goal node, or the one determined by data.h. Defaults to 0.

p
property
x : number

For grid graphs, the 0-indexed x coordinate of this node.

p
property
y : number

For grid graphs, the 0-indexed y coordinate of this node.

p
property
data : Record<string, any>

Arbitrary data stored in this node. Grid graphs guarantee a key named traversable, which is false only if the node is a wall in the grid graph.

You may use this field to store data in the graph. Note that it must be serializable, so you should avoid cyclical data.

Modifying some of these values may result in the graph being broken. Modify with caution.

c
class
GraphEdge
implements EditableComponent

Edges are slightly complicated, but very powerful! Edges always have a mirrored version which we will call a virtual edge.

Edges connect pairs of nodes. For bidirectional edges, both the regular and virtual edges are traversable. For directed edges, only the regular edge is traversable, but a virtual edge still exists! This can help you identify the in-degree of a node for directed graphs.

Edges provide a series of helpful properties and functions that should allow you to use them effectively.

p
property
id : number

A unique numeric ID for this edge. Read-only.

p
property
source : GraphNode

The source of this edge, that is, the node to which it adds an out-degree.

In the case of bidirectional edges, the source is arbitrary

In the case of flipped edges, the source and target are swapped.

p
property
target : GraphNode

The target of this edge, that is, the node to which it adds an in-degree.

In the case of bidirectional edges, the source is arbitrary

In the case of flipped edges, the source and target are swapped.

p
property
weight : number

The weight associated with this edge. For bidirectional edges, it is the same in both directions.

If you wish to simulate a bidirectional edge with different weights, use two directed edges instead. (Useful for case editing)

p
property
isBidirectional : boolean

Indicates whether this edge is bidirectional. Read-only.

p
property
isRef : boolean

Indicates whether this edge is virtual. Read-only.

p
property
data : Record<string, any>

Arbitrary data stored in this edge.

Notably, data stores some critical information about the edge, such as whether it is flipped.

You may use this field to store data in the graph. Note that it must be serializable, so you should avoid cyclical data. Use IDs to refer to nodes or edges..

Modifying some of these values may result in the graph being broken. Modify with caution.

f
function
traversable() : boolean

This tells you whether an edge is traversable from source to target.

f
function
reverse() : GraphEdge

This function allows you to obtain the mirror of an edge. For regular edges, this returns the virtual edge. For virtual edges, this returns a regular edge.

I
interface
ItemPropertySet

p
property
property : string

The name of the property that was changed.

p
property
value : any

The new value of the property.

p
property
target : GraphNode | GraphEdge

The target of the property change.