About & Research Log

← Back to the game · Hub

Project: 2048 — Combo Edition (by ByJTT). A 1:1 fan clone of the classic 2048 by Gabriele Cirulli (MIT licensed), rebuilt with a unique combo twist, a leaderboard and X sharing, deployed to Vercel, and SEO-optimized. This page documents the entire build for research purposes.

The unique twist: Combo system

In the original 2048, merging two pairs in one move scores exactly the same as merging them one pair at a time. In this clone, merging 2+ pairs in a single move triggers a combo:

Each extra pair merged beyond the first earns a +50 bonus (e.g. 2 pairs = +50, 3 pairs = +100).
Combos on consecutive moves chain — the bonus counter keeps growing until you make a move without a multi-merge.
A live stats bar below the board tracks moves, best combo (largest single bonus), highest tile, and total combo bonus earned.
A floating "Combo! +N" popup appears over the board on every combo move.

The core game remains 1:1 with the original: same 4x4 grid, same merge rules, same tile colors and animations, same 90% / 10% tile spawn odds, same keyboard & touch controls, same win/lose logic, same local-storage persistence, and the same "Keep going" / "Try again" flow.

v2 additions: leaderboard & X sharing

Leaderboard: submit your score with a name; the top 10 are stored in Vercel Blob via a shared serverless function (/api/leaderboard) that any future experiment can reuse. Scores are validated server-side.
Share on X: one-click button that opens the official x.com/intent/post composer prefilled with your score and a link back to the game — no API keys or login required.
Mobile first: the layout is fully responsive down to 320px, with touch input, safe-area spacing, and thumb-friendly buttons.

How it was built (research log)

Everything below is fully documented for reproducibility.

Model & tooling

Model: deepseek-v4-flash-(latest), run with maximum effort inside CommandCode (the AI coding agent CLI).
CommandCode capabilities used: todo tracking (todo_write), web research (web_search), local file exploration (read_file / read_directory / shell_command), writing source files (write_file / edit_file), running a real browser for visual verification (agent-browser + Chrome headless), Node's built-in test runner, and the Vercel CLI for deployment.
Where each capability was used: the full session log is reproduced in the session log below.

The original prompt

"Create a 1:1 clone of a game that you feel 100% confident that you could clone perfectly, in one shot. Do research first on every capability that will assist you in doing this. Prioritize using open-sourced / free assets and already solved problems, reducing our need for custom code etc. So leveraging all tools, libraries, kits, and everything else relative to each aspect."

Follow-up: "Ensure our own unique twist is implemented… fully documented and logged for research purposes. Prompt used also, etc. Deploy it to vercel and SEO optimize it. Ensure we abide by all laws and legal concerns."

Follow-up (v2): "Add integration with leaderboards / x accounts as i'll post it on X.com. Also fix the copywriting… Also we will do this experiment more often so create a vercel app that showcases them all along with their detailed experiments… Ensure all games and experiments are fully mobile first."

Game choice rationale

2048 was chosen because it is the game most likely to be cloned "perfectly, in one shot": its canonical version is open source (MIT), its mechanics are small and precisely specified, it needs no audio, physics, or server, and its visual design is fully defined in a single CSS file. This makes a pixel-perfect, behavior-identical clone achievable with maximum confidence.

Research phase

Sources studied: the official gabrielecirulli/2048 repository (cloned locally): game_manager.js, grid.js, tile.js, html_actuator.js, keyboard_input_manager.js, local_storage_manager.js, index.html, style/main.css, style/fonts/clear-sans.css, and LICENSE.txt.
Mechanics extracted: traversal order and farthest-position algorithm, one-merge-per-pair rule, score = sum of merged values, 2048 triggers win, no-moves-available triggers loss, 90%/10% spawn of 2/4 tiles, two start tiles, best-score and game-state persistence keys (bestScore, gameState).
Visuals extracted: exact hex colors, tile sizes (107px tiles, 15px gaps on desktop; 58px/10px mobile), fonts (Clear Sans via Intel webfonts), animations (100ms slide, 200ms appear/pop, 600ms score float, 800ms message fade), and the 520px responsive breakpoint.
Inputs extracted: arrow keys, WASD, vim HJKL, R to restart, New Game / Try Again / Keep going buttons, touch swipes with a 10px threshold and one-finger rule.
v2 research: Vercel Blob CLI for serverless storage; the official x.com/intent/post share scheme (no API key required).

Assets & licensing (legal compliance)

Game code: derived from the original 2048 (MIT License, © 2014 Gabriele Cirulli). The MIT license requires including the copyright notice — done in LICENSE, and the game is documented as a fan-made educational clone.
Clear Sans font: bundled webfonts come from the original repo, which redistributes Clear Sans under the Apache 2.0 license (© 2012 Intel Corporation). Apache 2.0 permits commercial use and redistribution with attribution — done in style/fonts/LICENSE-ClearSans.txt and on this page.
Icons: favicon.ico and meta/apple-touch-icon.png are part of the MIT-licensed original repo and are reused under MIT terms.
No copyrighted assets, music, or images were taken from any other source. The game is free, contains no ads and no tracking, and collects only the name and score you voluntarily submit to the leaderboard.

Build & verification

Every JS file mirrors the original's structure; the twist was added as isolated extensions (merges counter, comboCount/comboBest/moves state, updateStats/showCombo in the actuator, stats bar + popup in HTML/CSS).
Unit tests: Node's built-in test runner exercises the merge rules, scoring, combo bonuses, win/lose, persistence round-trip, and serialization against a headless DOM shim.
Visual verification: the game is rendered in headless Chrome and screenshotted; a scripted play-through (moves + restart + win-message) confirms behavior.
Deployment: served from the shared hub app at experiments.byjtt.com.

SEO measures

Descriptive title, meta description and keywords; canonical URLs.
Open Graph and Twitter Card tags with a generated og-image.png.
Schema.org VideoGame structured data (JSON-LD).
robots.txt, sitemap.xml, semantic HTML, and fast static hosting.

Session log (capability usage)

Timeline of what was used and when, during the build sessions.

v1 session:
- 1. Planning: todo_write — created the task checklist (research → scaffold → logic → twist → UI → docs → SEO → tests → deploy).
- 2. Research: web_search — found the original repo & license; shell_command (git clone) — cloned the original 2048 source as reference; read_file / read_directory — studied every source file; web_search — verified the Clear Sans font license (Apache 2.0).
- 3. Scaffold: shell_command — created the project structure and copied MIT/Apache-licensed assets (fonts, favicon, icons); sips — generated the Open Graph image.
- 4. Implementation: write_file — wrote tile.js, grid.js, local_storage_manager.js, keyboard_input_manager.js, html_actuator.js, game_manager.js, index.html, main.css, clear-sans.css, application.js; edit_file — added the move counter and combo wiring.
- 5. Documentation: write_file — about.html (this page), README.md, LICENSE, font license notice.
- 6. SEO: write_file — robots.txt, sitemap.xml.
- 7. Testing: shell_command (node --test) — unit tests; Chrome headless — screenshot + scripted play-through verification; agent-browser — live keyboard/restart/UI checks.
- 8. Deployment: shell_command (vercel) — deploy to Vercel.
v2 session (hub, leaderboard, X share, mobile-first):
- Probed Vercel CLI (blob/storage) to choose the leaderboard backend; reused the MIT-licensed icons for the hub.
- Restructured into a monorepo hub (games/2048/ + root index), wrote the hub page and README "how to add an experiment" guide.
- Removed all out-of-scope name references from copy, meta, docs and code comments; rebranded to 2048 — Combo Edition.
- Wrote the serverless leaderboard API (api/leaderboard.js, @vercel/blob) and the mobile-first leaderboard client + X share button (official intent scheme).
- Added mobile-first CSS for the new UI; updated SEO files for the new paths; re-ran unit tests; verified live in a real browser.

Legal: This is a free, non-commercial fan project made for educational and research purposes. "2048" is a game concept popularized by Gabriele Cirulli, whose original code is MIT licensed; this clone is derived from and credits that code. Clear Sans is a trademark of Intel Corporation, licensed under Apache 2.0. See LICENSE and style/fonts/LICENSE-ClearSans.txt.