Contents
1 Overview
A cozy color puzzle on a farm: drag egg cartons across the board so the chicks of the same color hop into the free cups. A full color flies away, and the level is won when every chick is home. 100 levels in 5 worlds (Barn, Orchard, Snow, Night and Autumn), each with its own scenery, coop, music and ambience. New ideas arrive one at a time with a short explanation: one-way cartons, two-color cartons, nests that release sleepy chicks in order, bridges between two farms, eggs that hatch after a number of moves and gates opened by a button. A hen mascot reacts to every move; coins buy helpers and feathers hatch 12 special chicks for the collection. 14 interface languages, recorded sound effects and music, no external services.
2 Installation
Extract the ZIP. Open DOCUMENTATION.html for this guide. Upload only the contents of game/
to your static HTTP(S) hosting, keeping all folders beside index.html. Open that address in a browser. No database, PHP, account or Node.js runtime is needed to play. Keep source/ and the full ZIP outside your public website.
3 Requirements and sound
Use a current browser with JavaScript, Canvas 2D, Web Audio and local storage enabled. Mouse and touch are supported. The first click, tap or key press unlocks sound; check browser autoplay settings and the in-game sound controls. Files are bundled locally; normal play makes no request to Polar ranking, advertising or payment services. Host the complete folder; opening game HTML through file:// is not the supported installation method.
4 How to play
Press and drag a carton. It slides cell by cell; a chick of the same color under any part of the carton hops into a free cup. Cartons with arrows only move along their arrows. Some levels have a clock, which starts with your first move. Undo goes back up to 20 moves and Restart replays the level. Helpers unlock as you play: Moon stops the clock for 10 seconds (level 6), Corn calls every chick of a carton's color into it (level 12) and Scissors cut a carton into single cups (level 18). Each helper comes with 3 free uses and then costs coins (60, 120 and 90). Coins come from winning and from full cartons; feathers hatch a new special chick (8 per egg) on the Chicks screen. Settings has music, sound and hen volume, vibration, color symbols for color-blind players, an optional warning when a level can no longer be solved, and the language list.
5 Interface guide
Marks on the screenshot
- Play
- Chick collection
- Settings
Marks on the screenshot
- World name
- Next level to play
- World pages (swipe or arrows)
Marks on the screenshot
- Clock (starts with the first move)
- Helpers: Moon, Corn, Scissors
- Undo
Marks on the screenshot
- Special chick
- Hatch with feathers
Marks on the screenshot
- Volume sliders
- Language
6 Files and customization
All tuning is in src/config.js: carton and chick colors (COLORS), the feel numbers (FEEL), prices and rewards (ECONOMY), the worlds (WORLDS) and the level that introduces each mechanic (FEATURES). Levels are generated: edit the plan in tools/level-plan.mjs (board shape, cartons, colors, mechanics, time) and run npm run levels; the generator writes src/game/levels/world-1.js … world-5.js and stores each level's solution, which npm test replays on the rules engine. Texts are in src/lib/locales/<language>.js; keep placeholders such as {n}. To reskin, replace images in assets/ with the same names and similar proportions; the backgrounds are 1536×2304 (portrait) and 2304×1536 (landscape). Sound files are listed in src/audio/sfx-files.js; music is assets/music/<world>.mp3.
game/ upload these contents
source/ editable source, tests and tools
documentation/index.html offline illustrated guide
DOCUMENTATION.html guide shortcut
THIRD-PARTY-LICENSES/ font license
source/index.html entry page: loads css/ in order and src/main.js
source/css/01..04-*.css styles, loaded in order (later files override earlier ones)
source/src/main.js state, layout, drag input, level loop, start-up
source/src/app/screens.js tap to start, menu, level select, collection, hatching
source/src/app/modals.js settings, new feature, out of time, victory
source/src/app/hud.js top bar, helpers, hints, no-way-out card, undo, coins
source/src/app/render.js drawing of the board, sky and night overlay
source/src/game/rules.js pure rules (no drawing), used by the tests and the solver
source/src/game/levels/ the 100 levels, one file per world (generated)
source/src/game/specials.js the 12 special chicks of the collection
source/src/lib/locales/ one file per language (14)
source/src/render/ canvas art and the effects system
source/src/audio/ sound effects, ambience and music (Web Audio)
source/src/config.js every tuning number: colors, feel, economy, worlds, audio, save key
source/assets/ images (WebP), sounds and music (MP3), font
source/tools/ build.mjs, serve.mjs, generate-levels.mjs, level-plan.mjs
source/test/ node --test tests
7 Languages
The game interface offers 14 languages (English, Portuguese, Spanish, French, German, Italian, Dutch, Polish, Turkish, Russian, Indonesian, Japanese, Korean and Chinese). The game picks the browser language on the first visit and the player can change it in Settings. This guide is in English, Brazilian Portuguese and Spanish; screenshots stay in English. Each language is one file in src/lib/locales/; English fills any missing key. Edit the texts without changing placeholders such as {n}.
8 Local saves
Progress belongs to this browser and origin. This buyer edition uses its own storage namespace, separate from the Polar website game. Clearing site data, using another browser or changing the hosting origin does not transfer progress. Private browsing and blocked storage may prevent persistence. There is no account, online ranking or cloud synchronization.
peep-pack.template.progress levels, coins, feathers, helpers, chick collection, settings
peep-pack.template.lang chosen language
peep-pack.template.music music volume
peep-pack.template.sfx sound effects volume
peep-pack.template.voice hen clucks volume
(prefix set by STORAGE_PREFIX in source/src/config.js)
9 Development
The ready-to-host game in game/ needs no Node.js. The source is plain JavaScript (ES modules), so there is no compile step: npm run build copies index.html, css/, src/ and assets/ into dist/, which matches game/ file by file. Node.js 26.13 or newer is only needed for the tests, the level generator, the local server and Prettier. No server, account, ranking, ads or payments are used.
New to Node.js? 1) Install the LTS version from nodejs.org (Windows or macOS installer) or with your package manager on Linux; it must be 26.13 or newer. 2) Close and reopen the terminal, then run node -v and npm -v to confirm both print a version. 3) Open the terminal inside the source/ folder (the one containing package.json). 4) Run npm ci to install the exact tools from package-lock.json (only Prettier). 5) Run npm test for the tests, then npm run build to write the game to dist/. 6) Try it with npm run serve (http://localhost:5190/; the page needs a web server, it does not run from a double-clicked file), then upload the contents of dist/ like game/. Common errors: node or npm not found (reopen the terminal or fix PATH); on Windows PowerShell, npm.ps1 cannot be loaded (run npm.cmd ci or use Command Prompt); ENOENT package.json (you are not inside source/); EBADENGINE (Node.js is older than 26.13); network or proxy failures during install (check your connection and proxy); npm ci complaining about the lock file (do not edit package-lock.json; delete node_modules and retry).
cd source
npm ci
npm test
npm run build
npm run serve
# http://localhost:5190/
10 Updating and cache
Keep a backup of your edited files before replacing a release. Upload all updated assets together and keep the public URL unchanged to preserve the browser save. Clear hosting or CDN caches when applicable. Test a private window after deployment; adding ?v=2 to the entry URL can help diagnose stale HTML but does not replace updating all assets.
Clearing the cache without losing progress
Progress is stored in this browser, not on the server. Clearing cached images and files, or doing a hard reload, keeps your progress.
Computer: press Ctrl+F5 on Windows and Linux, or Cmd+Shift+R on macOS. Phone: in the browser settings, choose the option to clear cached images and files.
Do not choose cookies and site data, or clear site data, for the game's address. That deletes the local save.
11 Licenses
The game artwork, audio and editable game code are supplied under the purchased item license. Included fonts retain their complete SIL Open Font License notices in game/licenses/ and THIRD-PARTY-LICENSES/. Developer dependencies retain their own upstream licenses. Original production PNG masters and artwork-generation tools are not included.
12 Troubleshooting
If the page is blank, check that every folder was uploaded, the URL is served over HTTP(S), and the browser console and Network panel have no missing files. Module builds need correct JavaScript MIME types. If sound is silent, interact once and inspect browser and game volume. If progress resets, inspect storage permissions and origin changes. The guide itself also opens offline through file://.
13 Support
For support and customization contact willian@polargames.com.br. Include the product version, browser, device, hosting URL, reproduction steps and a screenshot. No backend, native app, ad SDK or real-money purchasing system is included.
Support request
When you write to support, include the browser and device, the game version, the page address, the steps that caused the problem, a screenshot and the first error shown in the browser console. Never send passwords, payment details or secret keys.