---
output:
  github_document:
    md_extensions: -smart
---

<!-- README.md is generated from README.Rmd. Please edit that file. -->



# mergeGridR

<!-- badges: start -->
[![R-CMD-check](https://github.com/fbertran/mergeGridR/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/fbertran/mergeGridR/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

`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:


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

Or build and install from a local checkout:


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

## Launch The App


``` r
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](https://fbertran.github.io/mergeGridR/static/mergeGridR.html).

<iframe
  src="static/mergeGridR.html"
  title="mergeGridR standalone WebGL game"
  width="100%"
  height="780"
  loading="lazy"
  style="border: 1px solid #d0d7de; border-radius: 8px; max-width: 1100px; background: #0f172a;"
></iframe>

If the embedded applet does not load, open
[the standalone app](https://fbertran.github.io/mergeGridR/static/mergeGridR.html).

## Standalone HTML App

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


``` r
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


``` 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:


``` r
state <- continue_game(state)
state$continues_remaining
```

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


``` r
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


``` r
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:


``` r
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


``` r
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.


``` r
get_high_score()
get_high_score(preview_horizon = 3)
```

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