## PROJECT OVERVIEW

Doing a timeboxed game jam. Will get something running, iterate a bit, and then turn to the corner to polish and ship.

## TECHNICAL APPROACH

Building on a base starter kit that uses the js library boardgame.io and the plugin for it called bgio-effects.  When working on tasks that require more information about this, you can refer to dev-docs\BestPractices.md for the overall approach. I've also made the reference docs available at reference-docs\boardgamio-docs.txt

On top of this game layer, we have a React front-end.

Game has two main layers: 1. the game layer (in src\game), 2. the UI layer (mostly in src\components).  The most important design rule is to maintain the separation of these concerns.  The game layer defines the rules and controls the state of the game.  The UI layer displays that state and has user inputs (eg buttons) that let the player execute game moves.  bgio-effects provides the mechanism for the game logic to raise events which the UI code can listen to for special effects.

# TERMINOLOGY

This game uses a grid.
The grid is composed of cells.
Cells can be empty, or they can have a tile inside them.
Types come in various types.

# GAME DESIGN

The player's job is to collect metal out of a pile of trash moving past on a conveyor belt toward an incinerator.

The game is turn-based, and takes place on a grid of squares.

The player will get to take one action, and then the conveyor belt will advance, moving every tile on the grid forward one cell toward the incinerator at the end.  Tiles reaching the incinerator are destroyed.

## PLAYER ACTIONS

The player has a set of tools.
Each tool has a button.
Tools come in two varieties: targeted, and untargeted.
To use an untargeted tool, the player clicks the button in the UI layer and the tool's move command is sent to the game.
To use a targeted tool is a two-step process:
1. The player clicks the button and enters a "target selection" mode.  A cancel button (or other control) becomes available.  Ideally, both the tool selected and the legal targets are highlighted.
2a. If the player clicks the cancel button, no command is sent and the player exits target selection mode.
2b. If the player clicks a valid target, the tool's move command is sent to the game (and the player exits target selection mdoe).

### Reset

Once the player uses a tool, it becomes "used" and is not available to be used again, until the player uses the "reset" tool.  This mechanism is inspired by the board game Concordia.

The player will have to take a turn off at some point to use the reset.

### Example tools

1. Grabber: grabs a single tile
2. Magnet: runs over a row (col?) and grabs the first metal tile(s) it passes over.

[For Later] The player earns money and upgrades their tools, for example the magnet can pick up 1 tile per sweep at the begining but can upgrade capacity.

## THE GRID

On the grid's turn, it simply advances forward.

But I am not sure of the best orientation for the grid.

We will start with a vertical grid, with tiles spawning at the top row and moving down.  But we might decide to try a horizontal movement at some point.

Start with a grid 7 cols wide and 10 rows tall.

# Animation-wait problem

In a turn-based game, it's important to be able to convey information about things moving from one state to another.

Specifically in this game it will be good to animate tiles moving from one cell to another, or to animate the magnet sweeping across a row.

We are supposed to be able to use the bgio-effects library to accomplish this.

The bgio-effects docs say this:

```
Sequencing effects
You can add timing information to your effects to sequence them on the client. By default, effects have a duration of 0 and are added to the end of the timeline in the order they are called, which means they will all trigger together as soon as the game state updates.

You can set an alternative default duration for each effect in its config object:

{
  effects: {
    longEffect: {
      duration: 5,
    },
  },
}
Now an effect called after longEffect will be added to the timeline 5 seconds after longEffect by default. For example:

0  .  .  .  .  5  .  .  .  .  10
↑              ↑
longEffect     nextEffect
```

But when I tried to use this in the past, I had a really tricky problem...
The game would not wait for the bgio-effects to complete their duration (animating the player) before executing the next turn (and thus updating the display).  This caused moves that were apparently configured to wait for each other to instead overlap.

There is a specific option to prevent this in bgio-effects, called updateStateAfterEffects, described here in the docs:

```
const board = EffectsBoardWrapper(BoardComponent, {
  // Delay passing the updated boardgame.io state to your board
  // until after the last effect has been triggered.
  // Default: false
  updateStateAfterEffects: true,

  // Global control of the speed of effect playback.
  // Default: 1
  speed: 1,
});
```

I was setting updateStateAfterEffects to true but it was still not working.

I ended up giving up on complex impactful animations.

But I hope in this project we can sort that out, without spending much time.

# PLAN

This plan is incremental.  We will add to it as we go through the steps.

Milestone 1: Basic grid of trash with two grabber actions and a reset.  No art, just colors on tiles and words on buttons.

[DONE] TODO-1: Basic Grid: Refactor the existing grid game into this trash-grid.  Get the right shape.  Get the tile-types trash and metal into place. Display trash as low-saturation brown and metal as silver. Give the player a "pass" button only, and let them advance the grid.

[DONE] TODO-2: Basic Tools: Add a simple grabber tool which can select any cell and grab that item.  Add a Metals count variable to the game state, and display it on a top corner.  The grabber doesn't yet have the used state and there is no reset yet.

[DONE] TODO-3: Add used/reset for tools: introduce reset button on the left side of the user's actions button list.  Now the grabber will become used, and can't be used again until it is reset.

[DONE] TODO-4: Add magnet tool: Give the player a new magnet tool. Expand the horizontal area of display for the whole game. This will make room for a small button on either side of each row, which are the magnet launch targets.  When in target selection mode for the magnet tool, the user can click any of those buttons. If player does, the magnet sweeps across that row, starting from the side of the selected target, sweeping across the row to the other side and picking up only the first metal it encounters in that row.

TODO-5: Animate the sweeping of the magnet across the row.
References:
    src\components\Board.jsx line 133 is where we instantiate the EffectsBoardWrapper from bgio-effects, and can set the option updateStateAfterEffects to true.   (Currently commented out)

