Grid-Based Number Merge Puzzle Simulation

Provides tools to simulate, analyse, visualise, and benchmark grid-based number merge puzzles. The package implements generic grid mechanics, tile-spawning rules, merge rules, scoring functions, reproducible simulation utilities, and local 'Shiny' and 'WebGL' interfaces for interactive use. It is intended for teaching, algorithmic experimentation, and game-theoretic examples. The autoplay helpers use standard heuristic search and Monte Carlo simulation ideas described in Russell and Norvig (2021, ISBN:9780134610993) and Robert and Casella (2004, ISBN:9780387212395).

output: github_document: md_extensions: -smart

mergeGridR

mergeGridR is a local R package for generic falling-block number merge puzzle simulation, visualisation, and benchmarking. It combines a Shiny interface, a ggWebGL board renderer, a standalone WebGL applet, and a deterministic Rcpp engine that can also be used directly from R for tests, simulations, and autoplay experiments.

Features

• Shiny app entrypoint with mouse, touch, keyboard, restart, high-score, and autoplay controls.
• WebGL board rendering through ggWebGL.
• Rcpp engine for deterministic drops, gravity, merges, cascades, scoring, tile spawning, and game-over detection.
• Three-or-more tile merge rule: a connected component of size n creates value * 2^(n - 1).
• Dynamic provided tile range from 2 through min(max(board), 256) by default.
• Spawn distributions can be weighted-low, weighted-high, or uniform.
• Configurable preview horizon, defaulting to one upcoming tile.
• Up to three manual continues by default, each clearing the top three rows while preserving score and future spawn eligibility.
• Autoplay strategies: greedy, lookahead, growth_lookahead, and monte_carlo.
• Benchmark helpers for comparing autoplay settings over seeded Monte Carlo game experiments.
• Standalone HTML export for browser-only local play without Shiny or an R session.
• High scores separated by preview horizon.

Installation

Install the development version from GitHub:

# install.packages("pak")
pak::pak("fbertran/mergeGridR")

Or build and install from a local checkout:

R CMD build .
R CMD INSTALL mergeGridR_0.2.0.tar.gz

Launch The App

library(mergeGridR)

run_drop_number()

The side panel includes the preview-horizon selector, next tiles, score, persisted best score for the active horizon, animation toggle, hint, one-step auto move, continuous autoplay, speed-up, instant autoplay, and continue controls after game over. The preview selector applies immediately before the first move; after play starts, the selected value is applied on restart.

Play In Browser

The standalone WebGL applet can be played directly on the pkgdown site. GitHub repository README pages do not render embedded iframes, so use the direct app link when viewing this page on GitHub: open the standalone app.

If the embedded applet does not load, open the standalone app.

Standalone HTML App

For local sharing or browser-only play, export the static app:

out <- file.path(tempdir(), "mergeGridR-static.html")
export_static_app(out, overwrite = TRUE)

The exported file is self-contained and runs without Shiny, Rcpp, or a live R session. Game rules, WebGL drawing, preview horizon, spawn distribution, continues, simple autoplay controls, and high scores all run in the browser. Static-app scores are stored in browser localStorage and are separated by preview horizon.

Use The Engine From R

library(mergeGridR)

state <- new_game(seed = 42)
state <- drop_tile(state, column = 3)

state$board
state$score
state$last_drop

If a state is over and continues remain, continue_game() clears the configured number of top rows without changing score or move count:

state <- continue_game(state)
state$continues_remaining

By default, new_game() previews one upcoming tile. Use next_count to choose a different preview horizon:

state <- new_game(game_config(next_count = 3), seed = 42)
state$next_tiles

Rows are stored bottom-up, so row 1 is the bottom row. The active tile is the tile that was just dropped, or the newly created tile after a cascade. Active tile merges are resolved first; if the active tile is stable, equal horizontal or vertical by-product components elsewhere on the board are then resolved deterministically until the board is stable.

Autoplay

move <- autoplay_move(
  state,
  strategy = "growth_lookahead",
  depth = 3,
  beam_width = 10,
  seed = 1
)

state <- drop_tile(state, move$column)

growth_lookahead is a lookahead search variant that gives extra value to three-or-more tile merges, especially when those merges create larger tiles. It is useful when the goal is to accelerate growth through high-value multi-tile components.

To autoplay a full game:

game <- autoplay_game(
  strategy = "growth_lookahead",
  max_moves = 1000,
  depth = 3,
  beam_width = 10,
  seed = 1
)

game$final_state$score
tail(game$history)

Benchmark Strategies

settings <- autoplay_benchmark_settings("fast")

bench <- benchmark_autoplay_strategies(
  n_games = 5,
  max_moves = 50,
  settings = settings,
  seed = 20260609,
  workers = 1
)

bench$summary

Use workers > 1 to opt into base R PSOCK parallel execution after installing the package into the library used by worker processes.

High Scores

High scores are stored locally under tools::R_user_dir("mergeGridR", "cache") and are separated by preview horizon. For example, preview horizon 1 and preview horizon 3 use different high-score files.

get_high_score()
get_high_score(preview_horizon = 3)

Call reset_high_score() explicitly when you want to clear a local score file.