CyberAPI

Pathfinding and navigation for Among Us mods. Version 1.7.0 · plugin id com.cyberjack.cyberapi · PC and Android.

Overview

CyberAPI builds a grid of the current map and answers one question: how does a player get from here to there? It knows about walls, shadows, doors, and every way across the map that is not walking:

  • Airship ladders and the moving platform
  • Fungle ziplines
  • Vents (hop chains)
  • Mira HQ decontamination chambers
  • Submerged elevators
  • Any crossing your own mod registers

You ask for a route (MapPathfinding), optionally walk it (PlayerNavigation), and choose per request which of those the route may use (PathOptions). The host sets server-wide defaults in the in-game Navigation page; every call that does not say otherwise starts from them.

The older PathfindingAPI calls (below) are unchanged and still work. Everything on this page is additive.

Install

  1. Reference CyberAPI.dll from your project.
  2. Depend on it from your plugin class:
[BepInDependency("com.cyberjack.cyberapi")]
public class Plugin : BasePlugin { ... }

Namespaces: CyberAPI (the grid, PathfindingAPI), CyberAPI.Navigation (everything new).

Players need CyberAPI too: on Nebula, enable it for your server and it is delivered with your mod.

Quick start

Walk a player somewhere

using CyberAPI.Navigation;
using Reactor.Utilities;

// Call this on the client that controls the player (the local player, or a dummy on the host).
Coroutines.Start(player.CoMoveTo(goal, result =>
{
    if (result.Arrived) OnArrived();
    else Log($"stopped: {result.Status} - {result.Message}");
}));

or the same thing already started: player.MoveTo(goal, done).

Choose what the route may use

var options = PathOptions.Default          // the host's panel defaults, as a fresh copy
    .WithoutVents()                        // never through vents
    .WithoutPlatforms()                    // not the Airship platform
    .WithAutoOpenDoors();                  // open doors a player can open by hand

player.MoveTo(goal, done, options);

Only plan, do not walk

var request = MapPathfinding.CreateRequest(start, goal, options);
// once per frame (a few milliseconds each, so the game keeps drawing):
request.Step();
if (request.Status == PathStatus.Found)
    foreach (var point in request.Result.Points)
        Log($"{point.Kind} -> {point.Position}");

PathOptions

What one route may use. PathOptions.Default returns a fresh copy of the host's panel defaults every time, so change it freely. Every With... call returns the same object, so calls chain.

PropertyDefaultMeaningChain calls
UseLadderstrueWalk through ladder shafts (carried out as a climb). Off blocks the shafts.WithLadders(bool) / WithoutLadders()
UseZiplinestrueFungle ziplines.WithZiplines / WithoutZiplines
UseMovingPlatformstrueThe Airship moving platform. Only offered while it stands at the end you start from and is free.WithPlatforms / WithoutPlatforms
UseElevatorstrueSubmerged elevators (no effect elsewhere).WithElevators / WithoutElevators
UseDecontaminationtrueMira HQ decontamination chambers.WithDecontamination / WithoutDecontamination
UseVentsnulltrue always, false never, null: follow the player's role (only a player who may vent does; a search with no player never does).WithVents(bool) / WithoutVents()
WaitForDoorsfalseShut doors of any kind may be in the route; the walker waits for them to open on their own.WithWaitForDoors()
AutoOpenDoorsfalseShut doors a player can open by hand may be in the route; the walker opens them. Doors held shut by a sabotage or a timer stay walls.WithAutoOpenDoors()
AllowDiagonalstrueCorner cutting between grid cells.
WallCostScale1How much to dislike hugging walls: 0 ignore, 1 the grid's own tiers, 2 twice as strong.
DoorWaitCost10What waiting at a shut door adds to a route's cost (distance-like units).
DecontaminationCost22What a decontamination cycle adds.
MaxExpansions400000Safety stop: a search that expands this many cells gives up (NotFound).

WithoutDoors() makes shut doors walls (WaitForDoors and AutoOpenDoors both off). PathOptions.WalkOnly is plain walking only: every crossing, vents and shut doors off. Clone() copies an options object.

Doors and AutoOpenDoors. In 1.7.0, AutoOpenDoors no longer implies waiting for every door. It opens the clickable ones only. Add WithWaitForDoors() too if you also want the walker to wait for doors that open by themselves.

MapPathfinding

Route finding for the whole map. Static class, CyberAPI.Navigation.

MemberWhat it does
PathRequest CreateRequest(Vector2 start, Vector2 goal, PathOptions? options = null, PlayerControl? player = null)Starts a search you step yourself. With no grid yet the request is already finished with NotFound and a message. player only matters for vents (UseVents = null).
IEnumerator FindPath(start, goal, Action<PathResult> done, options = null, player = null)A coroutine that searches over as many frames as it needs, then calls done. Start it with Coroutines.Start.
PathResult FindPathNow(start, goal, options = null, player = null)Searches right now in one go. Fine for a one-off; on a phone prefer the other two.
bool IsReadyA grid exists and is built.

PathRequest

MemberWhat it does
PathStatus StatusSearching, Found, NotFound, Cancelled.
PathResult? ResultSet once the search ends.
Vector2 Start, Goal; PathOptions OptionsWhat was asked.
bool Step(float budgetMilliseconds = 3)Searches for up to that long. Returns true while more calls are needed.
IEnumerator Run(float budgetMilliseconds = 3)yield return request.Run() inside a coroutine.
void Cancel()Stops it; status becomes Cancelled.

The search is a stepwise A* over the grid plus the map's crossings, so it can be spread over frames.

PathResult & PathPoint

PathResult
StatusPathStatus.
PointsIReadOnlyList<PathPoint>, in order. Smoothed: straight stretches are single waypoints.
PositionsJust the positions, as a List<Vector2>.
UsesCrossingsTrue when any point is a crossing.
AutoOpensDoorsTrue when it was planned with AutoOpenDoors.
Cost, NodesExpanded, MessageSearch details. Message explains a failure.
PathPoint
PositionWhere this step ends (for a crossing: where the player arrives).
FromFor a crossing: where to stand to use it. For a plain step: the previous waypoint.
KindPathStepKind, below.
IsCrossingTrue for anything but Walk, Door, Decontamination.
CrossingReadyCan the crossing be used right now? Only the Airship platform ever says no: it carries from the end it stands at, and only while free. Code that moves a walker by itself should wait at From until this is true.
PathStepKindHow the walker gets there
WalkStraight line (already checked for walls).
DoorA shut door the route goes through: open it (or wait), then walk on.
DecontaminationA chamber door: call the chamber, wait for the cycle.
LadderClimb: stand at From, arrive at Position.
ZiplineFungle zipline.
MovingPlatformAirship platform.
VentOne or more vent hops (merged into one point).
ElevatorSubmerged elevator.
CustomA crossing another mod registered.

PlayerNavigation

Extension methods on PlayerControl that walk a route: plan, follow, notice trouble (stuck, a door that closed, a crossing that failed) and plan again.

Call
IEnumerator CoMoveTo(this PlayerControl player, Vector2 goal, Action<PathMovementResult> done, PathOptions? options = null, PathMovementSettings? settings = null)Plans a route from where the player stands, then walks it. done runs exactly once.
IEnumerator FollowPath(this PlayerControl player, PathResult path, Action<PathMovementResult> done, PathMovementSettings? settings = null)Walks a route you already planned. Does not re-plan when blocked.
void MoveTo(...), void Follow(...)The same two, already started.

Rules the walker follows:

  • Call it on the client that controls the player (player.AmOwner). Anything else ends at once with PlayerUnavailable.
  • Ladder, zipline, platform, vent and elevator steps use the game's own actions, so everyone sees the normal animations.
  • It re-plans up to MaxReplans times (default 2) when blocked, a crossing fails, or a door will not open. Only CoMoveTo re-plans; FollowPath stops.
  • While walking it watches the next stretch: a door that was open when the route was planned and has shut since counts as blocked, and the route is planned again.

PathMovementResult

Member
StatusArrived, Blocked (not at the goal and not moving), PathNotFound, CrossingFailed, DoorTimeout, TimedOut, Cancelled, PlayerUnavailable.
ArrivedShortcut for Status == Arrived.
Path, StoppedAt, StoppedAtIndex, MessageThe route used, where and at which waypoint it stopped, and why.

Movement settings

PathMovementSettings.Default is a fresh copy of the host's walker defaults.

PropertyDefault
WaypointTolerance0.2How close counts as being at a waypoint.
FinalTolerance0.15How close counts as arrived.
StuckSeconds2.5Seconds without progress before it nudges, then gives up or re-plans.
StuckDistance0.06How far it must move within StuckSeconds to count as progress.
DoorTimeoutSeconds15How long a shut door or decontamination cycle may take.
CrossingTimeoutSeconds12How long a ladder, zipline, platform, vent hop or elevator may take.
MaxSeconds180Hard limit for the whole movement (0 = none).
MaxReplans2Re-plans when blocked.

Teach routes about a crossing your mod adds (a teleporter, a trapdoor...). Routes then use it like any other.

NavLink link = NavLinks.Register(
    from: pointA, to: pointB, cost: 6f,
    traverse: player => MyCrossing(player),   // a coroutine that carries the player from A to B
    isAvailable: () => teleporterIsOn,        // optional: when false, routes skip it
    bothWays: false);

NavLinks.Remove(link);                          // when it goes away

Links are kept across grid rebuilds until removed. cost is distance-like (roughly: how many units of walking it is worth). The walker runs traverse when it reaches from. Such points have Kind == Custom.

Helper calls

Call
MapPathfinding.ClosedDoorAhead(Vector2 from, Vector2 to, float lookAhead = 1.2f)Is a shut door on the straight line, within the first lookAhead units? For walkers that moved on their own after planning.
MapPathfinding.IsDoorClosedAt(Vector2 position)Is the door covering this spot shut right now?
MapPathfinding.OpenDoorAt(Vector2 position)Asks the shut door at this spot to open, as a player click does. Only doors a player can open by hand react; returns whether a request was sent.
MapPathfinding.CallDecontamination(Vector2 position)Calls the nearest decontamination chamber the way its console does; works out outside vs inside from where you stand.
MapPathfinding.NearestFloor(Vector2 position, int maxRadiusCells = 60)The nearest ordinary floor (walkable, not in a ladder shaft, not in a shut door), or null. For putting a stuck walker back on its feet.

PathfindingAPI (unchanged)

The original, simpler calls keep working exactly as before:

Call
List<Vector2>? FindPath(Vector2 start, Vector2 end, bool allowDiagonals = true)A walking route (no crossings), or null.
GetRandomCoordInMap(), GetRandomCoord(), GetRandomCoordNear(origin, radius), GetRandomCoordInMapNear(origin, radius), GetRandomCoordsInMap(count, minSeparation)Random reachable spots.
IsWalkable(Vector2)Is this spot walkable right now?
RebuildGrid(int mapId), ShowDebugOverlay(), HideDebugOverlay(), ToggleDebugOverlay()Grid and overlay control.

Use MapPathfinding when you want crossings, per-route options or door handling; use PathfindingAPI for a quick walking route.

Navigation panel (for hosts)

Open the CyberAPI panel and press Navigation > in its header. These are the defaults every route starts from. Only the host can change them; everyone else sees them greyed out. Changes are sent to every player and applied at once; players joining later are brought up to date. The host's values are saved in navigation.txt next to CyberAPI's settings.txt (one Key=Value per line, hand-editable). Touch-friendly: switches and − / + buttons, no typing.

SettingDefaultRange / values
Laddersonon / off
Ziplinesonon / off
Decon Doorsonon / off
Platformonon / off
Elevatorsonon / off
Wait for Doorsoffon / off
Auto-Open Doorsoffon / off (opens doors a player can open by hand)
VentsAutoAuto (follow the player's role) / Always / Never
Wall Avoidance1.000 – 3, step 0.25
Waypoint Margin0.200.05 – 1, step 0.05
Stuck Timeout2.5 s0.5 – 10 s, step 0.5
Door Timeout15 s3 – 60 s, step 3

A mod can still override any of these for one request through PathOptions. Reset on the Navigation page (and the panel's main Reset) restores the defaults.

Overlay colours

Press F7 (when the overlay is enabled in the panel) to see the grid. Crossings are painted as ordinary node squares, each kind in a colour used for nothing else, with a thin line between the two ends of a crossing:

ColourMeans
purpleLadder (cells, shaft, line)
brownFungle zipline
indigoAirship moving platform
light pinkDecontamination door
whiteSubmerged elevator
salmonLink registered by another mod
lime / silver boxSubmerged upper / lower floor

Normal doors keep their blue / red cells and green / magenta lines. Vents keep their yellow outline; vent hops are not drawn.

What each map offers

MapCrossings
The Skeld, MIRA HQ, Polus, Fungle, Airship, SubmergedVents on every map (when allowed). Doors where the map has them.
AirshipLadders, moving platform, openable doors.
FungleZiplines.
Mira HQDecontamination chambers.
SubmergedElevators (found by name, so a Submerged update can stop them working), and two floors.

Android

  • The same API and the same Navigation page; the page uses large touch controls.
  • Searches are frame-sliced (Step() runs a few milliseconds at a time), so a phone keeps drawing while it plans. Prefer CreateRequest/FindPath over FindPathNow there.
  • Submerged does not exist on Android, so elevator links never appear.

Known limits

Crossing code has been exercised in Freeplay on Airship, Fungle and Mira HQ, but not on every map and not against every game update. Treat these as the honest edges:
  • Submerged is untested against a real Submerged install; its elevators are found by reflection and can stop being found after a Submerged update. The two-floor split is a guess from the elevator positions.
  • Walls come from the game's colliders. A spot the grid thinks is floor (for example a thin wall decoration without a collider) can be walked onto.
  • Doors use each door's own "open" flag; unknown door types count as open, so they never wall the map off.
  • Decontamination and some other game commands are sent the way the console sends them. If a game update changes them, the door will not open and the walker times out (DoorTimeout).
  • A player controls only their own character: call the walker on the owning client.

Changes in 1.7.0

  • New: MapPathfinding, PathRequest, PathOptions, PathResult/PathPoint, PlayerNavigation and PathMovementSettings.
  • New: crossings (ladders, ziplines, platform, vents, decontamination, Submerged elevators) and NavLinks.Register for your own.
  • New: the host-synced Navigation page and navigation.txt.
  • New: overlay colours per crossing kind.
  • New: one chain call per switch on PathOptions (WithoutVents(), WithAutoOpenDoors()...), and PathOptions.WalkOnly.
  • New: door helpers (ClosedDoorAhead, IsDoorClosedAt, OpenDoorAt), CallDecontamination, NearestFloor, PathPoint.CrossingReady.
  • Changed: AutoOpenDoors opens only doors a player can open by hand and no longer implies WaitForDoors.
  • Changed: a ladder can only be entered or left near its ends, never through its side.
  • Changed: the Airship platform is offered only while it stands at your end and is free.
  • Unchanged: every existing PathfindingAPI call.