---
title: "Waypoints API - Charted wiki"
description: "Read the world's waypoints, add and remove your own, and hear when they change."
url: https://voxelsprout.com/charted/wiki/waypoints-api
---

[Charted](https://voxelsprout.com/charted) [Wiki](https://voxelsprout.com/charted/wiki)Waypoints API

# Waypoints API

Read the world's waypoints, add and remove your own, and hear when they change.

`ChartedWaypoints` works on the waypoints of the world the player is in: the player's own, the ones Charted makes, and yours. From Charted **0.1.0**.

## What a waypoint is

An unmodifiable `Map<String, Object>` with these keys:

| Key       | What it holds                                   |
| --------- | ----------------------------------------------- |
| id        | Its id, for get and remove.                     |
| name      | The name the player sees.                       |
| x, y, z   | Where it is. y is null when no height is known. |
| dimension | The dimension id, such as minecraft:overworld.  |
| color     | 0xRRGGBB.                                       |
| kind      | manual, death, respawn, portal or temporary.    |
| group     | The group it is in.                             |
| hidden    | Whether the player hid it.                      |
| owner     | The mod that added it.                          |

## Add your own

```java
if (ChartedWaypoints.isAvailable()) {
    // Returns the new waypoint's id, or null. y may be null.
    String id = ChartedWaypoints.add("mymod", "Quest camp", 120, 64, -300, "minecraft:overworld", 0x3080FF);

    // The same, in a group of your choosing ("" for none).
    ChartedWaypoints.add("mymod", "Quest giver", 140, null, -280, "minecraft:overworld", 0x3080FF, "Quests");
}
```

A waypoint you add is saved with the world like the player's own. Before adding, look for yours in `list()` rather than adding it again each session.

The player can edit and delete it like their own; the list shows it under your mod's name.

## Take them away

```java
ChartedWaypoints.remove("mymod", id);       // one of yours
int gone = ChartedWaypoints.removeAll("mymod"); // all of yours in this world
```

## Hear about changes

```java
// Called at the end of a tick in which waypoints changed.
ChartedWaypoints.listen("mymod", () -> refreshMyList());

// Done listening.
ChartedWaypoints.unlisten("mymod");
```

## Reference

| ChartedWaypoints                                 | What it does                                                              |
| ------------------------------------------------ | ------------------------------------------------------------------------- |
| isAvailable()                                    | Charted is running and knows which world the player is in.                |
| list() / list(dimension)                         | Every waypoint of this world, hidden ones too, or those of one dimension. |
| get(id)                                          | One waypoint, or null.                                                    |
| add(owner, name, x, y, z, dimension, rgb)        | Adds one owned by you; returns its id or null. y may be null.             |
| add(owner, name, x, y, z, dimension, rgb, group) | The same, in a group of your choosing ("" for none).                      |
| remove(owner, id)                                | Removes one of yours.                                                     |
| removeAll(owner)                                 | Removes all of yours in this world; returns how many.                     |
| listen(owner, runnable) / unlisten(owner)        | Called at the end of a tick in which waypoints changed.                   |

[Previous For mod developers](https://voxelsprout.com/charted/wiki/api) [Next Markers API](https://voxelsprout.com/charted/wiki/markers-api)

Something missing or wrong on this page? Say so on [Discord](https://discord.gg/CvdkGbEW4y).