Solitaire Potions · Buyer Guide

1 Overview and package contents

Word-category card game in an alchemist's world: 12 worlds, endless levels, stars and combos. Each gold category card fills like a potion bottle, and the potion shelf collects every category you brew. Daily gifts and a daily challenge use local progression.

No native app project, accounts, cloud saves, online ranking or real-money purchases. Coins are earned in play. Ads are optional and off by default; the buyer supplies the provider.

This manual describes version 1.0.0. Open documentation/index.html by double-clicking it. This guide works without internet.

DOCUMENTATION.html
documentation/index.html
game/
source/
THIRD-PARTY-LICENSES/

2 Quick installation by FTP

Installing takes a few minutes. It needs no build step, terminal, database or PHP.

1. Extract the purchased ZIP on your computer.
2. Open the game/ folder. Keep its files and subfolders together.
3. Upload only the contents of game/ by FTP or your hosting file manager to an empty folder, such as public_html/my-game/.
4. Open https://your-domain.example/my-game/ in a modern browser.

3 Requirements and hosting

• A current version of Chrome, Edge, Firefox or Safari on a computer, tablet or phone.
• Any static hosting over HTTP or HTTPS. HTTPS is recommended.
• No npm, terminal, database, PHP, account or build step. The game loads everything from your folder.

The example above uses a subfolder. Keep all files together so the relative paths keep working.

To test before choosing a host, run any static web server on your computer or upload the game to a private test subfolder first.

4 Controls and how the game works

Place gold category cards at the top, then move matching words into them. Stack words of the same category in columns to reveal hidden cards. Draw from the deck when needed. Drag cards, or select a card and its destination.

Use mouse or touch for cards and the deck. Keyboard focus activates buttons with Enter or Space. The helpers are Hint, Undo and Joker; Restart starts the level again.

Each move matters. Complete all categories before moves run out. Stars and combos reward progress. Worlds contain 10 levels; artwork and music repeat after world 12.

5 Screens and controls explained

The captures below are real game screens from version 1.0.0, in English. Numbered marks point to the controls, and the legend under each capture explains them.

1 2 3

Marks on the screenshot

1. 1 Game logo.
2. 2 Play or continue your saved campaign.
3. 3 Settings available

1 2 3 4

Marks on the screenshot

1. 1 Gold category cards.
2. 2 Draw pile and remaining cards.
3. 3 Place gold category cards at the top, then move matching words into them. Stack words of the same category in columns to reveal hidden cards. Draw from the deck when needed. Drag cards, or select a card and its destination.
4. 4 Hint, Undo, Joker and Restart.

1 2

Marks on the screenshot

1. 1 The potion shelf keeps one bottle for every category you complete; tap a bottle to see it. Coins, stars and boosters are earned by playing; the buyer edition has no real-money checkout.
2. 2 Potion shelf

1 2

Marks on the screenshot

1. 1 If silent, interact first, then enable music, sounds and Minty's voice in Settings. Voice recordings only cover English, Portuguese and Spanish. Calm mode reduces motion; Large text enlarges card words.
2. 2 The game and this guide have 14 interface languages. Recorded voices are English, Portuguese and Spanish only. Settings also include music, sound, voice, vibration, Minty, large text and calm mode.

6 Settings available

The game and this guide have 14 interface languages. Recorded voices are English, Portuguese and Spanish only. Settings also include music, sound, voice, vibration, Minty, large text and calm mode.

Browsers need a first interaction, such as pressing Play, before audio can start. The game pauses when it loses focus.

7 Map of the files

8 Customize your copy

Edit solitaire.config.js (in game/, or in source/ and rebuild); no other change is needed. storageKey isolates saved progress; ads.enabled enables your own integrated provider. This setting does not change the illustrated title.

window.SOLITAIRE_CONFIG = {
  storageKey: 'my-word-game.save.v1',
  ads: {enabled:false, graceSec:180, minGapSec:120, startTimeoutSec:2.5, timeoutSec:180}
};

To change the illustrated title, icons, artwork, rules or text, edit the optional source edition and rebuild. Keep the existing proportions when replacing visuals. Do not edit hashed build file names without updating their references.

9 Languages, sound and accessibility

The game and this guide have 14 interface languages. Recorded voices are English, Portuguese and Spanish only. Settings also include music, sound, voice, vibration, Minty, large text and calm mode.

Edit source/i18n/, run npm run langs inside source/ (it rewrites js/langs.js and js/langs/), then npm test and npm run build, and upload the contents of dist/.

10 Saved progress and privacy

Default localStorage key: solitaire-potions.buyer.save.v1. Saves include progress, coins, the potion shelf and settings. No cloud or account. Different subfolders share origin storage, so use a different storageKey for independent installations.

• There is no account and no cloud sync. Records stay on this device.
• Private mode, storage restrictions, clearing site data or changing the address can remove access to saved progress. The game keeps running without saving.

Back up your configuration and exported save before updating. Keep storageKey unchanged to preserve access to progress. Upload all build files together; do not rename hashed assets.

11 Optional advertising

Disabled by default. Integrate your approved SDK and consent. Call started only when visible; resolve done only after confirmed completion. Rewards require both. Cancellation, error or unavailable inventory must not grant rewards. One ad at a time; remove your overlay on timeout.

// Contract for window.SOLITAIRE_AD_PROVIDER (supply your own approved SDK)
// init(): optional setup
// available(kind): boolean
// show(kind, placement, started): Promise<result>
// kind: 'interstitial' | 'rewarded'
// result: 'done' | 'skipped' | 'unavailable' | 'error'
// Call started() only once the ad is visible; cancel if it returns false.
// Resolve 'done' ONLY after a real confirmed completed-view event.
// All other outcomes return without reward; only one ad at a time.
// Default placements:
// level_end, double_reward, extra_moves, stuck_joker, shop_coins, booster
// ads: {enabled:false, graceSec:180, minGapSec:120,
//       startTimeoutSec:2.5, timeoutSec:180, placements:{...}}
// If your SDK times out, close its own overlay.

12 Optional development

This section is only for changing the source. The game/ folder already contains the playable build, so hosting needs no Node.js.

The playable game needs no build. source/ is the complete editable project: edit it, run npm test and npm run build with Node.js 26.13.0 or newer (no dependencies to install); dist/ comes out identical to game/. Internal names kept from the engine: the mascot icon and setting are called linky, her recorded lines use the ids lk*, and CLO (js/closet.js) is an empty closet interface. Renaming them is not needed.

cd source
npm ci
npm test
npm run build
# Only after editing translation JSON files:
npm run langs

13 Updating the game

Back up your configuration and exported save before updating. Keep storageKey unchanged to preserve access to progress. Upload all build files together; do not rename hashed assets.

Upload the new contents of game/ over the old files, keeping the names and folders.

Reload the game. If the old version still appears, clear the cache as described below.

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.

14 Common problems

• Blank page: make sure you uploaded the contents of game/, opened the HTTP(S) address and checked the browser console for scripts that failed to load. The source/ folder is not the playable website.
• Works on the computer but not on the server: the game does not run from a file on your computer (file://). Use a static web host or any static local server.
• Missing textures or sound: confirm the complete upload and the file name case, and that .mp3, .js, .css and font files are served with correct types.

If silent, interact first, then enable music, sounds and Minty's voice in Settings. Voice recordings only cover English, Portuguese and Spanish. Calm mode reduces motion; Large text enlarges card words.

15 Frequently asked questions

16 Support and version history

Self-hosted Baloo 2, Nunito and Fredoka fonts use SIL Open Font License. Keep the complete notices in THIRD-PARTY-LICENSES and game/assets/fonts. No external font service is required.

Support and customization: willian@polargames.com.br. Include your purchase or licence reference. This guide does not promise response times or a schedule of future updates.

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.