Skip to content

Commit

Permalink
Merge pull request #539 from MusclePr/feature/rest-cli
Browse files Browse the repository at this point in the history
add REST API command line interface 'rest-cli'.
  • Loading branch information
thijsvanloef committed Apr 29, 2024
2 parents 0b01c6d + ce8b8fb commit d1e3bb1
Show file tree
Hide file tree
Showing 5 changed files with 179 additions and 2 deletions.
3 changes: 2 additions & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,8 @@ COPY ./scripts /home/steam/server/
RUN chmod +x /home/steam/server/*.sh && \
mv /home/steam/server/backup.sh /usr/local/bin/backup && \
mv /home/steam/server/update.sh /usr/local/bin/update && \
mv /home/steam/server/restore.sh /usr/local/bin/restore
mv /home/steam/server/restore.sh /usr/local/bin/restore && \
ln -sf /home/steam/server/rest_api.sh /usr/local/bin/rest-cli

WORKDIR /home/steam/server

Expand Down
77 changes: 77 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -333,6 +333,83 @@ This will open a CLI that uses RCON to write commands to the Palworld Server.

For a full list of commands go to: [https://tech.palworldgame.com/settings-and-operation/commands](https://tech.palworldgame.com/settings-and-operation/commands)

## Using REST API

REST API is not enabled by default.
If used, please set REST_API_ENABLED to true.

docker-compose.override.yml

```yaml
services:
palworld:
environment:
REST_API_ENABLED: true
```
The palworld-server-docker image provides rcon-cli as well as rest-cli.
```bash
$ docker exec -it palworld-server rest-cli
Usage: rest-cli <api> [options]
api:
announce <json> ... announce message.
ban <json> ... ban player.
info ... show server informations.
kick <json> ... kick player.
metrics ... show server metrics.
players ... show online players.
save ... save the world.
settings ... show server settings.
shutdown <json> ... shutdown server.
stop ... force stop server.
unban <json> ... unban player.
options:
'{...}' ... json.
- ... json from stdin.
-h, --help ... help.
```

For example, you can broadcast a message to everyone in the server with the following command:

CLI parameter style:

```bash
docker exec -i palworld-server rest-cli announce "Broadcast Hello everyone"
```

JSON parameter style:

```bash
docker exec -i palworld-server rest-cli announce '{"message":"Broadcast Hello everyone"}'
```

JSON pipe style:

```bash
echo '{"message":"Broadcast Hello everyone"}' | docker exec -i palworld-server rest-cli announce -
```

rest-cli allows you to call REST APIs directly without exposing ports outside the container.

### List of REST APIs

| API | Info |
|----------------------------------|-----------------------------------------------------|
| info | Get the server information. |
| players | Get player list. |
| settings | Get the server settings. |
| metrics | Get the server metrics. |
| announce | Announce message. |
| kick {SteamID} | Kick player. |
| ban {SteamID} | Ban player. |
| unban {SteamID} | Unban player. |
| save | Save the world. |
| shutdown {Seconds} {MessageText} | Shutdown the server |
| stop | Force stop the server. |

For an official documents go to: [https://tech.palworldgame.com/category/rest-api](https://tech.palworldgame.com/category/rest-api)

## Creating a backup

To create a backup of the game's save at the current point in time, use the command:
Expand Down
6 changes: 6 additions & 0 deletions docusaurus/docs/known-issues/known-issues.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,12 @@ As an example, if I use:

only Hello is transmitted.

:::note info
Using REST API solves it.

`docker exec -it palworld-server rest-cli announce "Hello world"`
:::

## XBox GamePass players unable to join

At the moment, Xbox Gamepass/Xbox Console players will not be able to join a dedicated server.
Expand Down
3 changes: 2 additions & 1 deletion scripts/helper_functions.sh
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,8 @@ REST_API(){
local URL="http://localhost:${REST_API_PORT}/v1/api/${1}"
local ACCEPT="Accept: application/json"
local USERPASS="admin:${ADMIN_PASSWORD}"
if [ "${DATA}" = "" ]; then
local post_api="save|stop"
if [ "${DATA}" = "" ] && [[ ! ${1} =~ ${post_api} ]]; then
curl -s -L -X GET "${URL}" -H "${ACCEPT}" -u "${USERPASS}"
else
curl -s -L -X POST "${URL}" -H "${ACCEPT}" -u "${USERPASS}" --json "${DATA}"
Expand Down
92 changes: 92 additions & 0 deletions scripts/rest_api.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
#!/bin/bash
SCRIPT=$(basename "${0}")
ORGPATH=$(readlink -fn "${0}")
ORGDIR=$(dirname "${ORGPATH}")
#shellcheck source=scripts/helper_functions.sh
source "${ORGDIR}/helper_functions.sh"
help="-h|--help"
if [ $# -lt 1 ] || [[ ${1} =~ ${help} ]]; then
cat << EOF
Usage: ${SCRIPT} <api> [options]
api:
announce <json> ... announce message.
ban <json> ... ban player.
info ... show server informations.
kick <json> ... kick player.
metrics ... show server metrics.
players ... show online players.
save ... save the world.
settings ... show server settings.
shutdown <json> ... shutdown server.
stop ... force stop server.
unban <json> ... unban player.
options:
'{...}' ... json.
- ... json from stdin.
-h, --help ... help.
EOF
exit 1
fi

if [ ! "${REST_API_ENABLED,,}" = true ]; then
echo "ERROR: REST_API_ENABLED=False"
exit 1
fi

api="${1}"
json="${2}"
api_required_json="announce|ban|kick|shutdown|unban"
if [[ ${api} =~ ${api_required_json} ]]; then
if [ $# -lt 2 ]; then
echo "input json required."
exit 1
fi
if [ "${json}" = "-" ]; then
json="$(cat -)"
elif [[ ! ${json} =~ ^\{ ]]; then
usage="Usage: ${SCRIPT} ${api}"
case ${api} in
"announce")
if [[ ${json} =~ ${help} ]]; then
echo "${usage} <message>"
exit 1
fi
json="{\"message\":\"${2}\"}"
;;
"ban")
if [[ ${json} =~ ${help} ]]; then
echo "${usage} <steam_00000000000000000> [message]"
exit 1
fi
msg=${3:-You are banned.}
json="{\"userid\":\"${2}\",\"message\":\"${msg}\"}"
;;
"kick")
if [[ ${json} =~ ${help} ]]; then
echo "${usage} <steam_00000000000000000> [message]"
exit 1
fi
msg=${3:-You are kicked.}
json="{\"userid\":\"${2}\",\"message\":\"${msg}\"}"
;;
"shutdown")
if [[ ${json} =~ ${help} ]]; then
echo "${usage} <sec> [message]"
exit 1
fi
sec=${2}
msg=${3:-Server will shutdown in ${sec} sec.}
json="{\"waittime\":${sec},\"message\":\"${msg}\"}"
;;
"unban")
if [[ ${json} =~ ${help} ]]; then
echo "${usage} <steam_00000000000000000>"
exit 1
fi
json="{\"userid\":\"${2}\"}"
;;
esac
fi
fi

REST_API "${api}" "${json}" && echo ""

0 comments on commit d1e3bb1

Please sign in to comment.