Skip to main content

Kiss: Psycho Circus - The Nightmare Child Docker Container

This Docker container runs a Kiss: Psycho Circus - The Nightmare Child dedicated server. It is built on the WINE image and runs the retail game's Dedicated.exe (v1.13). The container doesn't download the game, so you provide the files.

Quick Start​

services:
kisspsychocircus:
image: lancommander/kisspsychocircus:latest
container_name: kisspsychocircus

ports:
- 42972:42972/udp
- 42973:42973/udp

volumes:
- "/data/Servers/Kiss Psycho Circus/Deathmatch:/config"

environment:
KPC_HOSTNAME: "My Psycho Circus Server"
KPC_MAX_PLAYERS: "16"

user: root
cap_add:
- SYS_ADMIN
security_opt:
- apparmor:unconfined

restart: unless-stopped

Copy a full Kiss: Psycho Circus install patched to 1.13 (the folder with Dedicated.exe, server.dll, object.lto, PSYCHO.REZ and KPCPatch.rez) into Server/ before the first start. You can instead set KPC_ARCHIVE_URL to a zip of that folder.

A team Conquer (BigHeads) game on a few maps:

    environment:
KPC_GAME_TYPE: "conquer"
KPC_TEAMPLAY: "1"
KPC_MAPS: "PM02, PM05, PM08"
KPC_FRAG_LIMIT: "50"
KPC_EXTRA_SETTINGS: "startgauntlets 1; startscourge 1"

How It Starts​

  1. PostInitialization/10-InitializeWinePrefix.ps1 (from the WINE image) creates the Wine prefix in /config/wineprefix.
  2. PostInitialization/20-InstallKissPsychoCircus.ps1 checks for Server/Dedicated.exe. If it's missing and KPC_ARCHIVE_URL is set, the hook downloads and extracts the archive (without Movies/ and Music/) and remounts the overlay.
  3. PostInitialization/30-ConfigureKissPsychoCircus.ps1 writes Dedicated-lancommander.exe (the idle patch), <KPC_CONFIG> (default lancommander.cfg) with the non-empty KPC_* settings, and MapLists/lancommander.txt from KPC_MAPS. It writes through Merged/, so the files land in Overlay/.
  4. START_EXE (/usr/local/bin/kpc-server) runs Dedicated-lancommander.exe -exec <KPC_CONFIG> from the game folder under Wine, on a pty.

Dedicated.exe executes the config file and waits at a > prompt; a game only starts with the start console command, which -start on the command line does not do. It reads that prompt with ReadConsoleInput, which needs a real console, so kpc-server runs it under script(1) and feeds the pty from the FIFO /tmp/kpc/console. Two seconds after the server prints Ready. it types start. A successful start ends with:

Executed lancommander.cfg...

Host name is: Kiss Psycho Circus Server
Message of the day is: Welcome to Psycho Circus

Ready.
> start
Unregistered 0 models.
Loaded world: worlds\deathmatch\PM01
Running world
Server started on 172.17.0.2, port 42972.

Configuration Options​

Ports​

  • 42972/udp: Game (KPC_PORT)
  • 42973/udp: GameSpy query (KPC_GAMESPY_PORT). It answers \status\ with gamename kiss, the host name, map, player counts and limits.

Environment Variables​

See the README for the full table.

Server config​

<KPC_CONFIG> starts with a // Generated by LANCommander marker line and is regenerated on every start. To maintain it by hand, delete the marker line from Overlay/<KPC_CONFIG> (or point KPC_CONFIG at a file of your own, e.g. the stock server.cfg or server_bighead.cfg); a file without the marker is never touched. MapLists/lancommander.txt is always rewritten, and the generated config points maplist at it.

The config holds variables only, as "name" "value" lines. Besides the KPC_* settings, the server knows startgauntlets, startbelt, startboots, startshoulderplates, startbreastplate, startmask (start with that armor piece) and startscourge, startzero, startmagma, startwindblade, startultimate (start with that weapon), all 0/1. Set them with KPC_EXTRA_SETTINGS. Since 1.13, LithTech engine console variables such as UpdateRate can be set too. dedicated.txt in the game folder documents all of them. There is no join password.

Server console​

The server console goes to docker logs. To type a command into it:

docker exec kisspsychocircus kpc-console say Map change in 1 minute
docker exec kisspsychocircus kpc-console nextlevel
docker exec kisspsychocircus kpc-console list_ids
docker exec kisspsychocircus kpc-console kick_id 3

kpc-console quotes the rest of the line for say, msg (center print) and kick (by name). Other commands: stop/end (end the game, kicking everyone), start [world], exec <file>, quit, and any variable (fraglimit 30). The server's reply shows up in the log.

Idle patch​

The main loop of Dedicated.exe (at 0x401DE3) calls timeGetTime, polls the console, and runs a server frame once 8 ms have passed. It never sleeps, and under Wine each console poll is a wineserver request, so an idle server uses about 1.7 CPU cores (the MaxFPS engine variable doesn't help). The patch replaces the cmp ecx,8 / jb at 0x401E0C with a jump into a code cave in the zero padding at the end of .text (0x40E310). The cave looks up Sleep once (GetModuleHandleA/GetProcAddress, cached at 0x41AC98 in .data) and calls it for the rest of the 8 ms frame, and it grows the .text and .data virtual sizes to cover the new bytes. The server still runs a frame every 8 ms, and an idle server uses about 20% of one core and 210 MB.

The hook only patches a Dedicated.exe with the sha256 of the 1.13 build and checks the result's sha256. The patched copy is Dedicated-lancommander.exe in Overlay/; Server/Dedicated.exe is never modified. Set KPC_IDLE_PATCH=false to run the original.

Hooks​

HookWhen
PreInstallKissPsychoCircus / PostInstallKissPsychoCircusAround the game file check/download
PreInitializeWinePrefix / PostInitializeWinePrefixAround Wine prefix creation (WINE image)

Put .ps1 scripts in config/Scripts/Hooks/<HookName>/.

Troubleshooting​

  • Stuck at Ready.: the server is waiting for start. kpc-server sends it two seconds after Ready.; typed earlier, its Enter gets lost while the console is still being set up and the text stays on the prompt. Run docker exec <container> kpc-console start if it ever happens.
  • ERROR: You must run the dedicated server from a full install and from the same directory as psycho.rez!: Server/ must hold the whole game folder, including PSYCHO.REZ (about 460 MB) and KPCPatch.rez.
  • Could not start world ...: a KPC_MAPS entry isn't a world in the rez files. The deathmatch maps are PM01 to PM10.
  • High CPU: check the log for the idle patch warning. A Dedicated.exe other than the 1.13 build (sha256 19d7766c949b2278ec1e99c9e559312d35fd26456bb2539d9e525abad8a829a8) runs unpatched.
  • Settings ignored: check Overlay/<KPC_CONFIG>. If its first line isn't the marker, the image doesn't write to it.
  • Slow docker stop: the server doesn't get the stop signal, so Docker kills it after its timeout (10 s).