Daffy's Mods
← All buildsBots

Club Penguin Bots

Bot penguins for a private Waddle Forever Club Penguin server. They walk into the rooms you visit, play out small scenes (a cafe with a server and customers, a dance crew, a snowball fight), chat in short friendly lines, dress for the date the server is set to, and remember the players they have met. I built them so the island feels alive on a small home server.

  • Updated Oct 28, 2026
  • 3 pictures
  • 8 updates
Club Penguin Bots, first picture

The repo also holds the Waddle Forever changes the bots need, plus a tester bot that plays every 2005-2008 event like a young kid to find bugs.

Status: running on my home server for the 2005-2010 eras; the install steps below were never tried on a fresh PC · Visibility: public · Last updated: 2026-10-04

Contents

Bot features

Everything below is what the code in bots/bots/ and waddle-forever/src/server/socket-server/bots.ts really does today.

Who they are

Where they show up

What they do in a room

Chat

Era outfits

Buddies and memory

What they do not do (yet)

Screenshots

Night Club on the Halloween 2007 date: costumed bots dancing on the pumpkin floor and chatting

Halloween Party 2007, Night Club: the dance crew in costumes from that date’s wardrobe.

Coffee Shop in November 2007: a server at the counter, customers on the couches

Coffee Shop, November 2007: a server at the counter and customers on the couches, in everyday clothes.

Pizza Parlor in November 2007: staff at the counter, customers seated at the tables

Pizza Parlor, November 2007: staff at the counter and customers seated at the real tables.

All shots come from a test copy of the server. The one test penguin is “Visitor”; every other penguin is a bot.

Era changes in Waddle Forever

The bots run inside a fork of Waddle Forever that I changed to play the 2005-2010 eras the way the real game did on each date. Those changes are in waddle-forever/ (code only, no game files):

Requirements

Install

  1. Get Waddle Forever at the commit the patches were made against, and apply the 24 patches:

    git clone https://github.com/nhaar/Waddle-Forever
    cd Waddle-Forever
    git checkout -b bots-eras 7a578e7544e7bfd95ffb2a92033e02a86e262475
    git am <path-to>/club-penguin-bots/waddle-forever/patches/*.patch

    The files in waddle-forever/src, scripts, fla and tsconfig.bots-check.json are the same changes as finished files, if you would rather read or copy them.

  2. Put the bot brain where the server looks for it. bots.ts sets ROOT near the top (/opt/club-penguin/src/wand/houdini on my server) and loads the brain from <ROOT>/houdini/plugins/bots/:

    sudo mkdir -p /opt/club-penguin/src/wand/houdini/houdini/plugins
    sudo cp -r <path-to>/club-penguin-bots/bots/bots /opt/club-penguin/src/wand/houdini/houdini/plugins/

    Or change ROOT in src/server/socket-server/bots.ts to a folder of your choice and copy bots into <ROOT>/houdini/plugins/ there.

  3. Install and build Waddle Forever as its README describes (yarn install, then its build steps).

  4. Optional, Houdini: copy bots/bots/ into Houdini’s houdini/plugins/ folder. It was made against Houdini commit 45021fa838ede1e1526858ea079bd13d1b01d5b9 and uses Houdini’s own dependencies.

Run

  1. Start the Waddle Forever server. I run only the server part, from the Waddle Forever folder:

    npx tsx src/server/main.ts

    (yarn dev does the same with file watching.) The log should show Bots ready (four reserved room slots).

  2. Log in with a client and walk into a room. The bots appear as you arrive and start their scene within a few seconds.

  3. Click a bot to see its player card, say hi, wave, or send it a buddy request.

To run without bots, take Bots out of src/server/socket-server/world-server.ts (the import, the constructor and stop() calls, and the intercept check in front of the XT handler). Today the server stops at startup if the brain files are missing.

Configuration

Setting Where Meaning
ROOT top of bots.ts folder that holds houdini/plugins/bots/
WF_BOTS_STATE environment where the bots keep their state file (default <ROOT>/bots-state.json)
WF_TARGET_IP environment address the clients should use when it is not the request’s host
WF_HTTP_PORT environment HTTP port (default 24105); login and world ports follow it
WF_RUFFLE_DIR environment folder with a Ruffle web build to serve at /ruffle
WF_ALLOW_FAN environment 1 serves fan-made recreation files again

Room sizes for the bots are in Brain.target() in brain.py (8 per room, 6 in the Coffee Shop). The state file holds buddy lists and bot memories; keep it out of git.

How it works

Tester

tester/ is a QA bot that plays old Club Penguin (2005-2008) the way a young kid would, to check that the server really serves every event of that era on the right date: the map, rooms, music, minigames, hunt items, catalogues, puffles, igloo and inventory. It runs on a separate sandbox copy of the server (ports 16112-16114), never the main one, and writes down what passed and what failed. Most of the era fixes above were found this way.

File What
kidbot.py layer A
layerb.mjs, inv.mjs, puffle.mjs layer B and its two focused flows
layerb.sh, inv.sh, puffle.sh, layerb-chain.sh runners (one browser at a time, in a systemd unit capped at 6 GB)
sandbox-ctl.sh the sandbox server: setup, date YYYY-MM-DD, start, stop, status, log
oracle.ts asks Waddle Forever what it serves on a date (copied into the sandbox and run with tsx)
patchwf.py, wf_autologin.py straight-in login for the era clients (no typing) plus the read-only probe
swfscan.py reads old Flash (AS1/AS2) files: disassembler and placed objects, no external tools
as2/ compiles a small AS2 file for the probe (uses JPEXS FFDec)
CP-EVENTS-2005-2008.md the 79 events, their dates and free items, and the 12 checks (status columns empty)

Requirements: Linux or WSL2 with systemd, Python 3 and Node.js; a Waddle Forever checkout with these patches and its node_modules at /opt/club-penguin/wf/src (the scripts use the /opt/club-penguin/ layout; change the paths at the top of each script for another layout). For layer B, Playwright 1.63 with Chromium in /opt/club-penguin/kidbot-browser (npm i playwright, then npx playwright install chromium) and a Ruffle web build. For as2/ only, Java and JPEXS FFDec.

bash tester/sandbox-ctl.sh setup      # git worktree of the server + copied data; set the branch name in that line to yours
python3 tester/kidbot.py 1-79          # layer A, all events (or one: 49)
bash tester/layerb.sh 49               # layer B, one event (1-79 for all); --only hunt,puffle; --all re-walks proven rooms

Logs and screenshots go to $KB_OUT (default /var/tmp/cp-kidbot). Status: layer A runs all 79 events and they all pass on my server (934 checks pass, 0 fail, 14 not applicable); layer B has so far been run on a few events plus the inventory and puffle flows. It was written against this fork, so on stock Waddle Forever expect some checks to need changes. Hobby code, not a polished tool.

Project layout

Folder What lives there
bots/bots/ the bot brain (brain.py, scenes.py, lives.py, outfits.py), its data (personality.json, wardrobe.json, houdini-wardrobe.json) and the Houdini plugin (__init__.py)
bots/test_scenes.py, bots/test_outfits.py unit tests for the brain
waddle-forever/patches/ the Waddle Forever changes as 24 patches (code only)
waddle-forever/src/, scripts/, fla/ the same changes as finished files, at Waddle Forever’s own paths
tester/ the kid tester bot
docs/screenshots/ README pictures

Development

python bots/test_scenes.py      # 29 tests: admission, room budget, roles, chat, lives
python bots/test_outfits.py     # 6 tests: names, dated outfits, slots

Both run with plain Python, no server needed. In a patched Waddle Forever folder, npx tsc -p tsconfig.bots-check.json type-checks the server with the bot code. After changing item-art.as, rebuild item-art-avm1.ts with the tools in tester/as2/.

Coming soon

Keep this list current: when an item ships, move it to Recent changes with the date, then add what is next.

Recent changes

Credits and license

More builds

BotsToontown Classic with BotsToontown Online as it played at its September 2013 shutdown, on your own PC, with a town full of bot toons that play like real players.Updated Oct 4, 20266 picturesBotsCS:GO BotsSmarter bots for a private, offline CS:GO LAN server (the legacy 1.38.8.1 build).Updated Oct 28, 20262 picturesGames & modsCustom Toontown ServerMy own take on Toontown Online, built on Open Toontown (the open-source Toontown client and server).Updated Oct 28, 20266 pictures