MatchBoard

A match-3 board, with no code: the gems are the tiles of its entity’s Tilemap, one kind per tile number in Gems. Drag a gem onto a neighbor (or click one, then the other) to swap them; three or more of a kind in a row or column clear, the gems above fall into the gaps, new ones drop in from the top, and whatever lines up as they land clears too, a chain. With keys or a gamepad, the arrows move a cursor, the PickAction (Space, the gamepad’s A) picks a gem up and an arrow swaps it that way.

Part of the Match-3 module: Boards of gems swapped into lines of three or more of a kind that clear (MatchBoard), levels with moves and goals, the Match-3 template, and Create Match Board in the Entity menu.

The board is Columns by Rows cells from the tilemap’s top left. Empty cells are filled with gems as the game starts, and tiles that aren’t gems are fixed blocks: they don’t move or match, gems stop on them, and the cells under one are filled from just under it. Without a tileset image each gem kind draws as a square of its own color. The tiles are saved with the scene, so a rewind goes back to how the board was (the slides and falls under way start again from there). In a network game the host runs the board and any player can swap.

Each gem cleared scores Points, more along a chain. Give it Moves, a TargetScore or gems to Collect and it’s a level: met goals send the WinMessage, moves run out first the OutOfMovesMessage, and either way no more swaps are taken.

Requires: Tilemap (holds the gems)

Works with: Counter (shows the score (Message “Score”), the moves left (Output Moves) or the gems of a kind cleared (Output Cleared:1))

Takes the player’s input only while it has focus (its Controllable): its Focus action hands it the input and takes it from everything else the same player plays.

Draws itself, along with the rest of its entity (it doesn’t set the entity’s draw order).

In a network game, it also sends values of its own besides its properties.

Properties

Each is listed as its key in the scene file and the MCP tools, then its kind of value, its default and what it does.

columns: a whole number = 8. Cells across. (Field: a number.)
rows: a whole number = 8. Cells down. (Field: a number.)
gems: text = “0-5”. The tile numbers that are gems, each its own kind: numbers and ranges, e.g. “0-5” for six kinds. Any other tile on the board is a fixed block. (Tiles of the tilemap’s tilesets by number (the first tileset’s from 0, the next’s from 100, then 200…): a string of numbers and ranges like “10-15, 20”, or for a whole number one tile. The Inspector shows the tiles to click.) (Field: its own editor: Tile Numbers.)
matchLength: a whole number = 3. How many of a kind in a row (or column) clear. (Field: a number.)
deal: true or false = true. Deal a fresh board each time the game starts, with no matches already made, keeping the blocks where they are. Untick it to play the gems as painted: a level laid out by hand (empty cells are still filled). It unticks itself once the board is dealt, so a rewind keeps the board it goes back to. (Field: on or off.)
seed: a whole number = 0. Picks the gems dealt and dropped in: the same number always gives the same ones. 0 is different each game. (Field: a number.)
paused: true or false = false. True while it stands still: nothing moves, falls or clears, and it takes no swaps. Its Pause and Resume actions set it. (Field: on or off.)
controllable: true or false = true. Untick it to have the board ignore the mouse, keys and gamepad while it plays on: another part of the scene has the player’s input (a platformer around an arcade cabinet). Its Focus action ticks it and unticks it on everything else the player plays, and the player’s own Focus gives the input back. (Field: on or off.)
swaps: a whole number = 0. How many swaps have been made (not counting those that slid back). Saved with the scene, so a rewind takes them back. (Field: a number.)

Score and Goals

points: a whole number = 10. Points for each gem cleared, times how far into the chain it clears: gems in the second clear after a swap score double, the third triple. 0 keeps no score. (Field: a number.)
score: a whole number = 0. The points scored so far. Saved with the scene, so a rewind takes them back. (Field: a number.)
moves: a whole number = 0. How many swaps the player gets: once they’re used up and the board comes to rest, the level is over (won if its goals are met, lost if not). 0 is no limit. (Field: a number.)
targetScore: a whole number = 0. A score that wins the level once it’s reached. 0 is no score to reach. (Field: a number.)
collect: text = null. Gems to clear to win the level, as kind:count pairs, e.g. “0:20, 3:15” for 20 of tile 0 and 15 of tile 3. With a TargetScore too, both have to be done. (Tiles and how many of each, as tile:count pairs separated by commas, e.g. “0:20, 3:15” for 20 of tile 0 and 15 of tile 3. The Inspector lists them a row each, the tile picked off the tileset.) (Field: its own editor: Tile Counts.)
cleared: text = null. How many of each kind have been cleared so far, as kind:count pairs like Collect. Saved with the scene, so a rewind takes them back. (Plain text: how many of each gem have been cleared: the game counts it.) (Field: text.)

Rules

onlyMatchingSwaps: true or false = true. A swap that lines nothing up slides back. Untick it to let any two neighbors swap. (Field: on or off.)
refill: true or false = true. New gems drop in from the top to fill the gaps. Untick it for a board that empties out as it’s cleared. (Field: on or off.)
shuffleWhenStuck: true or false = true. When no swap would line anything up, the gems are shuffled (into a board with no matches but a move to make). (Field: on or off.)
pickAction: text = “Jump”. The input action that picks up the gem under the cursor: “Jump” is Space or the gamepad’s A. Empty only uses the mouse. (Names an input action.) (Field: a name.)

Motion

swapTime: a number = 0.15. Seconds a swap takes. (Field: a number.)
clearTime: a number = 0.2. Seconds matched gems take to shrink away. (Field: a number.)
fallTime: a number = 0.12. Seconds a gem takes to fall one cell. Longer falls speed up as they go, as things falling do. (Field: a number.)

Look

background: a color, “#RRGGBB” or “#RRGGBBAA” = “#10141CB0”. A color drawn behind the board’s cells. Transparent draws nothing. (Field: a color.)
highlight: a color, “#RRGGBB” or “#RRGGBBAA” = “#FFFFFF50”. The color of the picked-up gem’s cell and the keyboard cursor. (Field: a color.)

Sound and Messages

swapSound: text = null. A sound played as two gems swap, e.g. “Sounds/swap.wav”. (A sound in Assets, e.g. “Sounds/hit.wav”.) (Field: a sound.)
matchSound: text = null. A sound played as gems clear (once however many lines go at once). (A sound in Assets, e.g. “Sounds/hit.wav”.) (Field: a sound.)
noMatchSound: text = null. A sound played when a swap lines nothing up and slides back. (A sound in Assets, e.g. “Sounds/hit.wav”.) (Field: a sound.)
shuffleSound: text = null. A sound played as a stuck board is shuffled. (A sound in Assets, e.g. “Sounds/hit.wav”.) (Field: a sound.)
matchMessage: text = “Match”. A message sent with Game.Send as gems clear, with how many as its data: a Counter listening for it adds them up. (Names a message.) (Field: a name.)
chainMessage: text = null. A message sent as a chain goes on (the second clear and on after one swap), with how long it is so far as its data. (Names a message.) (Field: a name.)
settledMessage: text = null. A message sent once the board comes to rest after a swap, with how many clears the swap set off as its data. (Names a message.) (Field: a name.)
shuffleMessage: text = null. A message sent as a stuck board is shuffled, with this entity as its data. (Names a message.) (Field: a name.)
scoreMessage: text = “Score”. A message sent as gems clear, with the points they scored as its data: a Counter listening for it (its Message is “Score” to begin with) shows the score. (Names a message.) (Field: a name.)
winSound: text = null. A sound played when the level is won: its goals met, once the board comes to rest. (A sound in Assets, e.g. “Sounds/hit.wav”.) (Field: a sound.)
outOfMovesSound: text = null. A sound played when the moves run out with the goals not met. (A sound in Assets, e.g. “Sounds/hit.wav”.) (Field: a sound.)
winMessage: text = “Level Complete”. A message sent once the goals are met and the board comes to rest, with this entity as its data: a panel with this as its Open Message shows the level is won. (Names a message.) (Field: a name.)
outOfMovesMessage: text = “Out of Moves”. A message sent once the moves run out with the goals not met and the board comes to rest, with this entity as its data. A board with no goals sends it too: the end of a game played for score. (Names a message.) (Field: a name.)

Actions

What anything can make it do with no code: a Trigger’s do when its message arrives, a Contraptions Wire’s input as its signal comes on, a script’s Game.Do(entity, “Name”).

Shuffle. Shuffles the gems at the start of the next frame, as a stuck board is.
Pause. Stops the board where it is: nothing moves, falls or clears, and no swaps are taken, until it’s resumed.
Resume. Lets a paused board go on.
Restart. Starts the board over at the start of the next frame: a fresh deal (blocks stay), no swaps, score or gems cleared.
Focus. Gives its entity the player’s input: whatever there and inside it has focus, and everything else the same player plays loses it (a platformer’s player stops on the arrow keys while a board takes them).

Outputs

What anything can read with no code: a Counter’s, Bar’s or Text’s output, a Contraptions Wire’s output as its signal; Text shows names too, the rest read numbers, true as 1.

Swaps (a whole number, out of its moves). How many swaps have been made (not counting those that slid back). Saved with the scene, so a rewind takes them back.
Moves (a whole number, out of its moves). The swaps made, as a puzzle’s moves are counted: the same as Swaps, out of Moves.
Score (a whole number, out of its targetScore). The points scored so far. Saved with the scene, so a rewind takes them back.
MovesLeft (a whole number). How many swaps are left of Moves: 0 once they’ve run out, -1 with no limit.
Chain (a whole number). How many clears the last swap has set off so far: 1 for a plain match, more for a chain.
Cleared (a whole number, read by a kind after a colon, e.g. “Cleared:1”, out of its toCollectOf). How many gems of the kind named kind (a tile number, e.g. “1”) have been cleared. Read as “Cleared:1”, out of how many Collect asks for.

While the game runs

Not saved with the scene; scripts read them, and entity_get shows them as live while the game plays.

movesTaken: a whole number. The swaps made, as a puzzle’s moves are counted: the same as Swaps, out of Moves.
movesLeft: a whole number. How many swaps are left of Moves: 0 once they’ve run out, -1 with no limit.
goalsMet: true or false. True if the board has goals (a TargetScore or gems to Collect) and they’re all met.
isOver: true or false. True once the level is over, won or out of moves: no more swaps are taken.
isBusy: true or false. True while gems are swapping, clearing or falling: swaps wait until it’s still.
chain: a whole number. How many clears the last swap has set off so far: 1 for a plain match, more for a chain. (Sent in a network game.)
picked: [x, y], whole numbers or null. The cell of the gem this machine’s player has picked up to swap, or null.
cursor: [x, y], whole numbers or null. The cell this machine’s player’s keyboard cursor is on, or null while they use the mouse.

Scripts use it as MatchBoard: its methods, events and values that aren’t saved with the scene.