# Commands

All citizen management commands use the `/kscitizen` prefix. The alias `/npc` can be used as a shorthand.

:::note[Permissions]
Every subcommand except `repair` needs `ks.citizen.admin` or `ks.admin` (the old `citizen.admin` still works). The bare `/kscitizen` usage list needs `ks.citizen`. `/kscitizen repair` is a player command (`ks.citizen.user.repair`, granted by default). See [Permissions](https://wiki.kyuubisoft.com/hytale/citizens/permissions/).
:::

Most NPC work is now easier in the [NPC management window](https://wiki.kyuubisoft.com/hytale/citizens/admin-windows/) (`/kscitizen edit`). The commands below stay available.

An NPC ID is one word without quotes. A subcommand that needs an ID and gets none only shows how to use it and changes nothing.

:::note[Before Core 2.9.9]
The subcommands with an ID (`create`, `remove`, `tp`, `respawn`, `info`, `marker`, `wprecord`, `skinreload`) refused every ID, and `/kscitizen create` without an ID made an NPC called `create`. If you have such an NPC, delete it with `/kscitizen remove create`.
:::

## Command Reference

### `/kscitizen edit [id]`

Opens the NPC management window.

```
/kscitizen edit
/kscitizen edit town_guard
```

- Without an ID it opens the NPC you are looking at (up to 24 blocks away), or the list if you look at none.
- With an ID it opens that NPC.

---

### `/kscitizen list [group]`

Lists all registered citizens with their spawn status.

```
/kscitizen list
/kscitizen list quest_npcs
```

**Output:**
```
=== Citizens (18) ===
• oasis_healer [quest_npcs] (-21, 0, 3)
• desert_scout [quest_npcs] (-65, -10, 4)
• guide_finn (12, 65, -4)
```

- Green dot = currently spawned.
- Red dot = not spawned (world not loaded, or hidden).
- Without a group it lists all NPCs. The optional `group` parameter shows only the citizens with that `group` field.

---

### `/kscitizen create <id>`

Creates a new citizen at your current position.

```
/kscitizen create town_guard
```

The ID is one word without quotes: `/kscitizen create "Black Smith"` only shows how to use the command. Give the NPC a display name with spaces in the NPC management window instead.

The new citizen is created with these defaults:
- Player model (`isPlayerModel: true`)
- Your current position and world
- Your facing direction (rotY)
- Idle movement, scale 1.0

The NPC spawns immediately after creation. Edit it in the NPC management window, or edit the JSON and reload. If an NPC file failed to load, creating is refused with a clear message until the file is fixed.

---

### `/kscitizen remove <id>`

Removes a citizen from the configuration and despawns its entity.

```
/kscitizen remove town_guard
```

- Exactly one ID: `/kscitizen remove Black Smith` only shows how to use the command and removes nothing.
- The NPC files keep their last 10 timestamped backups in `citizen-backups/`.
- An NPC that has commands running as the console can only be removed with `ks.core.admin.dialog.console` as well.

---

### `/kscitizen tp <id>`

Teleports you to the citizen, also into another world.

```
/kscitizen tp oasis_healer
```

Teleports you to the NPC's position, regardless of whether it is currently spawned. The world of the NPC must be loaded. Since 2.9.0 this uses Hytale's teleport for your own player instead of the console `tp` command, which could move a different player with a similar name.

---

### `/kscitizen respawn <id>`

Despawns and re-spawns a specific citizen in its own world.

```
/kscitizen respawn desert_scout
```

Use this after changes that need a fresh spawn, such as skin, equipment, scale or position fixes.

---

### `/kscitizen respawnall`

Despawns and re-spawns **all** registered citizens, each one in its own world. NPCs whose world is not loaded spawn when that world loads. The reply tells you how many were respawned and how many are waiting.

```
/kscitizen respawnall
```

:::caution
On servers with many citizens, this command can briefly impact performance. Use `/kscitizen respawn <id>` for single NPCs when possible.
:::

---

### `/kscitizen reload`

Reloads the citizen configuration from disk in all worlds.

```
/kscitizen reload
```

This re-reads `citizens.json` and `custom/custom_citizens*.json` and respawns the citizens in their worlds. If a file is locked because it failed to load, the reply names it; fix the file and reload again.

:::tip
Run `/kscitizen reload` after editing JSON files by hand. Core never saves over a file that changed on disk; admins get a chat warning instead.
:::

---

### `/kscitizen info <id>`

Displays details about a specific citizen.

```
/kscitizen info oasis_healer
```

**Output:**
```
=== Citizen: oasis_healer ===
Name: Zara
Group: none
World: Forgotten_Temple
Position: -21.3, 0.0, 3.0
Model: Player (Darkelf)
Role: Citizen_Interactable_Role
Movement: IDLE
Status: Spawned
```

Shows name, group, world, position, model, NPC role, movement type and spawn status, plus the dialog count and shop ID when set.

---

### `/kscitizen marker <citizenId> [! | ? | off]`

Sets or removes a per-player quest marker above a citizen. This is mainly a testing command.

```
/kscitizen marker oasis_healer !      # Show quest available marker
/kscitizen marker oasis_healer ?      # Show quest turn-in marker
/kscitizen marker oasis_healer off    # Remove marker
```

- The marker is only visible to the player who runs the command.
- Defaults to `!` if no marker type is given.
- Must be run by a player.

---

### `/kscitizen viewer`

Opens the NPC viewer: NPCs, mod NPCs, orphans, mounts and world creatures per loaded world, with teleport, bring here, remove, "Clean up orphans" and "Adopt as NPC". See [NPC Admin Windows](https://wiki.kyuubisoft.com/hytale/citizens/admin-windows/#npc-viewer).

```
/kscitizen viewer
```

---

### `/kscitizen skinreload <id>`

Fetches the skin of an NPC with `skinUsername` again and respawns it. If the player with that name is online, their current skin is used; otherwise the skin is fetched again from the online skin database.

```
/kscitizen skinreload desert_scout
```

---

### `/kscitizen repair`

Opens Hytale's item repair window for the item in your active hotbar slot. This is a player command (`ks.citizen.user.repair`, granted by default).

---

### `/kscitizen browseskins`

Meant to browse skin JSON files on the server. The server-side file browser is currently switched off because of a Hytale bug, so the command only answers with a chat message.

---

### Waypoint Recording Commands

These commands record NPC patrol paths by walking through the world. The recorded waypoints define the NPC's `PATH` movement route.

#### `/kscitizen wprecord <citizenId>`

Starts waypoint recording for a citizen. A HUD shows the recording status.

```
/kscitizen wprecord town_patrol
```

#### `/kscitizen wpadd [seconds]`

Adds a waypoint at your current position. Optionally give a pause time in seconds (0-30) for the NPC to wait there.

```
/kscitizen wpadd           # Add waypoint, no pause
/kscitizen wpadd 5         # Add waypoint, NPC pauses 5 seconds here
```

A pause above 30 seconds is cut to 30. A word that is no number, or a negative number, adds no waypoint and shows how to use the command.

#### `/kscitizen wpundo`

Removes the last recorded waypoint.

#### `/kscitizen wpdone`

Stops recording and saves all waypoints to the citizen config.

:::tip
A PATH movement type needs at least 2 waypoints. The NPC walks from waypoint to waypoint in order. Set `"pathShape": "LOOP"` (default) to loop back to the start, or `"LINE"` to walk back and forth.
:::

---

## Command Aliases

| Full Command | Alias |
|-------------|-------|
| `/kscitizen` | `/npc` |

## Console Usage

These subcommands can be run from the server console: `list`, `remove`, `respawnall`, `reload` and `info`. All others need a player because they use your position, world, a per-player marker or a window: `create`, `tp`, `respawn`, `edit`, `viewer`, `marker`, `skinreload`, `repair`, `browseskins`, `wprecord`, `wpadd`, `wpundo`, `wpdone`.