Counter

Keeps count and shows it in its entity’s Text: a score, coins, kills. Every Message sent adds to it (the number sent along, or 1; or just 1 with OnePerMessage), so it adds up Pickups with no code; scripts can call Add. It can count anything’s output instead (a board’s score, the dungeon floor, a faction’s gold: see Output). When it Reaches a value it sends its ReachMessage and its own output Reached turns on. With SaveBestAs it remembers the highest count ever, between runs.

Works with: Text (shows the count); Trigger (doing something on its Reach Message)

Saved data version: 2 (older scenes are upgraded as they load).

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.

• message: text = “Score”. The message that adds to it, e.g. “Score” for Game.Send(“Score”, 10). Empty only counts Add. (Names a message.) (Field: a name.)
• onePerMessage: true or false = false. Add 1 for each Message, whatever number it sends: a beat clock’s Beat sends the beat’s number (0, 1, 2…), so a counter of beats adds one a beat with this, rather than adding the numbers up. (Field: on or off.)
• value: a whole number = 0. The count now. Set it to start from something other than 0. (Field: a number.)
• format: text = “Score: {0}”. How the text reads: {0} is the count and {1} the best, e.g. “Score: {0}”, “Best: {1}” or “{0:000000}” (and {2} what it’s out of and {3} how many are left, e.g. with the Output “Goals Covered” how many goals there are and how many are still uncovered). Empty shows just the number. (Text with holes the game fills in: {0} the count, {1} the best, {2} what it’s out of, {3} how many are left, each with a number format after a colon if it says, e.g. {0:000}. The Inspector has a button for each and shows how it reads now.) (Field: its own editor: Format.)
• saveBestAs: text = null. A name to keep the best count under in Game.SaveData, e.g. “best”. Whenever the count beats it, it’s saved, so another counter (on a menu, with Format “Best: {1}”) can show it. (Names a name in the save data: this entity’s own, which other fields can name.) (Field: a name.)
• newBestMessage: text = null. A message sent as the count first beats the best kept under SaveBestAs while it’s being played (a new best), with the count as its data, e.g. “New Best”: a sound player plays a sting on it. Not sent while nothing’s been kept yet. (Names a message.) (Field: a name.)
• saveAs: text = null. Keeps the count itself in the game’s save data under this name, e.g. “Coins”, so a counter saved as the same name in the next scene (or a minigame) carries on from it, and so does the next run: coins or a score kept from level to level. Empty keeps nothing. (Names a name in the save data: this entity’s own, which other fields can name.) (Field: a name.)
• loaded: true or false = false. Set by the game once it has taken its count from the save data, so a rewind doesn’t do it again. Leave it be. (Field: on or off.)
• multiplyBy: text = null. Another counter, by name, whose count multiplies what each Message (and the Add action) adds to this one: a score counted double, triple and so on while a “Multiplier” counter says so. Empty multiplies by nothing. (Names an entity.) (Field: an entity’s name.)
• max: a whole number = 0. The most the count goes up to: adding past it stops there, e.g. 5 for a multiplier up to 5x. 0 has no limit. (Field: a number.)
• pop: a number = 1.3. How big the text pops when the count changes, springing back: 1.3 is a little pop, 1 none. (Field: a number.)
• item: text = null. An item to count instead of a message, e.g. “Key”: it shows how many the first Inventory in the scene (usually the player’s) holds. (Names an item.) (Field: a name.)

Counting an Output

• track: text = null. An entity whose Output it counts, by name, e.g. “Board”. Empty is this entity, or the nearest one it’s inside with that output; “*” is the first entity in the scene that has it, wherever it is (a HUD’s counter of the board’s score, the goals covered, the moves taken or the dungeon’s floor). (Names an entity.) (Field: an entity’s name.)
• output: text = null. Count an output instead of a message: whatever it gives, now (see component_describe’s Outputs), e.g. a board’s “Score” or “Moves Left”, a dungeon’s “Floor”, a turn order’s “Round”, a beat clock’s “Beat”, a faction’s “Amount:Gold” or “Units”, another counter’s “Count”. What it’s out of, if it says, is {2} in Format. (Names an output of the entity track names, or without one this entity or the nearest it’s inside with it: one component_describe lists under Outputs, a number or true or false, e.g. “Score”, “MatchBoard.Score” for one component’s, or “Amount:Gold” for one read by a name.) (Field: an output’s name.)

Reaching a Value

• reaches: one of Never, AtLeast, AtMost = “Never”. Do something as the count reaches Reach: once it’s at least that (counting up) or at most that (counting down). It sends ReachMessage each time it gets there, and its output Reached is on while it’s there, for a wire into a door’s Power. (Field: one of its values.)
• reach: a whole number = 10. The count it reaches, e.g. 10 coins, or 0 moves left. (Only used when reaches isn’t Never.) (Field: a number.)
• reachMessage: text = null. A message sent as the count reaches Reach, with the count as its data: a trigger opens a door or a panel on it. Sent again if the count leaves it and comes back. (Only used when reaches isn’t Never.) (Names a message.) (Field: a name.)

State

• bestToBeat: a whole number = -1. The best kept under SaveBestAs as this scene started: what the count has to beat to be a new best. -1 until the game has read it. Set by the game. (Field: a number.)

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”).

• Add (done with a whole number, its amount: a trigger’s with, 1 without one). Adds amount (take some away with a negative amount), times the count of the counter it’s multiplied by (see MultiplyBy), never past its Max.
• Set (done with a whole number, its amount: a trigger’s with, 0 without one). Sets the count to amount, e.g. a multiplier back to 1 as the ball drains.
• Reset. Starts the count again from 0.

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.

• Count (a whole number, out of its total). The count now. Set it to start from something other than 0.
• Reached (true or false). True while the count is at (or past) Reach, the way Reaches says.
• Left (a whole number). How far the count is from Total, never below 0 ({3} in Format): goals left, moves left.
• Best (a whole number). The best count, from SaveBestAs (or this run’s, without it).
• NewBest (true or false). True once the count has beaten the best kept under SaveBestAs as the scene started: a new best.

While the game runs

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

• reached: true or false. True while the count is at (or past) Reach, the way Reaches says.
• total: a whole number. What the count is out of, for a counter that counts goals, a match board’s moves, score or gems ({2} in Format); 0 otherwise.
• left: a whole number. How far the count is from Total, never below 0 ({3} in Format): goals left, moves left.
• best: a whole number. The best count, from SaveBestAs (or this run’s, without it).
• newBest: true or false. True once the count has beaten the best kept under SaveBestAs as the scene started: a new best.

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