palworld-live-map

KO | EN

gitlite — search

#rag #cpp #computer-vision #claude-code #ios #docker #generative-ai #python #data-science #sql

palworld-live-map

(★ 9)

Self-hosted live map for Palworld dedicated servers—live players, bases, Pals, NPCs and server metrics. Docker; no client mods.

File Explorer

ZIP Download

- - ci.yml
- dependabot.yml
- - demo.gif
  - demo.png
- - README.md
- embed.go
- - main.go
  - main_test.go
- - AssemblyInfo.cs
  - ExportInfrastructure.cs
  - GameAssetReader.cs
  - GameVersionExtractor.cs
  - LandmarkExporter.cs
  - LandmarkShaper.cs
  - packages.lock.json
  - PalworldAssetExporter.csproj
  - Program.cs
  - WorldCatalogueExporter.cs
  - WorldCatalogueModels.cs
  - WorldCatalogueShaper.cs
- - packages.lock.json
  - PalworldAssetExporter.Tests.csproj
  - Program.cs
  - WorldCatalogueTests.cs
- .dockerignore
- Dockerfile
- export.sh
- global.json
- README.md
- - config.go
  - config_test.go
- - landmarks.go
  - landmarks_test.go
- - mapdata.go
  - mapdata_test.go
- - client.go
  - client_test.go
  - demo.go
  - demo_test.go
  - poller.go
  - poller_test.go
- - playerclaim.go
  - service.go
  - service_test.go
- - integration_test.go
  - saveroster.go
  - saveroster_test.go
- - savesidecar.go
  - savesidecar_test.go
  - types.go
- - claims.go
  - claims_test.go
  - server.go
  - server_test.go
- - worldcatalogue.go
  - worldcatalogue_test.go
- build-save-reader.sh
- generate-map-tiles.py
- map-tiles-requirements.txt
- - App.saveProgress.test.tsx
  - App.test.tsx
  - App.tsx
  - index.css
  - main.tsx
  - types.ts
- - capture-demo.mjs
  - precompress.mjs
- biome.json
- embed.go
- index.html
- package-lock.json
- package.json
- tsconfig.json
- vite.config.ts
.dockerignore
.env.example
.gitignore
.node-version
.nvmrc
compose.yml
CONTRIBUTING.md
DEVELOPMENT.md
Dockerfile
go.mod
LICENSE
Makefile
README.md
SECURITY.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

CI Visit
GHCR Visit
Core license: MIT Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Give your Palworld community a live view of players, guilds, bases, Pals, in-game locations, and server health. It runs against your dedicated server's official APIs, stays read-only, and needs no client mods.

![Animated Palworld Live Map demo showing filters, My Progress, a guild base and its Pals, leaderboards, map navigation, and both world regions](https://raw.githubusercontent.com/LukeHollandDev/palworld-live-map/main/assets/images/demo.gif)

## Features

- Interactive maps of Palpagos and the World Tree
- Live player locations and save-backed leaderboards for level, captures,
  Paldeck discoveries, Arena RP, exploration, and boss/tower clears
- Guild bases, members, and assigned worker Pals
- Current companion Pals linked to their players
- Search and filters for players, guilds, Pals, bases, and in-game locations
- Live player count, server FPS, uptime, base count, in-game day, and connection status
- Optional save integration adds offline players, saved locations, levels,
  guilds, capture totals, Paldeck progress, Arena RP, fast-travel points,
  discovered areas, boss/tower clears, and last-seen times
- Optional saved-character connection asks one grounded multiple-choice
  question before granting self-only completion access; raw save identifiers
  and completion keys stay in the backend
- My Progress combines private save-confirmed exploration with a local browser
  checklist, shows completion by landmark category, and can hide completed
  locations from both the map and its filters
- Share-position links open the same region, coordinates, and zoom without
  exposing a player or marker identifier
- Rich landmark details include altitude, journal previews, and Ancient Shrine
  rewards when that data is available
- Configurable refresh intervals and world-object layers
- Demo mode with fictional moving players and world objects

## Find anything on the map

Open the map filter to choose which markers are shown and search for players, guilds, Pals, bases, or in-game landmarks. Select a result to jump to its location and open its details.

## Track exploration progress

Open **My Progress** for a regional completed/total breakdown. Palpagos currently
contains 1,064 checklist locations: 83 Alpha Pals, 8 Tower Bosses, 33 Bounties,
3 Oil Rigs, 20 Watchtowers, 137 fast-travel points, 170 dungeons, 360 Lifmunk
Effigies, 55 journals, 106 Ancient Shrine pickups, and 89 NPC locations. The
total comes from the bundled landmark catalogue and updates with the selected
region and catalogue version.

Every location can be checked manually in the current browser. Connecting a
saved character can additionally confirm Alpha Pals, Tower Bosses, Bounties,
Watchtowers, fast travel, Lifmunk Effigies, journals, and Ancient Shrine
pickups. Oil Rigs, dungeons, and NPC locations remain manual-only. **Only show
missing** applies the combined result to the map and map-filter lists without
changing the category selections.

## Run with Docker

Enable Palworld's REST API, then start the map with the REST API URL and your server's admin password:

```bash
docker run -d \
  --name palworld-live-map \
  --restart unless-stopped \
  -p 8080:8080 \
  -e PALWORLD_REST_URL="http://your-palworld-server:8212" \
  -e PALWORLD_ADMIN_PASSWORD="your-admin-password" \
  ghcr.io/lukehollanddev/palworld-live-map:latest
```

Replace the URL and password with your server's values, then open <http://localhost:8080>. Enable Palworld's game-data API to also display bases, Pals, and NPCs. A healthcheck endpoint is available at `/-/health`.

To enable save enrichment, add `-v /path/to/Pal/Saved/SaveGames/0:/data/palworld/saves:ro`
and `-e SAVE_DATA_ENABLED=true`. The save directory must be mounted read-only.

In-game locations are bundled with the map, so they remain available without the game-data API.

The bundled Compose file provides the same single-service setup:

```bash
cp .env.example .env
# Edit .env with the server URL and admin password, then:
docker compose up -d
```

For a local preview that does not need a Palworld server or credentials:

```bash
docker run --rm -p 127.0.0.1:8080:8080 -e DEMO_MODE=true \
  ghcr.io/lukehollanddev/palworld-live-map:latest
```

Docker is the supported deployment method. See [Development](DEVELOPMENT.md#run-locally) to run from source.

## Run with Palworld Server Docker

If you run your server with [`thijsvanloef/palworld-server-docker`](https://github.com/thijsvanloef/palworld-server-docker), add the map to the same Compose file, set `ADMIN_PASSWORD`, then start both services with `docker compose up -d`. The map connects through the `palworld` service name:

```yaml
services:
  palworld:
    image: thijsvanloef/palworld-server-docker:latest
    environment:
      ADMIN_PASSWORD: "${ADMIN_PASSWORD}"
      REST_API_ENABLED: "true"
      REST_API_PORT: "8212"
      ENABLE_GAMEDATA_API: "true"
    volumes:
      - palworld-data:/palworld

map:
    image: ghcr.io/lukehollanddev/palworld-live-map:latest
    restart: unless-stopped
    environment:
      PALWORLD_REST_URL: http://palworld:8212
      PALWORLD_ADMIN_PASSWORD: "${ADMIN_PASSWORD}"
      SAVE_DATA_ENABLED: "true"
      PALWORLD_SAVE_ROOT: /palworld-data/Pal/Saved/SaveGames/0
    ports:
      - "${HTTP_PORT:-8080}:8080"
    volumes:
      - palworld-data:/palworld-data:ro

volumes:
  palworld-data:
```

## Configuration

Every supported environment option and timeout is listed below and documented in [`.env.example`](.env.example).

| Variable                  | Purpose                                                              | Default                |
| ------------------------- | -------------------------------------------------------------------- | ---------------------- |
| `PALWORLD_REST_URL`       | Private URL of the official Palworld REST API                        | required               |
| `PALWORLD_ADMIN_PASSWORD` | REST admin password; never sent to browsers                          | required               |
| `DEMO_MODE`               | Use fictional data and do not contact Palworld                       | `false`                |
| `HTTP_PORT`               | Host port published by Compose                                       | `8080`                 |
| `ADDR`                    | Address the Go HTTP server listens on                                | `:8080`                |
| `POLL_INTERVAL`           | Player and metrics refresh interval; minimum `2s`                    | `5s`                   |
| `UPSTREAM_TIMEOUT`        | Player and server-information timeout; must be below `POLL_INTERVAL` | `4s`                   |
| `WORLD_DATA_ENABLED`      | Poll bases, Pals, and NPCs                                           | `true`                 |
| `WORLD_POLL_INTERVAL`     | World-object refresh interval; minimum `5s`                          | `15s`                  |
| `WORLD_TIMEOUT`           | World-object timeout; must be below `WORLD_POLL_INTERVAL`            | `10s`                  |
| `SAVE_DATA_ENABLED`       | Enrich REST-visible players from immutable save backups              | `false`                |
| `PALWORLD_SAVE_ROOT`      | Read-only `SaveGames/0` directory                                    | `/data/palworld/saves` |
| `PALWORLD_SAVE_WORLD_ID`  | Exact world ID when automatic discovery is ambiguous                 | empty                  |
| `SAVE_POLL_INTERVAL`      | Save enrichment interval; minimum `15s`                              | `30s`                  |
| `SAVE_TIMEOUT`            | Whole-generation timeout; must be below `SAVE_POLL_INTERVAL`         | `20s`                  |
| `PLAYER_CLAIMS_ENABLED`   | Enable save-backed “This is me” character connection                 | `false`                |

To enable save integration, mount the server's `SaveGames/0` directory read-only
and set `SAVE_DATA_ENABLED=true`. The image includes the pinned
[`palworld-save-reader`](https://github.com/LukeHollandDev/palworld-save-reader)
automatically. Save records add offline players and progression without exposing
raw account, player, or guild identifiers. Leaderboards omit an individual stat
when that value is unavailable rather than treating it as zero.

Save decoding can use substantial memory, so leave container headroom. A
decoding problem does not interrupt the live map: online players and available
progress remain visible, while the map reports that offline details are
temporarily unavailable.

### Connect a saved character privately

Set `PLAYER_CLAIMS_ENABLED=true` alongside save integration. Choose an online or
offline character and answer one question based on their saved inventory,
equipment, food, or party. You can request a different question before answering.

If the map cannot build a question, add three distinct items or Pal species to
one supported group and wait for a completed backup before trying again.

Connecting adds save-confirmed completion for bosses, bounties, travel points,
effigies, journals, and Ancient Shrine pickups. Progress is checked
automatically, and the server selects the completed backup used for the overlay.
Other landmarks continue to use the browser-local checklist. The connection
lasts until the page is reloaded; HTTPS is recommended on untrusted networks.
Existing public player data and map features are unchanged.

## License

The Go application, web application, documentation, and other original project files are [MIT](LICENSE) unless marked otherwise. Palworld-derived map textures, screenshots, and extracted game data remain copyright Pocketpair; see the [Palworld asset provenance](assets/palworld/README.md) for extraction sources and the reproducible workflow. Inclusion in the same repository or container does not replace a component's own terms.

Palworld Live Map is an independent, fan-made project. It is not affiliated with, endorsed by, or sponsored by Pocketpair, Inc. Palworld and related names and marks belong to their respective owners.

palworld-live-map

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README